Importação: external_id
Contatos, empresas, negócios, tarefas e agenda aceitam um campo external_id — o id daquele registro na sua base de origem (o outro CRM, a planilha, o sistema…
Contatos, empresas, negócios, tarefas e agenda aceitam um campo external_id — o id daquele
registro na sua base de origem (o outro CRM, a planilha, o sistema legado). É o que permite provar,
depois de migrar, que nada se perdeu e que rodar a carga de novo não duplica.
- Até 255 caracteres, único por conta e por tipo de registro — o mesmo
external_idpode existir emcontactse emdealsao mesmo tempo (são catálogos separados), e pode se repetir em contas diferentes (o índice nunca compara entre clientes). - Rodar a carga de novo é seguro. Mandar de novo o mesmo
external_idnumPOSTdevolve409 external_id_conflict, comexisting_idno corpo do erro — o id do registro que já existe. Seu script de importação usa esse id em vez de criar um segundo registro para a mesma origem. - Filtre por ele pra conferir a migração.
GET/api/contacts?external_id=crm-legado-482(troque o recurso e o valor) devolve só aquele registro — ou lista vazia se ainda não migrou. É assim que você prova, ao vivo, que um id da base antiga chegou ao Salos. - Definir depois de criar funciona uma vez só. Um
PATCHpode gravarexternal_idnum registro que nasceu sem ele (por exemplo, criado pela tela antes de você existir como integração) — mas não pode TROCAR umexternal_idque já está gravado. Tentar troca devolve409 external_id_immutable. - Registro legado (criado antes desta frente existir) devolve
external_id: nullnoGET— e continua editável normalmente. - O ensaio (
?dry_run=true) também avisa o conflito, sem gravar nada — ver §26.
Produtos também têm um campo
external_id, mas com outra regra. Nele é só um código de referência (por exemplo, o código do produto no seu ERP): não é único, pode ser trocado porPATCHe não é filtro deGET/api/products. Para reexecutar uma carga de produtos sem duplicar, use oIdempotency-Key(§5) e o SKU, que é único na conta (409se repetir).
# Prova que o cliente 482 do sistema antigo chegou ao Salos como contato:
curl "https://app.salos.com.br/api/contacts?external_id=crm-legado-482" \
-H "Authorization: Bearer $SALOS_API_KEY"