Saltar al contenido principal

Gestiona los registros

Gestiona los registros

Cada registro de un formulario se persiste como un ConsentFormEntry. Esta guía cubre dónde encontrar los datos, qué se almacena y cómo procesar los registros en tu backend.

Qué se almacena​

ConsentFormEntry
{
  "id": "cfent_wAspvmEr4ACDZaPUtfwjsA",
  "consent_form_id": "cform_wAspvmEr4ACDZaPUtfwjsA",
  "consent_form_version": 2,
  "subject_id": "ent_wAspvmEr4ACDZaPUtfwjsA",
  "subject_type": "Entity",
  "user_reference": "customer-123",
  "consent_action_id": "consact_wAspvmEr4ACDZaPUtfwjsA",
  "consent_commit_id": null,
  "data": {
    "full_name": "Jane Doe",
    "email": "jane@soyio.id"
  },
  "created_at": "2024-03-20T15:30:00Z"
}
  • data contiene los valores capturados, indexados por la key que definiste en cada campo.
  • consent_action_id se usa cuando el registro tiene un solo consentimiento. consent_commit_id se usa cuando hay varios. Solo uno de los dos tendrá valor.
  • consent_form_version indica la versión exacta del formulario que firmó el usuario.
  • subject_id apunta a la Entity (ent_*) o Identity (id_*) del subject. Soyio crea automáticamente una Entity si no había una previa.

Los datos del formulario están sujetos a minimización. Captura solo los campos que realmente necesitas, y considera referenciar documentos legales en lugar de incluir texto extenso en los campos.

Consulta desde el dashboard​

Abre Consentimiento > Formularios > Tu formulario para ver el resumen del formulario y la tabla de registros. El bloque Resumen muestra el total de registros del periodo seleccionado, los datos solicitados y las tasas de consentimiento completo y parcial. Usa Descargar CSV para exportar la tabla en cualquier momento.

Detalle de un formulario con resumen y tabla de registros

Haz clic en una fila para abrir el drawer del registro, que reúne todo lo capturado en un solo lugar.

Drawer de un registro con datos del sujeto, consentimientos e historial

El drawer del registro incluye:

  • Datos del sujeto: los valores enviados en cada campo del formulario.
  • Sujeto: el entity_id (o identity_id) y su estado de vigencia.
  • Consentimientos: cada plantilla aceptada con su versión y estado (Otorgado, Revocado).
  • Historial: los eventos asociados al registro, empezando por la submission del formulario.
  • Exportar: descarga el detalle del registro individual.

Consulta desde la API​

Listar registros​

GET /api/v1/consent_form_entries?per_page=50&page=1

Esto retorna todos los registros de tu compañía. Para filtrar por un formulario específico, usa los filtros estándar:

GET /api/v1/consent_form_entries?filter[consent_form_id]=cform_<id>

Lee el detalle en indexConsentFormEntries.

Recuperar un registro​

GET /api/v1/consent_form_entries/cfent_<id>

Actualizar user_reference​

Si un registro llegó sin un identificador de tu sistema, puedes asociarlo a tu user_reference después:

PATCH /api/v1/consent_form_entries/cfent_<id>
{
  "user_reference": "customer-123"
}

Solo el campo user_reference puede actualizarse después de creado el registro. El resto de los datos es inmutable para mantener la integridad de la evidencia.

Procesar registros en tiempo real​

Cada registro actualiza el Agreement del subject y dispara los webhooks agreement.created o agreement.updated. Suscríbete desde Desarrolladores > Webhooks del dashboard para reaccionar inmediatamente al cambio de permisos: te llega el estado vigente del consentimiento, no las acciones individuales que tendrías que reconstruir.

Usa estos webhooks para:

  • Crear el usuario en tu CRM con los datos capturados.
  • Disparar emails de bienvenida o follow-up.
  • Auditar el estado de consentimiento en tus sistemas internos.

El payload del webhook trae el Agreement actualizado, no los datos crudos del formulario. Para acceder a data, consulta el ConsentFormEntry correspondiente vía API a partir del entity_id u identity_id que viene en el agreement.

