Campos, formularios y consentimiento

Endpoints para gestionar el catálogo de campos, consultar formularios y registrar consentimientos (Ley 21.719) programáticamente.

Alcance

Cubre:

• Consulta del catálogo de campos reutilizables (solo lectura por API — el alta/baja de campos es exclusiva del panel web).
• Listado y consulta de formularios, incluyendo sus ítems y public_token.
• Listado del catálogo de finalidades y de los términos de consentimiento con su historial de versiones.
• Registro de un consentimiento capturado fuera de Fidelizador (source=api), consulta del historial, y resolución del consentimiento vigente antes de enviar.

Fuera de alcance:

• Construir o editar un formulario (agregar/quitar ítems, cambiar textos públicos) — exclusivo del panel web.
• Crear o versionar un término de consentimiento — es una acción legal revisada en el panel web.
• Derechos ARCO+ (acceso o supresión de los datos de un titular) — no existe todavía un endpoint para esto.

Autenticación

Para clientes programáticos: usar los endpoints de integración de las tablas siguientes. Requieren:

• Authorization: Bearer FD.<key_id>.<token> — API key del tenant.
• X-Instance-Slug: <tenant-slug>.

Ver Referencia de la API pública para el detalle.

Endpoints de integración

Una ficha por endpoint, con request/response tipados, query params y errores — ver.

Campos (base /v1/fields):

Método	Ruta	Ficha
GET	/v1/fields	Listado

No existen operaciones de alta, edición ni baja de campos en la API pública.

Formularios (base /v1/forms):

Método	Ruta	Ficha
GET	/v1/forms	Listado
GET	/v1/forms/{id}	Detalle por id

No existe una operación de alta, edición ni baja de formularios en la API pública.

Términos de consentimiento (base /v1/consent-terms):

Método	Ruta	Ficha
GET	/v1/consent-terms	Listado

Finalidades (base /v1/consent-purposes):

Método	Ruta	Ficha
GET	/v1/consent-purposes	Listado

Consentimientos (base /v1/consent-events):

Método	Ruta	Ficha
GET	/v1/consent-events	Historial
POST	/v1/consent-events	Registrar un consentimiento
GET	/v1/consent-rules/resolve	Resolver el vigente

Evidencia y estado vigente son dos cosas

Registrar un consentimiento escribe evidencia: un registro inmutable de qué término se aceptó, en qué versión exacta, cómo y cuándo. Esa evidencia no se edita ni se borra nunca — revocar es registrar un consentimiento nuevo cuya regla deniega, y el original sigue ahí.

En la misma operación se actualiza el estado vigente: qué aplica hoy para cada combinación de canal, finalidad e identificador. Entre reglas contradictorias gana la que deniega.

De ahí que haya dos endpoints de lectura y no uno. El historial responde "qué pasó"; resolve responde "qué aplica ahora", que es la única pregunta que corresponde hacer antes de enviar.

Flujo programático recomendado

Para sincronizar un consentimiento obtenido en un canal propio:

1. GET /v1/consent-purposes para obtener el purpose_id de la finalidad que corresponde.
2. GET /v1/consent-terms para obtener el id del término aplicable.
3. POST /v1/consent-events con el term_id, cómo se obtuvo, y una regla por cada par de canal y finalidad: qué identificador y si allow o deny.
4. Antes de enviar, GET /v1/consent-rules/resolve — no el historial. Es el endpoint que aplica la precedencia y devuelve el mismo veredicto que aplicará el envío.

Consentimiento y envío

El consentimiento no es solo un registro: puede hacerse valer en el envío.

Un remitente puede marcarse como que exige consentimiento y declarar las finalidades que cubre, cada una en modo opt_in u opt_out. Esa configuración se hace desde el panel; no se expone por API. Con la exigencia activa, cada envío de ese remitente se evalúa por destinatario:

Modo de la finalidad	Consentimiento otorgado	Revocado	Sin registro
opt_in	se envía	no se envía	no se envía
opt_out	se envía	no se envía	se envía

Si el remitente declara más de una finalidad, el envío requiere que todas pasen.

Tres cosas que conviene tener presentes:

• El envío se acepta y el descarte ocurre después. La respuesta al envío sigue siendo 200; el correo se evalúa por destinatario más adelante, igual que ocurre con una dirección suprimida. Un destinatario bloqueado queda registrado como descartado, con el motivo — se consulta en el seguimiento del correo.
• Los envíos de prueba no pasan por esta evaluación.
• La verificación es por dirección de correo. Una revocación registrada contra un código propio del integrador queda guardada y se devuelve al resolverla, pero no detiene un envío por correo: vincular un código con una dirección requiere saber que son la misma persona, y eso solo lo sabe el integrador.

Para no depender del descarte posterior, consultar GET /v1/consent-rules/resolve antes de enviar.

Errores comunes

Resumen — el detalle completo, con el código exacto por endpoint, está en la ficha de cada uno y en Respuestas de error.

Código HTTP	Caso típico
404	id de formulario no existe; term_id no existe al registrar un consentimiento.
409	El término está inactivo o no tiene versión vigente; el tipo de identificador no corresponde al canal; dos reglas para el mismo par canal + finalidad; o listas de identificadores y tipos desparejas al resolver.
422	Body no cumple el schema (campos requeridos faltantes, tipos incorrectos).

El contrato autoritativo es el OpenAPI publicado por la propia API en https://$API_HOST/docs (y https://$API_HOST/openapi.json). Este documento reformatea para lectores humanos, pero ante discrepancia el contrato OpenAPI manda.