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.

Asociar el user_reference al recibir el registro​

Si tu sistema recién identifica al titular cuando le llega el registro, suscríbete además a consent_form_entry.created y úsalo como gatillo:

  1. Recibe el evento y lee el identificador del titular desde payload.data (por ejemplo cl_carnet_rut o email).
  2. Resuelve contra tu base quién es ese usuario.
  3. Llama a PATCH /api/v1/consent_form_entries/{id} con el user_reference resuelto.
consent_form_entry.created
{
  "id": "evt_1B2M2Y8AsgTpgAmY7PhCfg",
  "name": "consent_form_entry.created",
  "payload": {
    "id": "cfent_wAspvmEr4ACDZaPUtfwjsA",
    "subject_id": "ent_wAspvmEr4ACDZaPUtfwjsA",
    "user_reference": null,
    "consent_action_id": null,
    "consent_commit_id": null,
    "granted_template_ids": [],
    "data": {
      "full_name": "Jane Doe",
      "email": "jane@soyio.id",
      "cl_carnet_rut": "11.111.111-1"
    }
  },
  "created_at": "2024-03-20T15:30:00Z"
}

consent_form_entry.created se emite antes de crear la acción de consentimiento, así que llega con consent_action_id: null y granted_template_ids: []. Sirve como gatillo para enriquecer el registro, pero no como confirmación del consentimiento: para eso usa agreement.created / agreement.updated o consent_action.created. Si necesitas reconciliar el estado desde el registro, consulta GET /consent_form_entries/{id} con reintentos y backoff hasta que consent_action_id o consent_commit_id tenga valor. Si ambos siguen en null, la respuesta todavía es incompleta. Lee el detalle en Orden de emisión y fuente de verdad.

Después del PATCH recibes un consent_form_entry.updated con el user_reference ya asociado. Ese evento suele traer granted_template_ids y el consent_action_id (o consent_commit_id si el envío tenía varios consentimientos) poblados, pero si el PATCH se ejecuta antes de que termine de crearse la acción de consentimiento, llega con esos campos vacíos igual que el evento de creación. No los uses como confirmación del consentimiento.

Si en vez de etiquetar el registro necesitas centralizar los permisos en un sujeto que ya tenías, usa la fusión de sujetos.

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_*.

Validación anticipada y creación de consentimiento​

Con early_government_check_enabled la verificación del documento se separa de la creación de la identidad y del consentimiento:

  • La validación anticipada crea el ConsentFormValidationRequest y su ValidationAttempt, y nada más: no promueve una Identity, no escribe el data vault, no genera atestaciones y no crea ConsentFormEntry ni consentimientos. Devuelve un comprobante cfvreq_*.
  • El envío final consume ese comprobante: recién ahí Soyio promueve la Identity, escribe el data vault y las atestaciones, fusiona la Entity preexistente y crea el ConsentFormEntry con sus consentimientos.

El comprobante se envía en consent_form_validation_request_id al crear el registro, es de un solo uso y vence a los 30 minutos. Soyio lo rechaza con 400 si ya fue usado, si venció, si la validación no fue exitosa, o si no corresponde exactamente a la misma empresa, versión del formulario, RUT, número de documento y subject del envío. Si el envío no incluye comprobante, Soyio ejecuta la validación en ese momento, igual que antes de esta opción.

Cuando la validación falla, la API responde 422 con un error_reason estable (invalid_document_number, document_not_valid, expiration_error o government_api_error) para que puedas mostrar un mensaje específico.

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​