Revisa la guía de webhooks para detalles de configuración y verificación de firmas.

Linkear un registro a un usuario ya conocido​

Si tu sistema ya tiene un ent_* o id_* para el usuario, puedes pasarlo al renderizar el formulario para que el registro quede asociado a ese subject existente en lugar de crear una Entity nueva.

  • En el iframe SDK: configura subjectId: 'ent_<entity_id>' al inicializar el ConsentFormBox.
  • En la API directa: envía subject_id en el body del POST /consent_forms/:id/entries.

Solo puedes enlazar a subjects que ya pertenecen a tu compañía. Pasar un subject_id de otra compañía resulta en 404.

Centraliza el registro en un sujeto existente​

subject_id cubre el caso en que ya sabes quién es el usuario antes de mostrarle el formulario. Cuando recién al recibir el registro logras identificarlo en tu sistema (cruzando email, RUT, teléfono o cualquier otro dato del formulario), puedes fusionar la Entity recién creada en la Entity que ya tenías para centralizar los permisos del usuario en un único sujeto.

Es el caso típico de:

  • Captación de leads que después descubres que ya eran clientes en tu CRM.
  • Atenciones presenciales donde tu equipo identifica al usuario en el sistema después de que firmó el formulario.
  • Onboardings donde el formulario se cierra antes de que tu backend complete la conciliación con tu base de usuarios.

Cómo se hace​

Toma cualquiera de los datos capturados (email, nin, phone, etc.) y resuelve contra tu sistema cuál es la Entity precedente. Luego llama al endpoint de fusión:

POST /api/v1/subject_merges
{
  "precedent_entity": "ent_<entity_precedente>",
  "merged_entity": "ent_<entity_del_formulario>"
}
  • precedent_entity: el sujeto que conserva precedencia. Tus consultas posteriores apuntarán a este.
  • merged_entity: la entidad recién creada por el formulario. Queda marcada con merged_into = precedent_entity y deja de aparecer como sujeto activo.

El endpoint solo acepta tokens ent_* (Entities). La fusión sobre Identity (id_*) todavía no está soportada.

Qué pasa con datos y permisos​

  • Se crea un nuevo Agreement sobre precedent_entity que combina sus data_permissions con las del registro recién enviado. El version_source del agreement queda apuntando al SubjectMerge, así la fusión es trazable en la auditoría.
  • El data vault se fusiona campo a campo: la precedent_entity tiene prioridad. Los campos que tenía la merged_entity y no la precedente se copian. Los emails se unen sin perder valores.
  • La merged_entity queda marcada como fusionada y deja de ser un sujeto activo.

Llamadas posteriores​

Después de la fusión, llamar a cualquier endpoint con el ent_* original de la merged_entity redirige automáticamente al sujeto precedente. La respuesta incluye metadata.entity_redirect para que tu sistema actualice referencias:

{
  "metadata": {
    "entity_redirect": {
      "requested_entity_id": "ent_mergedEntity123",
      "resolved_entity_id": "ent_precedentEntity123",
      "merge_chain": ["ent_mergedEntity123", "ent_precedentEntity123"]
    }
  }
}

La fusión es irreversible. Una merged_entity no se puede volver a fusionar ni separar. Verifica el match con tu sistema antes de llamar al endpoint.

Consulta los detalles completos en createSubjectMerge.

Consulta el estado de cumplimiento​

Una vez creado el registro, el Agreement del usuario queda actualizado. Para verificar si el usuario cumple con un consentimiento específico, usa el endpoint estándar de ComplianceStatus:

GET /api/v1/entities/<entity_id>/agreement/compliance_statuses?consent_template_id=<consent_template_id>

Revisa la guía de consulta de consentimiento para los detalles de las respuestas posibles.

Revocaciones​

Los consentimientos firmados a través de un formulario de consentimiento se revocan igual que cualquier otro consentimiento:

El ConsentFormEntry permanece como evidencia histórica de que el usuario otorgó el consentimiento en algún momento, aunque el Agreement refleje la revocación posterior.

Próximos pasos​