external_id: ID externo do contato para integracoes
Use external_id para vincular um contato ao seu registro no ERP, e-commerce ou outro sistema e evitar duplicados ao sincronizar.
O que e o external_id
O campo external_id guarda o identificador que um contato ja tem em outro sistema seu (seu ERP, seu e-commerce, outro CRM, uma base propria). E um texto livre de ate 255 caracteres que viaja junto com a ficha do contato no Omnifox e serve para vincular esse contato ao registro original na sua plataforma.
A mensageria e a Meta nao o utilizam; ele existe apenas para integracoes que voce construir com a API REST do Omnifox. Esta indexado, entao buscar ou deduplicar por external_id e rapido.
Quando usar
- Voce sincroniza contatos entre o Omnifox e um sistema externo e precisa saber qual e qual sem depender do telefone ou e-mail (que podem mudar).
- Quer que sua integracao seja idempotente: reenviar o mesmo contato nao deve criar duplicados.
Como gravar via API
O external_id e aceito ao criar ou atualizar um contato, e como chave no upsert.
1. Criar com external_id:
POST /api/v1/contacts
{
"first_name": "Alex",
"phone": "+593990000000",
"external_id": "erp-00482"
}
2. Upsert (cria ou atualiza por uma chave unica):
POST /api/v1/contacts/upsert
{
"unique_by": ["external_id"],
"external_id": "erp-00482",
"first_name": "Alex",
"email": "[email protected]"
}
Com unique_by: ["external_id"], o Omnifox procura no workspace atual um contato com esse external_id. Se encontrar exatamente um, atualiza; se nao houver nenhum, cria. Voce pode combinar chaves (["phone","external_id"]), mas se chaves diferentes apontarem para contatos diferentes a API responde 409 (ambiguo) para voce nunca mesclar por engano.
Como verificar
- Apos o upsert, chame de novo com os mesmos dados: a resposta deve retornar o mesmo id de contato e nao criar um novo.
- Em Contatos, abra a ficha e confirme que os dados foram atualizados em vez de duplicados.
Se nao funcionar
- Duplicados sao criados: confira que voce envia
unique_bye que o external_id seja identico (sem espacos extras nem maiusculas diferentes). O valor e comparado como esta. - Recebo 409 ambiguo: dois contatos do workspace ja tem chaves que se chocam (ex.: um com aquele telefone, outro com aquele external_id). Resolva mesclando ou limpando antes de tentar de novo.
- O external_id e nulo entre workspaces: lembre que cada workspace tem sua propria base; o external_id so e unico dentro do workspace onde voce o gravou.
Dicas
- Use um prefixo no valor (
erp-,shop-) para saber de relance de qual sistema ele vem. - Mantenha o external_id estavel: se ele mudar no sistema de origem, voce perde o vinculo e pode duplicar.
Artigos relacionados
Artigos relacionados
-
Como importar contatos de um arquivo CSV
Carregue sua lista de contatos em minutos mapeando as colunas do seu CSV para os campos do CRM.
-
Gerenciando contatos e o CRM
No Omnifox cada conversa cria um contato. Aprenda a usar campos personalizados, etiquetas, o pipeline de oportunidades e a linha do tempo 360 do contato.
-
Guia completo do CRM
O CRM a fundo, em 46 capítulos: pipeline, oportunidades, ficha da venda, pendências, painel e meta, configurações, ficha do contato, contatos, importar, formulários, chat, IA e fluxos.
-
Campos personalizados de contatos
Crie campos sob medida para o seu negócio para guardar exatamente a informação que você precisa de cada contato.
-
O pipeline de vendas e as oportunidades (deals)
Visualize e gerencie seu processo comercial com um quadro de etapas e cartões de oportunidade.