Arma tu formulario

Esta guía cubre todas las opciones de configuración de un formulario de consentimiento. Puedes editar el formulario desde el dashboard o desde la API; ambos caminos manejan el mismo modelo.

Editor del dashboard

Entra al dashboard y abre Consentimiento > Formularios. La lista muestra todos los formularios de tu compañía con el número de registros recibidos y los consentimientos asociados.

Crea un nuevo formulario con + Crear Formulario o abre uno existente para editarlo. El editor tiene tres pestañas:

Contenido: estructura del formulario (encabezado, páginas, campos, consentimientos y pantalla de éxito).
Personalización: branding por formulario (logo, tipografía, color y alineación de botones).
Configuración: link público y código QR.

El estado del formulario (Live / borrador) se controla con el toggle del encabezado del editor; los cambios se guardan con Guardar Cambios.

Identificación del formulario

Nombre interno (name): solo visible para tu equipo en el dashboard.
Título (title): encabezado que ve el usuario.
Descripción (description): subtítulo opcional debajo del título.
Slug (slug): parte final de la URL standalone (/<companySlug>/<formSlug>). Debe ser único dentro de tu compañía, en minúsculas, con números y guiones, entre 3 y 80 caracteres.

Si dejas el slug en blanco, Soyio lo genera a partir del nombre. Cámbialo a algo memorable si vas a compartir el link por canales como WhatsApp o impresos.

Estado del formulario

Un formulario tiene tres estados:

Estado	Comportamiento
`draft`	Solo visible en el dashboard. Los registros al link público son rechazados.
`published`	URL pública activa, registros aceptados.
`archived`	Estado terminal. No acepta registros y no puede volver a `draft` ni `published`.

El estado archived es irreversible. Úsalo solo cuando ya no necesitas el formulario.

Campos

Desde la pestaña Contenido del editor, agrega los campos del formulario usando + Agregar campo. Cada campo se ordena dentro de una página y aparece en el preview de la izquierda en tiempo real.

Cada campo es un objeto con la siguiente forma:

ConsentFormField
{
  "key": "full_name",
  "label": "Nombre completo",
  "placeholder": "Ej: Jane Doe",
  "type": "text",
  "required": true,
  "page_index": 0,
  "position": 0
}

Tipos disponibles

Tipo	Comportamiento
`text`	Input de texto libre.
`name`	Input para nombre de persona; solo acepta letras, espacios, guiones y apóstrofos.
`email`	Input con validación de formato de email.
`nin`	Input con validación de documento de identidad por país (RUT, DNI, CC, etc.).
`phone`	Input con formato de teléfono internacional.
`textarea`	Texto multilínea.
`select`	Selector con opciones predefinidas en `options`.
`checkbox`	Casilla booleana.
`date`	Fecha en formato ISO-8601 (`YYYY-MM-DD`).

Reglas de configuración

La llave (key) debe empezar con letra minúscula y solo contener a-z, 0-9 y _. Es el nombre con el que el valor queda almacenado en data y se expone vía API o webhook.
Las llaves deben ser únicas dentro del formulario.
El campo options solo se acepta para type: select. En el resto de los tipos debe ir vacío.
required: true rechaza registros con el campo en blanco.
page_index y position controlan dónde se renderiza el campo en formularios multi-página.

Soyio normaliza los valores antes de guardarlos: hace strip en strings, valida fechas con Date.iso8601 y rechaza registros con tipos inválidos. La respuesta de error siempre indica qué campo falló.

Consentimientos

Cada consentimiento dentro de un formulario es una ConsentTemplateSelection. Apunta a una versión concreta de un consent template ya existente.

ConsentFormSelectedTemplate
{
  "consent_template_id": "constpl_wAspvmEr4ACDZaPUtfwjsA",
  "consent_template_version": 2,
  "required": true,
  "page_index": 0,
  "position": 0
}

Reglas

Cada consent_template_id puede aparecer una sola vez por formulario.
Si omites consent_template_version al crear el formulario por API, Soyio fija la versión latest al momento de guardar.
Un formulario publicado debe tener al menos un consentimiento obligatorio.

Si una plantilla cambia, las versiones anteriores de tu formulario siguen apuntando a la versión que fijaste al guardar. El editor muestra la versión fijada de cada plantilla y, cuando existe una versión más nueva, despliega un aviso con la opción Actualizar a la versión N; al actualizar (o al guardar por API con la nueva versión) se crea una nueva versión del formulario.

Múltiples páginas

Para flujos largos, distribuye campos y consentimientos en varias páginas usando page_index:

Todos los items con page_index: 0 se muestran en la primera página.
Pasar a la siguiente página solo está habilitado cuando los campos obligatorios de la página actual son válidos.
En la última página el botón cambia a Enviar.

