Trazer a sua base de clientes sem criar duplicados

Quem chega de outra plataforma quase sempre traz a mesma pergunta: como subir milhares de cadastros de uma vez sem acabar com o mesmo cliente repetido três vezes. A resposta curta é que a carga é feita pela API, e que a chave que evita duplicidade é o id do seu sistema de origem, não o documento nem o e-mail.

O caminho: a API de clientes

A carga usa o endpoint POST /clients/upsert. Ele é do tipo cria ou atualiza: você manda o cadastro e informa de onde ele veio, com dois campos obrigatórios.

  • source: um apelido para o sistema de origem, em letras minúsculas. Exemplo: erp, sistema_antigo.
  • external_id: o id daquele cliente no sistema de origem.

A plataforma procura, dentro da sua conta, um cliente com esse mesmo par. Achou, atualiza. Não achou, cria. Rodar a mesma carga duas vezes não gera duplicado, o que deixa a importação segura para repetir: se a rede cair no meio, é só rodar de novo.

A resposta diz o que aconteceu com cada registro: 201 quando criou, 200 quando atualizou.

Para gerar a chave de acesso e ver o formato completo do corpo da requisição, com todos os campos aceitos, use a documentação da API em Administração › Aplicativos › API. A referência de cada endpoint fica na página de documentação da sua plataforma, em /docs/api.

Levar junto a origem do cliente

Se o seu sistema guarda de onde o cliente veio, mande isso no campo attribution. Assim os relatórios de marketing mostram o canal e a campanha desses cadastros, como fazem com quem chega pelos formulários.

  • utm_source, utm_medium, utm_campaign, utm_term e utm_content: os parâmetros da campanha.
  • gclid, gbraid, wbraid e fbclid: o identificador do clique no anúncio, que permite devolver a conversão ao Google Ads ou à Meta.
  • landing_page e referrer: a página em que a pessoa entrou e o site de onde ela veio.

Vale o primeiro toque: a origem é gravada uma vez e não muda mais, mesmo que a sincronização mande o cadastro de novo com outra campanha. Cadastro que chega com o campo attribution sem nenhum parâmetro fica com a origem Direto.

Travar os campos que vêm do seu sistema

Quando o seu sistema é quem manda em um dado (o nome, o documento, o e-mail, o plano), vale dizer isso à plataforma. Mande no mesmo envio o campo managed_fields com a lista desses campos. Campo personalizado entra como custom. seguido da chave dele, por exemplo custom.plano. Em managed_by vai o nome que a equipe vai ler no aviso, como Sistema de gestão.

A partir daí, quem usa a tela vê esses campos com um cadeado e a frase de que eles vêm da integração. Ninguém troca o e-mail aqui para depois descobrir que o seu sistema continua com o antigo: a correção é feita na origem, e o próximo envio já traz o valor novo. Só a sua integração, com a chave de API, continua escrevendo nesses campos.

Algumas regras do envio:

  • Campo que não vem no envio continua como está. Campo enviado vazio (null) é apagado aqui, o que deixa os dois lados iguais quando o dado some na origem.
  • Mandar managed_fields vazio solta os campos: eles voltam a ser editáveis na tela.
  • Os negócios aceitam a mesma lista ao criar e ao atualizar, com campos como amount (valor) e stage (etapa). É o jeito de o valor de uma venda paga no seu sistema não mudar por aqui.

Ver se os dados estão chegando

Em Administração › Aplicativos › API, a aba Sincronização mostra, para cada chave, quando chegou o último envio, quantos cadastros chegaram hoje e nos últimos sete dias, e quantos foram recusados. As recusas aparecem embaixo com o campo e o motivo, por exemplo um e-mail que não existe. Quando houver recusa nas últimas 24 horas, a aba avisa no topo.

Por que a chave não é o CNPJ

É a parte que mais surpreende, então vale explicar. Documento e e-mail não são usados para casar cadastros, e é de propósito.

Um mesmo CNPJ aparece legitimamente em mais de um cadastro: matriz e filial, o contador que abre chamado pela empresa do cliente, o grupo econômico com várias operações. Se o sistema fundisse tudo pelo documento, ele misturaria históricos de clientes que a sua operação trata como separados. O mesmo vale para o nome, que é ainda mais frágil: "Padaria do João" e "Padaria do Joao Ltda" são a mesma empresa para você e strings diferentes para qualquer computador.

Por isso a regra é uma só: quem manda os dados diz qual é a identidade deles. O par origem mais id é uma afirmação sua, não um palpite do sistema.

Preparando a carga

Antes de disparar, três cuidados poupam retrabalho:

  1. Escolha o source e não mude mais. Se você importar hoje como erp e amanhã como erp_v2, a segunda carga cria tudo de novo, porque o par mudou.
  2. Use um id estável. A chave primária do sistema de origem serve. Um número de linha de planilha não serve, porque muda quando alguém ordena a planilha diferente.
  3. Teste com poucos registros. Suba dez, confira o resultado na tela de clientes, e só então rode a base inteira.

Se o cadastro já existir aqui

Cliente cadastrado à mão antes da importação não tem origem nem id externo, então a carga não vai reconhecer ele e vai criar um segundo registro. Duas saídas: importar primeiro, cadastrar à mão depois, ou aceitar a limpeza manual desses poucos casos.

Vale saber que cliente excluído volta. Se o registro tinha sido apagado aqui e ainda existe no sistema de origem, a importação restaura ele, porque a fonte externa é tratada como a verdade.

Contatos de e-mail para campanhas

Se o seu objetivo não é o cadastro completo, e sim uma lista para disparo, o caminho é mais curto: em CRM › Listas, a importação por planilha carrega os e-mails direto na lista. Ela alimenta as campanhas, não o cadastro de clientes do CRM.