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_id pode existir em contacts e em deals ao 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_id num POST devolve 409 external_id_conflict, com existing_id no 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 PATCH pode gravar external_id num registro que nasceu sem ele (por exemplo, criado pela tela antes de você existir como integração) — mas não pode TROCAR um external_id que já está gravado. Tentar troca devolve 409 external_id_immutable.
  • Registro legado (criado antes desta frente existir) devolve external_id: null no GET — 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 por PATCH e não é filtro de GET/api/products. Para reexecutar uma carga de produtos sem duplicar, use o Idempotency-Key (§5) e o SKU, que é único na conta (409 se 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"