Saltar al contenido principal

Sincronizar los contactos de un sitio

POST 
/contacts/sync

Los clientes de un sitio conectado, hasta 500 por llamada. Es lo que llama el plugin de WordPress para traer los usuarios, clientes y leads del sitio — y cualquier plataforma propia con la API key de un sitio conectado también puede llamarla. La respuesta es 200 aunque fallen filas: el resultado de cada una viene en results, en el orden de envío.

POST /contacts/batch es una planilla enviada una vez. Esta ruta es lo contrario: un sistema que reporta a las mismas personas una y otra vez, por eso sus reglas solo suman, nunca destruyen:

  • el contacto se busca primero por quién es en el sitio (ref: el usuario 42 de WordPress), después por teléfono. Quien cambió de número sigue siendo el mismo contacto; si el número nuevo ya es de otro contacto, no se une nada y la fila vuelve con phone_conflict;
  • sin teléfono y sin vínculo con el sitio, no se crea a nadie (no_phone, invalid_phone);
  • las etiquetas solo entran, por nombre, y las que no existen se crean. Para quitar una, usa removeTags;
  • nombre, e-mail y campos personalizados solo rellenan lo que está vacío: lo que alguien escribió en el panel gana sobre lo que reporta el sitio. Los campos que calcula el propio sitio (los wc_… de WooCommerce) sobrescriben — salvo que occurredAt sea más antiguo que el último aplicado para ese vínculo (stale_snapshot);
  • una baja dada en el sitio siempre vale. El consentimiento solo pasa de unknown a opted_in, con evidencia, y nunca por encima de una baja (kept_opt_out) o de una supresión (kept_suppression);
  • un valor para un campo que la cuenta no tiene, o del tipo equivocado, se descarta y aparece en warnings — el resto de la fila se aplica;
  • los contactos nuevos cuentan en el tope del plan (contact_limit_reached).

Con options.triggers en false — el valor por defecto, el de una carga inicial — no se dispara nada: ningún flujo empieza y no sale ningún webhook contact.created. Una carga de diez mil clientes no puede saludar a diez mil personas. Envía true para lo que acaba de pasar en el sitio.

Idempotencia. Con la cabecera Idempotency-Key, un lote repetido tras una conexión caída devuelve el primer resultado, con Idempotent-Replayed: true, en lugar de aplicarse dos veces. La misma clave con otro cuerpo se rechaza con 422 idempotency_key_reused; mientras la primera solicitud sigue en curso, la repetición recibe 409 idempotency_in_progress.

Solo la API key de un sitio conectado sincroniza — viene con el permiso contacts:sync. Una API key común recibe 404 site_not_found, y una API key restringida a algunos números, 403.

Request​

Responses​

Resultado por fila.