Reportar eventos del sitio
POST/site-events
Por aquí un sitio conectado cuenta lo que pasó en él — un pedido pagado, un registro, un carrito abandonado —, hasta 100 eventos por llamada. Es lo que llama el plugin de WordPress, y cualquier plataforma propia con la API key de un sitio conectado también puede llamarla.
El sitio no necesita saber qué flujos existen: reporta el evento por su nombre, y todo
flujo activo y publicado con el disparador de evento del sitio que escucha ese nombre lo
recibe (como máximo 20 flujos por evento, por prioridad), igual que las ejecuciones que lo
están esperando. En el flujo, lo que venga en data queda disponible como
{{trigger.<ruta>}} — {{trigger.order.total}} —, junto a trigger.$event (id,
name, occurred_at) y trigger.$site (id, url, name).
Nombres. <origen>.<objeto>.<suceso>, en minúsculas, de 2 a 4 segmentos y hasta 80
caracteres: wc.order.paid, wp.user.registered. Los orígenes wp, wc, wcs,
form y fcrc son los del catálogo del plugin; los eventos de tu propia integración van
en custom — custom.suscripcion.renovada.
Contacto. El bloque contact pasa por la misma sincronización que
POST /contacts/sync, con los campos en snake_case y con los disparadores activados: un
contacto nuevo o una etiqueta añadida inician los flujos de siempre. Sin un contacto
válido no empieza ningún flujo — pero un bloque contact inválido no rechaza el evento,
que queda registrado con el motivo.
Respuesta. 202 significa registrado y encolado: ningún flujo corre dentro de la
solicitud. Cada evento responde por sí mismo — uno inválido vuelve en rejected, con su
posición y el motivo, sin tumbar el lote; un id que el sitio ya reportó cuenta en
duplicates y no cambia nada. La entrega es "al menos una vez": reenviar es seguro. Cada
evento lleva hasta 64 KB entre data y contact.
Esta ruta no responde 402: con la cuenta bloqueada, los eventos se aceptan y se
registran sin correr flujos, para que el sitio no acumule reintentos.
Idempotencia. Con la cabecera Idempotency-Key, una repetición de la misma llamada
devuelve la primera respuesta, con Idempotent-Replayed: true. 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 reporta eventos — viene con el permiso
events:write. Una API key común recibe 404 site_not_found.
Request
Responses
- 202
- 401
- 403
- 404
- 409
- 413
- 422
- 429
Eventos registrados. El destino de cada uno está en accepted, duplicates o rejected.
Token ausente, mal formado, desconocido o revocado (authentication), o cuenta
suspendida (tenant_inactive).
Una sesión del panel en lugar de una API key (site_key_required), o una API key sin el permiso events:write (key_permission_denied).
La API key no está vinculada a un sitio conectado (site_not_found). Conecta el sitio de nuevo desde el plugin.
El sitio está en pausa en el panel (site_paused); un evento trae un site_url distinto de la dirección en que se conectó el sitio (site_url_mismatch, con esa dirección en registeredUrl) — una copia de un sitio, como la de pruebas, debe conectarse por separado, y se rechaza el lote entero; o una solicitud con la misma Idempotency-Key sigue en curso (idempotency_in_progress).
El cuerpo supera 512 KB (payload_too_large). Divide el lote.
Cuerpo inválido — events ausente, vacío o con más de 100 elementos (invalid_request, con issues) —, o la misma Idempotency-Key con otro cuerpo (idempotency_key_reused). Un evento inválido no rechaza el lote: vuelve en rejected.
Límite de peticiones superado (rate_limit).
Response Headers
Segundos a esperar antes de reintentar.
Categoría de límite aplicada — send, media o default.
Qué cubo describen las otras cabeceras — key (la API key), session (el panel) o account (el techo de la cuenta).
Techo de peticiones de la categoría en la ventana actual.
Peticiones restantes en la ventana actual.