Campos, formularios y consentimiento

Para desarrolladores

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

Alcance

Cubre:

• Consulta del catálogo de campos reutilizables y creación de campos nuevos (editar, desactivar y eliminar un campo se hace desde el panel web).
• Listado y consulta de formularios, incluyendo sus ítems y public_token; exportación en CSV de los envíos confirmados de un formulario.
• Registro de un envío de un formulario que usted renderizó en su propio sitio, aplicando la configuración que ese formulario tiene en el panel (validación, doble confirmación, respuesta automática, aviso al equipo y registro de los consentimientos). La protección anti-bot de esa página queda de su lado (ver la sección correspondiente).
• 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.
• Solicitudes de un titular sobre sus datos (acceso o supresión) — no existe un endpoint para esto.

Autenticación

Los endpoints de las tablas siguientes requieren:

• Authorization: Bearer <API_KEY> — API key de la instancia.
• X-Instance-Slug: <slug> — identificador de la instancia.

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.

Campos (base /v1/fields):

Método	Path	Ficha
GET	/v1/fields	Listado
POST	/v1/fields	Creación

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

Datasets (base /v1/datasets):

Método	Ruta	Ficha
GET	/v1/datasets	Listado
GET	/v1/datasets/{id}/records	Contactos de un dataset
GET	/v1/datasets/{id}/records/export	Exportar los contactos en CSV
POST	/v1/datasets/{id}/contacts	Registrar un contacto
DELETE	/v1/datasets/{id}/contacts/{identifier}	Quitar un contacto

Un dataset se crea y se configura desde el panel; la API pública lo lee, lo alimenta, lo exporta y quita contactos. No hay import de CSV: subir un archivo es trabajo de Listas, no de un dataset.

Listas (base /v1/lists):

Método	Ruta	Ficha
GET	/v1/lists	Listado
POST	/v1/lists	Creación
GET	/v1/lists/{id}	Detalle por id
PATCH	/v1/lists/{id}	Edición
DELETE	/v1/lists/{id}	Eliminación
GET	/v1/lists/{id}/fields	Columnas de una lista
PUT	/v1/lists/{id}/fields	Declarar las columnas
POST	/v1/lists/{id}/imports	Importar un CSV
GET	/v1/lists/{id}/imports	Historial de importaciones
GET	/v1/lists/{id}/imports/{import_id}	Estado de una importación
GET	/v1/lists/{id}/preview	Vista previa del último archivo

Una lista es un conjunto de contactos que se carga desde un CSV: cada columna del archivo se declara como un campo del catálogo, por su posición. A diferencia de un dataset, una lista se crea, se configura y se carga por API. Una importación queda en cola al subir el archivo y su estado se consulta después; la vista previa del último archivo subido ayuda a decidir qué campo corresponde a cada columna.

Formularios (base /v1/forms):

Método	Path	Ficha
GET	/v1/forms	Listado
GET	/v1/forms/{id}	Detalle por id
GET	/v1/forms/{id}/submissions/export	Exportar envíos confirmados
POST	/v1/forms/{id}/submissions	Registrar un envío

No existe una operación de alta, edición ni baja de formularios en la API pública: el formulario, sus campos y sus términos se configuran en el panel. Lo que sí puede hacerse por API es enviarlo.

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

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

Finalidades (base /v1/consent-purposes):

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

Consentimientos (base /v1/consent-events):

Método	Path	Ficha
GET	/v1/consent-events	Historial
POST	/v1/consent-events	Registrar un consentimiento
GET	/v1/consent-events/export	Exportar el historial
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; 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, consulte 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

Además de registrarse, el consentimiento se puede exigir en el envío.

Un remitente se puede configurar para que exija consentimiento y declare 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 restringida. Un destinatario bloqueado queda registrado como descartado, con el motivo. Puede consultarlo en GET /v1/mails/{mail_id}/logs.
• Los envíos de prueba no pasan por esta evaluación.
• La verificación es por dirección de correo. Una revocación registrada con un código propio queda guardada y se devuelve al resolverla, pero no detiene un envío por correo: Fidelizador no tiene forma de saber que ese código y una dirección corresponden a la misma persona.

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

Errores comunes

Esto es un 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 de referencia es el OpenAPI que publica la propia API: el spec está en https://$API_HOST/openapi.json y la referencia navegable en https://$API_HOST/docs.