Si un consentimiento obligatorio queda sin marcar y el usuario llega a la última página, el formulario lo lleva automáticamente a la página donde se encuentra ese consentimiento y resalta el error.

Título y descripción por página

Por defecto, el title y description del formulario se usan en todas las páginas. Si activas títulos por página (per_page_headers: true; en el editor, desmarca "Usar el mismo título y descripción en todas las páginas"), cada página puede tener su propio encabezado mediante el arreglo pages:

Cada entrada de pages define index, title y description.
El title y description del formulario son los de la página 1 (index: 0): al editar la página 1 editas el título y la descripción del formulario.
Una página sin título o descripción propios usa los del formulario (es decir, los de la página 1) como fallback.
El title del formulario sigue siendo obligatorio.

per_page_headers + pages
{
  "per_page_headers": true,
  "pages": [
    { "index": 0, "title": "Tus datos", "description": "Cuéntanos sobre ti" },
    { "index": 1, "title": "Consentimientos", "description": "Revisa y acepta" }
  ]
}

Puedes elegir entre dos estilos visuales del indicador de progreso desde la apariencia del formulario:

bar: barra horizontal con porcentaje.
steps: pasos numerados.

Pantalla de éxito

Cambia al sub-tab Pantalla de éxito dentro del preview del editor para configurar el copy que ve el usuario después de enviar el formulario.

Lo que ve el usuario después de enviar el formulario es completamente personalizable:

success_screen
{
  "title": "Listo, gracias",
  "message": "Recibimos tus datos y tu consentimiento.",
  "button_text": "Volver al sitio",
  "redirect_url": "https://miempresa.cl"
}

Si redirect_url está presente, el botón redirige al usuario a esa URL. Debe comenzar con http:// o https://.
En modo embebido (iframe SDK), el iframe no navega solo: tu integración recibe el evento CONSENT_FORM_COMPLETED con el redirectUrl y tú decides qué hacer. Revisa Integra el formulario.

Apariencia por formulario

La pestaña Personalización del editor agrupa el branding por formulario: logo, tipografía, color primario, alineación del botón principal y estilo del indicador de progreso.

Cada formulario hereda la apariencia global de tu compañía pero acepta overrides puntuales:

