Saltar al contenido principal

Listar finalidades

GET/v1/consent-purposes

Para desarrolladores

Descripción​

Lista el catálogo de finalidades de la cuenta. Una finalidad es para qué se usa el consentimiento, por ejemplo marketing directo o comunicaciones informativas. Es la unidad sobre la que se decide un envío.

Es el paso previo obligado: registrar un consentimiento exige el purpose_id de una de estas finalidades, y resolver el veredicto también.

El catálogo se administra desde el panel. Por la API solo se puede consultar.

Guía relacionada​

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

Autenticación​

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

Request​

Query params:

pageinteger
Número de página; la primera es la 1. Default: 1.
page_sizeinteger
Tamaño de página, 1–100. Default: 20.
is_enabledboolean | null
Filtra por finalidades habilitadas. Sin el filtro se devuelven todas.

Response​

200 OKDevuelve una página de resultados: data con los elementos y pagination para pedir la siguiente. Cada elemento tiene los campos que siguen.
idintegersiempre presente
El purpose_id que se usa al registrar y al resolver.
codestringsiempre presente
Identificador legible y estable dentro de la cuenta.
namestringsiempre presente
Nombre visible.
descriptionstring | null
—
is_enabledinteger, `0 | 1`siempre presente
1 si la finalidad está habilitada. Se serializa como entero, no como booleano.
Notas
  • Cada cuenta arranca con dos finalidades ya creadas, marketing y newsletter. Ambas se pueden editar o deshabilitar como cualquier otra finalidad.
  • Los envíos puramente transaccionales no declaran finalidad, así que no requieren consentimiento.
  • Una finalidad que ya tiene consentimientos registrados no se puede eliminar; se deshabilita.
Request
curl -X GET "https://$API_HOST/v1/consent-purposes?is_enabled=true" \
-H "Authorization: Bearer $API_KEY" \
-H "X-Instance-Slug: $SLUG"
Response
{
"data": [
  {
    "id": 1,
    "code": "marketing",
    "name": "Marketing directo",
    "description": "Comunicaciones promocionales y de oferta comercial.",
    "is_enabled": 1
  },
  {
    "id": 2,
    "code": "newsletter",
    "name": "Comunicaciones informativas",
    "description": "Boletines y contenidos informativos periódicos.",
    "is_enabled": 1
  }
],
"pagination": {
  "page": 1,
  "page_size": 20,
  "has_more": false,
  "total_items": 2,
  "total_pages": 1
}
}