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. Si el formulario tiene validación gubernamental habilitada, Soyio crea o reutiliza una Identity después de validar RUT y número de documento.

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 el sujeto recién creado en el sujeto que ya tenías para centralizar los permisos del usuario.

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 el sujeto canónico. Luego llama al endpoint de fusión:

POST /api/v1/subject_merges
{
  "canonical_subject": "id_<identity_canonica>",
  "merged_subject": "ent_<entity_del_formulario>"
}
  • canonical_subject: el sujeto que queda vigente. Acepta ent_* o id_*.
  • merged_subject: el sujeto que se fusiona. Acepta ent_* o id_*.

precedent_entity y merged_entity siguen soportados para integraciones existentes. Cuando una Identity participa en una fusión, Soyio la promueve como sujeto canónico.

Qué pasa con datos y permisos​

  • Se crea un nuevo Agreement sobre el sujeto canónico que combina sus data_permissions con las del sujeto fusionado. 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: el sujeto canónico tiene prioridad. Los campos que tenía el sujeto fusionado y no el canónico se copian. Los emails se unen sin perder valores.
  • El sujeto fusionado queda marcado como fusionado y deja de ser un sujeto activo.

Validación gubernamental en formularios​

Si activas validación gubernamental en el editor del formulario, Soyio agrega o exige dos campos: cl_carnet_rut y cl_carnet_doc_number. En el submit:

  • Se crea un ConsentFormValidationRequest y un ValidationAttempt.
  • Si la validación falla, no se crea ConsentFormEntry, ConsentAction, ConsentCommit ni Agreement.
  • Si la validación es exitosa, el registro se asocia a una Identity.
  • Si ya existía una Entity para el user_reference, Soyio la fusiona automáticamente hacia la Identity para que los consentimientos no queden separados entre ent_* e id_*.

Llamadas posteriores​

Después de la fusión, llamar a cualquier endpoint con el token original del sujeto fusionado redirige automáticamente al sujeto canónico cuando el endpoint soporta subjects fusionados. La respuesta incluye metadata.subject_redirect para que tu sistema actualice referencias. En fusiones legacy Entity → Entity, también se incluye metadata.entity_redirect por compatibilidad:

{
  "metadata": {
    "subject_redirect": {
      "requested_subject_id": "ent_mergedEntity123",
      "resolved_subject_id": "id_canonicalIdentity123",
      "merge_chain": ["ent_mergedEntity123", "id_canonicalIdentity123"]
    }
  }
}

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​