Integration Guide — Onboarding Widget

The onboarding widget is a self-contained Web Component (<firmadigital-onboarding>) that runs the entire issuance flow — from entering the purchase_code to downloading the certificate — inside your site’s own page, with no iframes. Partner integration is exclusively through this Web Component.

1. Loading the widget

1. Add the bundle’s <script> tag (a single self-contained file, no dependencies):

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

2. Add the element wherever you want the form to appear:

   <firmadigital-onboarding
     partner="MYPARTNER"
     p_code="MYPARTNER-26-FV01-A1B2C3D4"
     returnurl="https://mysite.com/thanks"
   ></firmadigital-onboarding>

If you don’t have a purchase_code to test with yet, generate one first with the Purchase Code API.

Attributes

Attribute	Required	Description
partner	Yes	Your partner name (the same one you use as your partner identity in the APIs).
p_code	Yes	The purchase_code to redeem.
returnurl	No	Where to redirect the user once they complete the full flow.

Try it before integrating

You can load the widget against a real purchase_code from your development environment using the test-widget-harness demo page — paste your purchase_code and partner name there to see the full flow and the events it emits, without touching your own site yet.

2. Listening to events

The widget reports its progress via CustomEvent on the element itself — no iframe or postMessage needed, since it lives in the same document as your page.

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

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

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

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

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

Event	When it fires
onboarding:ready	The widget finished loading and rendering.
onboarding:stepChange	The user moved to a different step (identity → personal data → security).
onboarding:complete	The user finished the full flow.
onboarding:error	An error occurred during the flow.
onboarding:download	The user downloaded their certificate.
onboarding:emailCopy	The user requested an email copy to be resent.
onboarding:centralized	The user centralized their signature with the SII (Chile’s tax authority).

If you’d rather not depend on real-time events — for an internal support dashboard, for example — you can check the status of any purchase_code at any time with the Partner API’s GET /status.

3. Widget mode vs. standalone site

The widget automatically adjusts its own UI when it detects it’s running embedded (no celebratory confetti, no recommendations panel at the end, navigation that doesn’t write a hash to your site’s URL) — none of this needs any extra configuration on your part.

Next step

If your integration is B2B (mode = 2 on your partner configuration), you probably don’t need the widget at all — the certificate is issued and delivered automatically via the Partner API with no interaction required from the end user.