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_id de novo devolve 409 external_id_conflict com existing_id no corpo, em vez de criar um segundo registro. Um script de importação bem-feito trata esse 409 como 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.

  1. Catálogos. POST/api/deal-sources (§9.2) e POST/api/loss-reasons (§9.3) — as origens e motivos de perda que o source/loss_reason_id do negócio vão referenciar. source só aceita texto que já existe no catálogo; criar o negócio antes do catálogo é 400.

  2. 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_fields no corpo de contato/empresa/negócio já sabe reconhecer a chave.

  3. Empresas. POST/api/companies ou POST/api/companies/batch (§8, §14), com external_id, os 14 campos cadastrais que a base antiga tiver, tag_ids e custom_fields.

  4. Contatos. POST/api/contacts/batch (§7), com company_id apontando para a empresa já migrada no passo 3 (resolva pelo external_id dela, com um GET ?external_id= se seu script não guardou o id novo em memória).

  5. Negócios. POST/api/deals/batch (§9), com company_id, contact_ids[] (até 200, §9.4), source, loss_reason_id (negócio já perdido), custom_fields, stage e — pro negócio já ganho ou perdido — actual_close_date (com import:write; não dá pra corrigir depois). A criação não aceita column_id: pra reconstituir a etapa exata, mande um PATCH com column_id em seguida (leia "stage × column_id" antes deste passo — importar histórico é o caso de uso que essa seção descreve).

  6. Tarefas. POST/api/tasks/batch (§10), incluindo a que já nasceu concluída (status: "done" + completed_at, precisa de import:write).

  7. Anotações. POST/api/{contacts,companies,deals}/{id}/notes (§7.1), com author_id ou author_name e attachments, tudo atrás de import: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 a Idempotency-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_to pelos 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.