hide_logo, hide_title, hide_description: oculta elementos del header.
font_family: tipografía del formulario.
primary_color: color principal en formato hex (#RRGGBB o #RGB).
button_alignment: left, center o right.
progress_indicator_style: bar o steps.

Lee la guía de apariencia para combinarlos con la configuración global.

Link público y QR

La pestaña Configuración del editor muestra la validación del formulario, el slug y el dominio público, además de un código QR descargable en PNG o SVG.

Pestaña de configuración con slug, dominio público y QR

El slug se concatena al dominio público para formar la URL standalone (https://forms.soyio.id/<companySlug>/<formSlug>).
El dominio público se ajusta desde la configuración general de la compañía. Cámbialo desde Editar dominio público.
Descarga el QR en PNG o SVG para imprimirlo en piezas físicas o pegarlo en una campaña.

Validación gubernamental

Desde la pestaña Configuración, activa Habilitar Validación Gubernamental cuando necesites validar el RUT y número de documento antes de registrar el consentimiento.

Al activarla, Soyio agrega o exige dos campos en el formulario:

cl_carnet_rut: RUT del usuario. Queda obligatorio.
cl_carnet_doc_number: número de documento del carnet. Soyio lo administra para que la validación pueda ejecutarse.

En el envío, Soyio valida esos datos antes de crear el ConsentFormEntry, los ConsentAction o ConsentCommit, y el Agreement. Si la validación es exitosa, el registro queda asociado a una Identity; si falla, el consentimiento no se registra.

Cuándo se valida: Validar antes de continuar

Con la validación gubernamental activa aparece la opción anidada Validar antes de continuar, desactivada por defecto. Controla cuándo Soyio consulta al Registro Civil:

Validar antes de continuar	Momento de la validación	Qué ve el usuario si falla
Desactivada (por defecto)	Durante el envío final del formulario	Vuelve a la página del RUT y número de documento, con sus datos y consentimientos intactos y un mensaje específico según el motivo
Activada	Al presionar Continuar en la página que contiene el RUT y el número de documento	Se queda en esa página con el mensaje específico, sin llegar a llenar el resto del formulario

Activarla evita que alguien complete un formulario largo para recién enterarse al final de que su documento no valida. La validación exitosa se reutiliza en el envío final, así que el Registro Civil se consulta una sola vez por intento.

Si el RUT y el número de documento están en la última página del formulario, no hay un paso Continuar posterior desde el cual validar: el envío final ejecuta la validación igual que con la opción desactivada. El mensaje de error sigue siendo específico según el motivo.

Desactivar Habilitar Validación Gubernamental vuelve Validar antes de continuar a false.

Mensajes de error que ve el usuario

Cuando la validación falla, el usuario ve un mensaje específico según el motivo. El mismo error_reason viaja en el 422 de la API al crear el registro (ver createConsentFormEntry y validación gubernamental en formularios):

`error_reason`	Mensaje en el formulario
`invalid_document_number`	El número de documento no corresponde al RUT ingresado. Revisa ambos datos e inténtalo de nuevo.
`document_not_valid`	No pudimos validar tu documento con el Registro Civil. Verifica que los datos coincidan con tu cédula vigente.
`expiration_error`	Tu cédula de identidad está vencida. Renuévala para poder continuar.
`government_api_error`	El Registro Civil no está disponible en este momento. Inténtalo de nuevo en unos minutos.
cualquier otro motivo	No pudimos validar tu RUT y número de documento. Revisa los datos e inténtalo de nuevo.

document_not_valid describe un documento que ya no está vigente; expiration_error es un motivo interno de expiración de la solicitud de validación que no se dispara con los RUTs de prueba de sandbox. Cuando el embed recibe un error_reason que no reconoce (por ejemplo document_mismatch_or_government_api_error), muestra el mensaje de "cualquier otro motivo".

Los textos están en español por defecto y en inglés cuando el formulario se carga con ?lang=en. Revisa apariencia y comportamiento para ver cómo configurar el idioma.

Prueba la validación en sandbox

En sandbox, solo los tres RUTs de prueba fallan la validación gubernamental: 11111111-1 devuelve auth-076 / document_not_valid, 22222222-2 devuelve auth-074 / invalid_document_number, y 33333333-3 devuelve auth-075 / government_api_error (con el proveedor certificadora_del_sur; con el proveedor por defecto, eCert, devuelve auth-077 / document_mismatch_or_government_api_error). El resto de los RUTs con formato válido se validan exitosamente. La misma lista de RUTs de prueba está en la guía de verificación gubernamental para el flujo API.

Crear o editar por API

Si tu sistema necesita aprovisionar formularios automáticamente, usa la API REST. Los endpoints están documentados en el API Reference.

POST /api/v1/consent_forms
{
  "name": "Consentimiento onboarding",
  "title": "Autorización de tratamiento de datos",
  "description": "Necesitamos tu autorización antes de continuar.",
  "slug": "onboarding",
  "fields": [
    {
      "key": "full_name",
      "label": "Nombre completo",
      "type": "text",
      "required": true,
      "page_index": 0,
      "position": 0
    },
    {
      "key": "email",
      "label": "Email",
      "type": "email",
      "required": true,
      "page_index": 0,
      "position": 1
    }
  ],
  "consent_templates": [
    {
      "consent_template_id": "constpl_wAspvmEr4ACDZaPUtfwjsA",
      "required": true,
      "page_index": 0,
      "position": 2
    }
  ],
  "validation": {
    "government_check_enabled": true,
    "early_government_check_enabled": false,
    "rut_field_key": "cl_carnet_rut",
    "document_number_field_key": "cl_carnet_doc_number",
    "document_number_field_managed": true
  }
}

early_government_check_enabled es opcional y su valor por defecto es false. Solo aplica cuando government_check_enabled es true.

Para actualizar, usa PATCH /api/v1/consent_forms/{id}. Cada PATCH crea una nueva versión del formulario.

La API responde con la versión recién creada en el campo consent_form. Si tu sistema guarda referencias al formulario, persiste el id (que no cambia) y opcionalmente el version (que sí cambia con cada edición).

Próximos pasos

Integra el formulario - Standalone, iframe SDK o API
Gestiona los registros - Consulta y procesa registros
Apariencia y comportamiento - Personaliza la marca del formulario

Editor del dashboard​

Identificación del formulario​

Estado del formulario​

Campos​

Tipos disponibles​

Reglas de configuración​

Consentimientos​

Reglas​

Múltiples páginas​

Título y descripción por página​

Pantalla de éxito​

Apariencia por formulario​

Link público y QR​

Validación gubernamental​

Cuándo se valida: Validar antes de continuar​

Mensajes de error que ve el usuario​

Prueba la validación en sandbox​

Crear o editar por API​

Próximos pasos​

Editor del dashboard

Identificación del formulario

Estado del formulario

Campos

Tipos disponibles

Reglas de configuración

Consentimientos

Reglas

Múltiples páginas

Título y descripción por página

Pantalla de éxito

Apariencia por formulario

Link público y QR

Validación gubernamental

Cuándo se valida: Validar antes de continuar

Mensajes de error que ve el usuario

Prueba la validación en sandbox

Crear o editar por API

Próximos pasos