Campos, formularios y consentimiento

Para desarrolladores

Use estos endpoints para gestionar el catálogo de campos, alimentar datasets, cargar listas de contactos, 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. Los datos que captura un formulario se leen en el dataset al que está conectado.
• 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.
• Lectura, alimentación y exportación de los datasets, que se crean y configuran en el panel.
• Creación, carga, combinación y exportación de listas, copia de sus contactos a un dataset y consulta de los trabajos en segundo plano.
• Registro de una oposición o un bloqueo temporal, con POST /v1/mail-restrictions (ver Oposición y consentimiento).

Fuera de alcance:

• Eliminar un formulario: se hace desde el panel web.
• Crear o versionar un término de consentimiento: es una acción legal que se revisa en el panel web.
• Acceder a los datos de un titular o levantar un bloqueo temporal: se hace desde la Ficha de contacto del panel web. La supresión de los datos de un titular tampoco está disponible por la API.

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

Cada endpoint tiene su ficha, con request y response tipados, parámetros de query y errores.

Campos (base /v1/fields):

Método	Ruta	Ficha
GET	/v1/fields	Listado
GET	/v1/fields/format	Formato de config
POST	/v1/fields	Creación

No existen operaciones de edición, desactivación ni eliminación 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
POST	/v1/datasets/{id}/snapshot	Tomar una instantánea en una lista nueva

Un dataset se crea y se configura desde el panel; la API pública lo lee, lo alimenta, lo exporta y quita contactos. Un dataset no admite importar un CSV. Para cargar en un dataset los contactos de un archivo, impórtelo como lista y copie la lista al dataset.

Listas de contactos (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, plano o comprimido
GET	/v1/lists/{id}/imports	Historial de importaciones
GET	/v1/lists/{id}/imports/{import_id}	Estado de una importación
GET	/v1/lists/{id}/imports/{import_id}/rejects	Filas descartadas de una importación
GET	/v1/lists/{id}/preview	Vista previa del último archivo
POST	/v1/lists/merge	Combinar listas en una nueva
POST	/v1/lists/{id}/export	Exportar los datos a un CSV
POST	/v1/lists/{id}/copy-to-dataset	Copiar los contactos a un dataset

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.

Trabajos (base /v1/jobs):

Método	Ruta	Ficha
GET	/v1/jobs	Listado
GET	/v1/jobs/{id}	Estado de un trabajo
GET	/v1/jobs/{id}/file	Descargar el archivo de un trabajo

Importar un archivo, combinar listas y tomar la instantánea de un dataset dejan un trabajo en segundo plano, y la respuesta trae su id en job_id. El trabajo dice si terminó y, si falló, por qué. El detalle de lo que quedó en la lista está en la importación. Exportar una lista y copiarla a un dataset responden con el trabajo. El archivo de una exportación se descarga desde él.

Formularios (base /v1/forms):

Método	Ruta	Ficha
GET	/v1/forms	Listado
GET	/v1/forms/{id}	Detalle por id
POST	/v1/forms/{id}/submissions	Registrar un envío

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-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. Consulte GET /v1/consent-purposes para obtener el purpose_id de la finalidad que corresponde.
2. Consulte GET /v1/consent-terms para obtener el id del término aplicable.
3. Registre el consentimiento con POST /v1/consent-events. Indique 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 que no pasa la evaluación 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, consulte GET /v1/consent-rules/resolve antes de enviar.

Oposición y consentimiento

Un rechazo de consentimiento (deny) y una oposición registrada con POST /v1/mail-restrictions se parecen, pero no detienen lo mismo:

	Rechazo de consentimiento	Oposición
Alcance	Una finalidad: detiene solo a los remitentes que la exigen	Todo remitente de la instancia, para los tipos de envío que indica (masivo, transaccional o ambos)
Depende del módulo de consentimiento	Sí	No
Se revierte	Con un nuevo evento que otorgue la finalidad	No se levanta

Si el titular pide no recibir más correos de la instancia, registre una oposición. Si retira su consentimiento para un fin concreto, registre el rechazo de esa finalidad. Para detener todo envío mientras se atiende otra solicitud suya, registre un bloqueo temporal (reason: block) con fecha de término.

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: la especificación está en https://$API_HOST/openapi.json y la referencia navegable en https://$API_HOST/docs.