external_id: ID externo del contacto para integraciones

Usa external_id para enlazar un contacto con su registro en tu ERP, e-commerce u otro sistema y evitar duplicados al sincronizar.

Jun 26, 2026

Que es el external_id

El campo external_id guarda el identificador que un contacto ya tiene en otro sistema tuyo (tu ERP, tu e-commerce, otro CRM, una base propia). Es un texto libre de hasta 255 caracteres que viaja junto a la ficha del contacto en Omnifox y sirve para enlazar ese contacto con su registro original en tu plataforma.

No lo usa la mensajeria ni Meta; es exclusivamente para integraciones que tu construyas con la API REST de Omnifox. Esta indexado, por lo que buscar o deduplicar por external_id es rapido.

Cuando usarlo

  • Sincronizas contactos entre Omnifox y un sistema externo y necesitas saber cual es cual sin depender del telefono o el correo (que pueden cambiar).
  • Quieres que tu integracion sea idempotente: reenviar el mismo contacto no crea duplicados.

Como guardarlo via API

El external_id se acepta al crear o actualizar un contacto, y como clave en el upsert.

1. Crear con external_id:

POST /api/v1/contacts
{
  "first_name": "Alex",
  "phone": "+593990000000",
  "external_id": "erp-00482"
}

2. Upsert (crea o actualiza segun una clave unica):

POST /api/v1/contacts/upsert
{
  "unique_by": ["external_id"],
  "external_id": "erp-00482",
  "first_name": "Alex",
  "email": "[email protected]"
}

Con unique_by: ["external_id"], Omnifox busca en el workspace actual un contacto con ese external_id. Si encuentra exactamente uno, lo actualiza; si no hay ninguno, lo crea. Puedes combinar claves (["phone","external_id"]), pero si distintas claves apuntan a contactos diferentes, la API responde 409 (ambiguo) para que no fusiones por error.

Verificacion

  • Tras el upsert, vuelve a llamarlo con los mismos datos: la respuesta debe devolver el mismo id de contacto y no crear uno nuevo.
  • En Contactos, abre la ficha y confirma que los datos se actualizaron en lugar de duplicarse.

Si no funciona

  • Se crean duplicados: revisa que envias unique_by y que el external_id sea identico (sin espacios ni mayusculas distintas). El valor se compara tal cual.
  • Recibo 409 ambiguo: dos contactos del workspace ya tienen claves que chocan (p. ej. uno con ese telefono y otro con ese external_id). Resuélvelo fusionando o limpiando antes de reintentar.
  • El external_id es nulo entre workspaces: recuerda que cada workspace tiene su propia base; el external_id solo es unico dentro del workspace donde lo guardaste.

Tips

  • Usa un prefijo en el valor (erp-, shop-) para saber de un vistazo de que sistema viene.
  • Manten el external_id estable: si cambia en tu sistema origen, perderas el enlace y podrias duplicar.

Articulos relacionados

¿Te fue útil?

Artículos relacionados

Escríbenos por WhatsApp