# Integration Guide — Onboarding Widget

> How to embed Firma Digital's issuance flow as a Web Component on your site.

The onboarding widget is a self-contained [Web Component](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) (`<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

<Steps>

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

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

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

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

</Steps>

If you don't have a purchase_code to test with yet, generate one first with the [Purchase Code API](/en/guides/partner-api-guide/#2-b2c-flow-the-most-common-one).

### 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. |

<Aside type="tip" title="Try it before integrating">
	You can load the widget against a real purchase_code from your development environment using the [`test-widget-harness`](https://test-widget-harness.tsp.workers.dev) 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.
</Aside>

## 2. Listening to events

The widget reports its progress via [`CustomEvent`](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) on the element itself — no iframe or `postMessage` needed, since it lives in the same document as your page.

```js
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`](/en/api/partners/#operation/getStatus).

## 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](/en/guides/partner-api-guide/#3-b2b-flow) with no interaction required from the end user.