Listar finalidades

GET/v1/consent-purposes

Descripción

Lista el catálogo de finalidades de la cuenta. Una finalidad es para qué se usa el consentimiento — marketing directo, comunicaciones informativas — y 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 lo administra el titular de la cuenta desde el panel; esta superficie es de solo lectura.

Autenticación

Authorizationbearer tokenheaderobligatorio

API key con scope consent:read. Formato: Bearer FD.<key_id>.<token>.

X-Instance-Slugstringheaderobligatorio

Request

Query params:

pageinteger

Página, 1-indexed. 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.

idintegerobligatorio

El purpose_id que se usa al registrar y al resolver.

codestringobligatorio

Identificador legible y estable dentro de la cuenta.

namestringobligatorio

Nombre visible.

descriptionstring | null

—

is_enabledinteger, `0 | 1`obligatorio

1 si la finalidad está habilitada. Se serializa como entero, no como booleano.

Notas

• Cada cuenta arranca con dos finalidades sembradas, marketing y newsletter. Ambas son editables: no son de sistema.
• 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
}
}