Importar uma base de outro CRM
Este roteiro é para quem está trazendo a base inteira de um cliente — um outro CRM, uma planilha, um sistema legado — para dentro do Salos pela API. É a soma…
Este roteiro é para quem está trazendo a base inteira de um cliente — um outro CRM, uma planilha, um sistema legado — para dentro do Salos pela API. É a soma de tudo que já foi dito neste documento, na ordem em que dá menos dor de cabeça pra seguir.
A ideia central: external_id
Todo registro que você cria carrega, se você mandar, o external_id — o id que aquele registro
tinha na base de origem (seção 27). É ele que resolve os dois problemas de toda migração:
- "Rodei de novo, e agora?" Mandar o mesmo
external_idde novo devolve409 external_id_conflictcomexisting_idno corpo, em vez de criar um segundo registro. Um script de importação bem-feito trata esse409como sucesso ("já existe, seguir para o próximo"), não como falha. - "Perdi alguma coisa?"
GET/api/<recurso>?external_id=<id-de-origem>prova, um a um ou em lote com um script, que cada registro da base antiga chegou ao Salos.
Grave o external_id em TUDO que aceitar — contato, empresa, negócio, tarefa e
compromisso da Agenda (anotação não tem external_id — veja o passo 7). É o que faz a
migração inteira ser re-executável com segurança: se cair no meio, rode o script de novo do
zero. Os registros já criados voltam como 409/already exists, não como duplicata.
Ordem recomendada
Cada passo depende dos anteriores (negócio referencia empresa e contato; anotação referencia o
registro-pai) — pular a ordem faz um passo mais à frente falhar por company_id/contact_id
inexistente.
Catálogos.
POST/api/deal-sources(§9.2) ePOST/api/loss-reasons(§9.3) — as origens e motivos de perda que osource/loss_reason_iddo negócio vão referenciar.sourcesó aceita texto que já existe no catálogo; criar o negócio antes do catálogo é400.Campos personalizados — as definições.
POST/api/custom-fields(§28) para cada campo que a base de origem tinha e o Salos não tem de fábrica (CPF, código do ERP, plano contratado…). Depois disso,custom_fieldsno corpo de contato/empresa/negócio já sabe reconhecer a chave.Empresas.
POST/api/companiesouPOST/api/companies/batch(§8, §14), comexternal_id, os 14 campos cadastrais que a base antiga tiver,tag_idsecustom_fields.Contatos.
POST/api/contacts/batch(§7), comcompany_idapontando para a empresa já migrada no passo 3 (resolva peloexternal_iddela, com umGET ?external_id=se seu script não guardou o id novo em memória).Negócios.
POST/api/deals/batch(§9), comcompany_id,contact_ids[](até 200, §9.4),source,loss_reason_id(negócio já perdido),custom_fields,stagee — pro negócio já ganho ou perdido —actual_close_date(comimport:write; não dá pra corrigir depois). A criação não aceitacolumn_id: pra reconstituir a etapa exata, mande umPATCHcomcolumn_idem seguida (leia "stage×column_id" antes deste passo — importar histórico é o caso de uso que essa seção descreve).Tarefas.
POST/api/tasks/batch(§10), incluindo a que já nasceu concluída (status: "done"+completed_at, precisa deimport:write).Anotações.
POST/api/{contacts,companies,deals}/{id}/notes(§7.1), comauthor_idouauthor_nameeattachments, tudo atrás deimport:write(§7.1). É o último passo porque toda anotação pertence a um registro que já precisa existir. ⛔ A data original (created_at/updated_at) só é aceita na anotação de contato; nas de empresa e negócio ela é400 unknown_field, e a anotação fica com a data da importação.Anotação não tem
external_id. Ao contrário de contato/empresa/negócio/tarefa, não há um id de origem pra filtrar depois nem pra proteger uma reexecução. Use aIdempotency-Key— uma chave determinística por anotação (por exemplo, derivada do id dela na base de origem) faz a segunda passagem devolver a MESMA anotação em vez de criar uma cópia.
Não convertemos usuário/vendedor pela API (cada aceite de convite ocupa uma licença paga). Cadastre a equipe na tela antes do passo 5, e resolva
owner_id/assigned_topelos ids que a tela mostra em Configurações → Usuários (GET/api/users, §18, lista quem já está cadastrado).
?dry_run=true antes de cada passo
Ensaie o passo inteiro (ou um lote representativo dele) com ?dry_run=true (§26) antes de
gravar de verdade — é como pegar erro de mapeamento de campo, company_id errado ou tipo de
campo personalizado incompatível sem sujar a base com registro pela metade. Confira a §26.1
antes de confiar cegamente num ensaio verde: em POST/api/leads e em POST/api/leads/batch,
por exemplo, o ensaio não antecipa a deduplicação por telefone/e-mail.
Os erros que você vai ver, e o que fazer com cada um
| Erro | Quando aparece | O que fazer |
|---|---|---|
400 unknown_field |
O corpo mandou uma chave que a API não reconhece — nome de campo do CRM de origem que não tem equivalente aqui | A mensagem nomeia a chave recusada. Remova-a do corpo, ou mapeie para custom_fields se o dado precisa ser preservado (§28) |
409 external_id_conflict |
Você já migrou este registro (mesmo external_id, mesma conta, mesmo tipo) |
Não é falha. O corpo traz existing_id — use-o em vez de criar um segundo registro. É o sinal de que rodar de novo está funcionando como deveria |
409 external_id_immutable |
Um PATCH tentou trocar o external_id de um registro que já tinha um gravado |
external_id só DEFINE uma vez. Se o id de origem mudou, é um registro diferente do lado de lá — confirme antes de insistir |
400 forbidden_import_field |
O corpo mandou created_at/updated_at, author_id/author_name/attachments (em anotação), completed_at (em tarefa) ou actual_close_date (em negócio) sem a chave ter o escopo import:write |
Peça uma chave nova com import:write somado ao :write do recurso (§24) — os dois juntos, um não substitui o outro |
409 cnpj_conflict |
A empresa que você está criando já existe na conta com o mesmo CNPJ | O corpo traz existing_id. Mesma lógica do external_id_conflict: reuse o id, não crie de novo |
409 de catálogo (origem ou motivo de perda repetido) |
POST/api/deal-sources ou POST/api/loss-reasons com um nome que já existe (ignorando acento/caixa) |
O corpo traz existing_id — use-o no source/loss_reason_id do negócio em vez de recriar o catálogo |
409 conflict (telefone de contato / nome de empresa repetido) |
A base de origem tem duplicata que o Salos recusa por regra própria | Decida do seu lado: é o mesmo cliente com dois registros na base antiga (reuse o existing_id), ou dois clientes com telefone/nome coincidente (mude o dado antes de reenviar) |
Leia a §26.1 antes de confiar 100% num
dry_run verde — algumas rotas (leads, mensagem de conversa) confirmam menos do que a
gravação de verdade confirma, e a tabela lá lista exatamente o que falta em cada uma.