Integra el formulario

Integra el formulario

Un mismo formulario puede recibir registros por tres canales en paralelo. Elige el que mejor se adapte a cómo tus usuarios van a interactuar con él.

Opción 1: Link standalone

Soyio aloja cada formulario en una página propia:

URL de producción

https://forms.soyio.id/<companySlug>/<formSlug>

URL de sandbox

https://sandbox-forms.soyio.id/<companySlug>/<formSlug>

Esta opción no requiere código: compartes el link y listo. Ideal para:

• Campañas de marketing por email o SMS.
• Códigos QR impresos en oficinas, eventos o sucursales.
• Procesos asistidos donde tu equipo de soporte envía el link al cliente.

La página standalone muestra el header con tu logo, el formulario y un pie con la marca Powered by Soyio.

Si quieres una URL más corta, puedes apuntar tu propio subdominio con un redirect a forms.soyio.id.

Opción 2: Iframe SDK (ConsentFormBox)

Para mantener al usuario dentro de tu sitio, embebe el formulario en un iframe usando @soyio/soyio-widget. La diferencia clave con el link standalone es que tu sitio controla qué pasa después del submit: cerrar un modal, avanzar a la siguiente pantalla, disparar analytics, etc.

Instala y monta

yarn add @soyio/soyio-widget

Estructura HTML

<div id="consent-form-box"></div>

src/consent-form.ts

import { ConsentFormBox } from '@soyio/soyio-widget';

const consentForm = new ConsentFormBox({
  consentFormToken: 'cform_<id>',
  locale: 'es',
  isSandbox: true,
  subjectId: 'ent_<entity_id>',
  userReference: 'customer-123',
  onEvent: (event) => {
    switch (event.eventName) {
      case 'CONSENT_FORM_PAGE_CHANGE':
        console.log(`Página ${event.currentPage}/${event.totalPages}`);
        break;
      case 'CONSENT_FORM_SUBMITTED':
        console.log('Registro creado', event.entryToken);
        break;
      case 'CONSENT_FORM_COMPLETED':
        if (event.redirectUrl) window.top!.location.assign(event.redirectUrl);
        break;
      case 'CONSENT_FORM_LOAD_ERROR':
        console.error(event.kind, event.message);
        break;
      case 'CONSENT_FORM_SUBMIT_ERROR':
        console.error(event.message);
        break;
    }
  },
});

consentForm.mount('#consent-form-box');

Opciones disponibles

• consentFormToken (requerido): identificador del formulario. Empieza con cform_.
• locale: 'es' o 'en'. Si lo omites, se usa el idioma del navegador.
• isSandbox: true apunta al ambiente de sandbox. Por defecto false.
• subjectId: opcional. Si tu sistema ya tiene un ent_* o id_* asociado al usuario, lo pasas para enlazar el registro a ese subject.
• userReference: opcional. Referencia interna de tu sistema, persistida con el registro.
• appearance: overrides visuales por embed. Revisa Apariencia y comportamiento.
• onEvent: callback que recibe cada evento del iframe.
• onReady: callback que se dispara cuando el iframe queda listo.

Eventos del ConsentFormBox

Todos los eventos llegan vía onEvent. La forma de cada uno es:

CONSENT_FORM_LOAD_ERROR

{
  eventName: 'CONSENT_FORM_LOAD_ERROR',
  kind: 'notFound' | 'hostNotAllowed' | 'loadFailed',
  message?: string,
}

CONSENT_FORM_PAGE_CHANGE

{
  eventName: 'CONSENT_FORM_PAGE_CHANGE',
  currentPage: number, // 1-indexed
  totalPages: number,
}

CONSENT_FORM_SUBMITTED

{
  eventName: 'CONSENT_FORM_SUBMITTED',
  entryToken: string,
  redirectUrl: string | null,
}

CONSENT_FORM_COMPLETED

{
  eventName: 'CONSENT_FORM_COMPLETED',
  entryToken: string,
  redirectUrl: string | null,
}

CONSENT_FORM_SUBMIT_ERROR

{
  eventName: 'CONSENT_FORM_SUBMIT_ERROR',
  message: string,
}

CONSENT_FORM_SUBMITTED se dispara cuando el registro se persiste. CONSENT_FORM_COMPLETED se dispara cuando el usuario hace clic en el botón final de la pantalla de éxito. Si tu integración necesita esperar al usuario, escucha CONSENT_FORM_COMPLETED.

Dominios permitidos

Por seguridad, el iframe solo puede cargarse desde dominios incluidos en la lista blanca de tu compañía. Configúralos en Configuración > Dominios permitidos del dashboard.

• El origen forms.soyio.id siempre está permitido (modo standalone).
• Si embebes en https://app.miempresa.cl, agrega ese origen exacto.

Si el host no está permitido, el iframe muestra el error CONSENT_FORM_LOAD_ERROR con kind: 'hostNotAllowed' y no carga el formulario.

Opción 3: API directa

Si construyes tu propia UI (por ejemplo, una app móvil nativa o un flujo legacy), puedes capturar los action_tokens y crear el registro directamente vía API. Esta es la misma mecánica que el módulo de consentimiento usa para integraciones sin SDK.

Flujo

Press enter or space to select a node.You can then use the arrow keys to move the node around. Press delete to remove it and escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

Registro

El endpoint público no requiere autenticación: usa el cform_ token del formulario en la URL y los action_tokens para acreditar el consentimiento.

POST /api/v1/consent_forms/cform_<id>/entries

{
  "version": 2,
  "subject_id": "ent_<entity_id>",
  "user_reference": "customer-123",
  "data": {
    "full_name": "Jane Doe",
    "email": "jane@soyio.id"
  },
  "consent_actions": [
    { "action_token": "<action_token_1>" },
    { "action_token": "<action_token_2>" }
  ]
}

Campo	Tipo	Requerido	Descripción
version	integer	No	Versión específica del formulario. Si la omites, se usa la última publicada.
subject_id	string	No	Token ent_* o id_* para enlazar el registro a un subject existente.
user_reference	string	No	Referencia interna del usuario en tu sistema.
data	object	Sí	Valores de los campos del formulario, indexados por key.
consent_actions	array	Sí	action_tokens (mínimo uno) de los consentimientos aceptados.

Todos los action_tokens deben corresponder a plantillas declaradas en el formulario. Los obligatorios deben estar todos presentes. De lo contrario el endpoint responde 400.

Consulta el API Reference para el detalle de validaciones y posibles respuestas.

¿Qué pasa con el Agreement?

Independiente del canal, cada registro genera:

• Un ConsentFormEntry con los datos y el subject.
• Un ConsentAction (un consentimiento) o un ConsentCommit (varios).
• Una actualización del Agreement del usuario.

Para reaccionar al cambio de permisos en tiempo real, suscríbete a los webhooks agreement.created y agreement.updated. Son los eventos que reflejan el estado vigente de consentimiento del usuario, así no tienes que reconstruirlo a partir de los consent_action o consent_commit individuales.

Próximos pasos

• Gestiona los registros - Consulta registros vía dashboard o API
• Apariencia y comportamiento - Personaliza el formulario por embed
• Webhooks - Procesa registros en tiempo real