Guía de Integración — Widget de Onboarding

El widget de onboarding es un Web Component autocontenido (<firmadigital-onboarding>) que corre todo el flujo de emisión — desde ingresar el código de compra hasta descargar el certificado — dentro de la página de tu sitio, sin iframes. La integración con partners es exclusivamente vía este Web Component.

1. Cargar el widget

1. Agregá el <script> del bundle (un solo archivo autocontenido, sin dependencias):

   <script src="https://mi.firma.digital/firmadigital-onboarding.js" defer></script>

2. Agregá el elemento donde quieras que aparezca el formulario:

   <firmadigital-onboarding
     partner="MIPARTNER"
     p_code="MIPARTNER-26-FV01-A1B2C3D4"
     returnurl="https://misitio.cl/gracias"
   ></firmadigital-onboarding>

Si no tenés un código de compra todavía para probar, generalo primero con la API de Códigos de Compra.

Atributos

Atributo	Requerido	Descripción
partner	Sí	Tu nombre de partner (el mismo que usás como identidad de partner en las APIs).
p_code	Sí	El código de compra a canjear.
returnurl	No	A dónde redirigir cuando el usuario termina el flujo completo.

Probalo antes de integrar

Podés cargar el widget contra un p_code real de tu ambiente de desarrollo con la página de prueba en test-widget-harness — pega tu código de compra y partner ahí para ver el flujo completo y los eventos que emite, sin tocar tu propio sitio todavía.

2. Escuchar eventos

El widget notifica su progreso vía CustomEvent sobre el propio elemento — no hace falta un iframe ni postMessage, porque vive en el mismo documento que tu página.

const widget = document.querySelector('firmadigital-onboarding');

widget.addEventListener('onboarding:ready', (e) => {
  console.log('Widget listo', e.detail); // { height }
});

widget.addEventListener('onboarding:stepChange', (e) => {
  console.log('Paso actual', e.detail); // { step, total }
});

widget.addEventListener('onboarding:complete', (e) => {
  console.log('Flujo completado', e.detail);
});

widget.addEventListener('onboarding:error', (e) => {
  console.error('Error en el widget', e.detail);
});

Evento	Cuándo se dispara
onboarding:ready	El widget terminó de cargar y renderizar.
onboarding:stepChange	El usuario avanzó de paso (identidad → datos personales → seguridad).
onboarding:complete	El usuario terminó el flujo completo.
onboarding:error	Ocurrió un error durante el flujo.
onboarding:download	El usuario descargó su certificado.
onboarding:emailCopy	El usuario pidió reenviar una copia por email.
onboarding:centralized	El usuario centralizó su firma en el SII.

Si preferís no depender de eventos en tiempo real (por ejemplo, para un dashboard interno de soporte), podés consultar el estado de cualquier código de compra en cualquier momento con GET /status de la API de Partners.

3. Modo widget vs. sitio standalone

El widget ajusta su propia UI cuando detecta que corre embebido (sin el “confetti” de celebración, sin el panel de recomendaciones al final, con navegación que no le escribe hash a la URL de tu sitio) — no hace falta ninguna configuración extra de tu parte para esto, es automático.

Siguiente paso

Si tu integración es B2B (mode = 2 en tu configuración de partner), probablemente no necesites el widget en absoluto — el certificado se emite y entrega automático vía la API de Partners sin que el usuario final tenga que interactuar con nada.