V-28 Referencia API

Referencia de la API

La API publica de Consenty sigue convenciones predecibles para que tu integracion sea estable a lo largo del tiempo. Esta pagina resume lo que necesitas saber para empezar a consumirla con confianza.

Convenciones

Envelope de respuesta

Toda respuesta exitosa usa application/json con la forma { data, meta, error }. error siempre es null en el camino feliz.

Nomenclatura

Campos en camelCase. Fechas en formato RFC 3339 UTC (2026-07-26T14:00:00Z). Paginacion con cursor opaco (nextCursor).

Trazabilidad

Cada respuesta trae la cabecera X-Request-Id. Incluyela en cualquier ticket de soporte.

Mutaciones idempotentes

Toda llamada POST / PATCH / DELETE acepta la cabecera Idempotency-Key con un identificador unico por operacion.

Autenticacion

La API usa bearer tokens emitidos desde la vista de API keys (/integrations/api-keys). El prefijo indica el ambiente:

cty_test_ — staging. Los eventos se purgan cada 24 horas.
cty_live_ — produccion. Eventos retenidos segun la politica de privacidad del canal.

GET /v1/channels

bash

curl https://api.consenty.cl/v1/channels \
  -H "Authorization: Bearer cty_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: 01J9XQZ5R3N4P8K7Y2T6V0M3HB" \
  -H "X-Request-Id: req_01J9XQZ5R3N4P8K7Y2T6V0M3HC"

Trata los secretos como contrasenas

Guarda las API keys en un vault (1Password, AWS Secrets Manager, Doppler). Nunca las pegues en el codigo del cliente ni las subas a un repositorio publico.

Endpoints clave

Conjunto representativo. La lista completa vive en la especificacion OpenAPI.

Metodo	Ruta	Proposito	Scope
GET	/v1/channels	Listar canales de la organizacion	`channels:read`
POST	/v1/channels	Crear un canal	`channels:manage`
GET	/v1/channels/:id	Detalle de un canal	`channels:read`
GET	/v1/public/sites/:siteKey/snippet	Snippet HTML publico del SDK	`publico`
POST	/v1/public/sites/:siteKey/preferences	Registrar una decision de consentimiento	`publico`
GET	/v1/evidence	Listar eventos de evidencia (filtros + cursor)	`evidence:read`
GET	/v1/exports	Listar exportaciones	`evidence:read`
POST	/v1/exports	Solicitar una nueva exportacion	`exports:create`
GET	/v1/webhook-destinations	Listar destinos webhook	`webhooks:read`
POST	/v1/webhook-destinations	Crear un destino webhook	`webhooks:write`
GET	/v1/webhook-deliveries	Listar entregas con filtros y cursor	`webhooks:read`
POST	/v1/webhook-deliveries/:id/redeliver	Reenviar una entrega fallida	`webhooks:write`
GET	/v1/api-keys	Listar API keys de la organizacion	`api_keys:read`
POST	/v1/api-keys	Emitir una nueva API key	`api_keys:manage`

OpenAPI completa

La especificacion OpenAPI navegable llega con T-08-01. Mientras tanto, el source vive en apps/api/src/openapi.json (en proceso de generacion automatica desde los decoradores NestJS).

Acceso provisional

Si necesitas la spec hoy, contacta a soporte con tu X-Request-Id: te enviaremos un snapshot vigente firmado.

Problemas y errores

Los errores siguen application/problem+json (RFC 7807). Campos:

type — URL canonical de la clase de error.
title — resumen legible.
status — codigo HTTP.
code — codigo estable para tu manejo.
detail — descripcion del caso concreto.
instance — ruta del recurso afectado.

409 Conflict

http

HTTP/1.1 409 Conflict
Content-Type: application/problem+json
X-Request-Id: req_01J9XQZ5R3N4P8K7Y2T6V0M3HC

{
  "type": "https://docs.consenty.cl/errors/origin_duplicate",
  "title": "Origen duplicado",
  "status": 409,
  "code": "origin_duplicate",
  "detail": "El origen https://app.inprivate.cl ya esta registrado en este canal.",
  "instance": "/v1/channels/ch_8x1k2n4q/origins"
}