Saltar al contenido principal

Registrar un consentimiento

POST/v1/consent-events

Para desarrolladores

Descripción​

Registra un consentimiento obtenido en un canal propio del integrador, como un formulario en su propio sitio. Es distinto de los formularios de Fidelizador. El registro queda con source=api.

Un evento tiene dos partes. El encabezado dice qué término se aceptó y cómo; las reglas dicen qué se autoriza o se deniega, para qué identificador y para qué finalidad. Se envían juntos, en una sola llamada, y el evento queda inmutable.

Revocar es una regla con action: deny, no un estado del evento. Cada llamada agrega un registro nuevo y actualiza el estado vigente; nada se edita ni se borra.

La versión del término aplicada es siempre la vigente al momento de la llamada. El request no acepta una versión específica.

Guía relacionada​

  • Consentimiento — Registre y consulte el consentimiento de sus contactos.

Autenticación​

Authorizationbearer tokenheaderobligatorio
API key con scope consent:write. Formato: Bearer <API_KEY>.
X-Instance-Slugstringheaderobligatorio
Identificador de su instancia. Ver Autenticación.

Request​

Body:

{
  "term_id": 4,
  "method": "double_opt_in",
  "rules": [
    {
      "channel": "mail",
      "contact_type": "email_address",
      "contact": "[email protected]",
      "purpose_id": 1,
      "action": "allow"
    }
  ]
}
term_idintegerobligatorio
Id del término aceptado (ver `GET /v1/consent-terms`).
methodstring, enum: `single_opt_in | double_opt_in`obligatorio
Cómo se obtuvo el consentimiento.
rulesarrayobligatorio
Al menos una regla. Una por par canal + finalidad.
channelstring, enum: `mail | sms | wsp | call | push`
Canal al que aplica la regla. Por defecto mail.
contact_typestring, enum: `email_address | phone_number | uniquecode`obligatorio
Qué identificador trae contact. Tiene que ser compatible con channel: mail admite email_address o uniquecode; sms, wsp y call admiten phone_number o uniquecode; push admite solo uniquecode. Una combinación inválida devuelve 409.
contactstringobligatorio
Identificador del titular, 1–254 caracteres.
purpose_idintegerobligatorio
Finalidad a la que aplica (ver `GET /v1/consent-purposes`).
actionstring, enum: `allow | deny`obligatorio
allow otorga, deny revoca.

Response​

201 CreatedDevuelve el objeto creado. El header Location trae su URL (ver Headers).
idintegersiempre presente
Identificador del evento creado.
term_idintegersiempre presente
—
term_version_idintegersiempre presente
Versión del término resuelta automáticamente (la vigente al momento de la llamada).
statusstring, enum: `confirmed | pending | expired`siempre presente
El estado del evento, que por esta vía se crea como confirmed.
methodstring, enum: `single_opt_in | double_opt_in`siempre presente
—
sourcestring, enum: `form | api | import | system`siempre presente
El origen del evento, que por esta vía es api.
submission_idinteger | null
El envío de formulario que originó el evento, que por esta vía es null: un evento registrado así no proviene de un formulario. Se completa en el listado para los eventos con source: form.
form_idinteger | null
El formulario de ese envío, que por esta vía es null (ver submission_id).
form_namestring | null
El nombre de ese formulario, que por esta vía es null (ver submission_id).
confirmed_atstring (date-time) | null
—
expired_atstring (date-time) | null
—
created_atstring (date-time)siempre presente
—
rulesarraysiempre presente
Las reglas del evento, con el id que se les asignó.

Errores​

CódigoCuándo
404El term_id no existe en la cuenta (consent_term_not_found).
409El término está inactivo (consent_term_inactive), no tiene ninguna versión vigente (consent_term_no_current_version), el tipo de identificador no corresponde al canal (consent_contact_type_channel_mismatch), o vienen dos reglas para el mismo par canal + finalidad (consent_duplicate_rule).

Detalle completo en Errores genéricos (not-found) y Errores genéricos (conflict).

Notas
  • Las direcciones de correo se guardan en forma canónica: se normalizan a minúsculas y se recortan los espacios. Registrar [email protected] y consultar después por [email protected] devuelve la misma regla. Los uniquecode, en cambio, se guardan tal cual: para ellos ABC y abc son dos códigos distintos.
  • Un evento no se puede actualizar. Para revocar, registre un evento nuevo cuya regla lleve action: deny. El registro original queda intacto como evidencia.
  • Para saber si hoy se le puede enviar a alguien, use GET /v1/consent-rules/resolve. El listado de eventos es el historial, no el estado actual.
Request
curl -X POST "https://$API_HOST/v1/consent-events" \
-H "Authorization: Bearer $API_KEY" \
-H "X-Instance-Slug: $SLUG" \
-H "Content-Type: application/json" \
-d '{
  "term_id": 4,
  "method": "double_opt_in",
  "rules": [
    {
      "contact_type": "email_address",
      "contact": "[email protected]",
      "purpose_id": 1,
      "action": "allow"
    }
  ]
}'
Response
{
"id": 42,
"term_id": 4,
"term_version_id": 7,
"status": "confirmed",
"method": "double_opt_in",
"source": "api",
"submission_id": null,
"form_id": null,
"form_name": null,
"confirmed_at": "2026-05-08T14:22:31Z",
"expired_at": null,
"created_at": "2026-05-08T14:22:31Z",
"rules": [
  {
    "id": 91,
    "channel": "mail",
    "contact_type": "email_address",
    "contact": "[email protected]",
    "purpose_id": 1,
    "action": "allow",
    "created_at": "2026-05-08T14:22:31Z"
  }
]
}