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.

Jun 26, 2026

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_by e 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

Isso foi útil?

Artigos relacionados

Fale conosco no WhatsApp