> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kycert.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Widget Embed

> Receba eventos do portal de onboarding embarcado via iframe.

O Widget Embed permite incorporar o portal de onboarding da kycert diretamente no seu site usando um `<iframe>`. A comunicação entre o iframe e a página pai é feita via **PostMessage API**, sem dependências externas.

## Instalação

Adicione 2 linhas ao seu HTML:

```html theme={null}
<div id="kycert-container"></div>
<script src="https://cadastro.kycert.com.br/embed.js"></script>
<script>
  KycertEmbed.init({
    slug:      'minha-corretora',
    container: '#kycert-container',
    height:    640,
    onSubmit: function(data) {
      console.log('Cadastro enviado:', data.status)
    },
  })
</script>
```

Substitua `minha-corretora` pelo slug da sua conta kycert.

## Opções de configuração

| Parâmetro   | Tipo                | Padrão      | Descrição                             |
| ----------- | ------------------- | ----------- | ------------------------------------- |
| `slug`      | `string`            | obrigatório | Slug da corretora                     |
| `container` | `string \| Element` | obrigatório | Seletor CSS ou elemento DOM           |
| `height`    | `number`            | `640`       | Altura inicial do iframe em pixels    |
| `onSubmit`  | `function`          | —           | Chamado quando o formulário é enviado |
| `onStep`    | `function`          | —           | Chamado a cada mudança de etapa       |
| `onError`   | `function`          | —           | Chamado em caso de erro               |

## Eventos PostMessage

O iframe emite eventos via `window.postMessage`. Você pode escutá-los manualmente se preferir não usar o helper:

```js theme={null}
window.addEventListener('message', function(event) {
  if (!event.data || typeof event.data !== 'object') return

  switch (event.data.type) {
    case 'kycert:submitted':
      // Formulário enviado com sucesso
      console.log(event.data.status)   // 'aprovado' | 'em_analise' | 'pendencia'
      console.log(event.data.message)  // mensagem para exibir ao cliente
      break

    case 'kycert:resize':
      // Altura do conteúdo mudou (auto-resize)
      iframe.style.height = event.data.height + 'px'
      break

    case 'kycert:step':
      // Usuário avançou para uma nova etapa
      console.log(event.data.step)     // 1, 2, 3, 4, 5 ou 6
      break
  }
})
```

### `kycert:submitted`

Emitido quando o usuário conclui o cadastro.

```json theme={null}
{
  "type": "kycert:submitted",
  "status": "em_analise",
  "message": "Suas informações foram recebidas. Em breve você receberá uma resposta."
}
```

| Campo     | Tipo     | Descrição                                                               |
| --------- | -------- | ----------------------------------------------------------------------- |
| `status`  | `string` | Status do cadastro: `aprovado`, `em_analise`, `pendencia` ou `recusado` |
| `message` | `string` | Mensagem de feedback para exibir ao cliente                             |

### `kycert:resize`

Emitido quando a altura do conteúdo muda. Use para ajustar o iframe dinamicamente e evitar scroll interno.

```json theme={null}
{
  "type": "kycert:resize",
  "height": 840
}
```

### `kycert:step`

Emitido a cada mudança de etapa no formulário. Útil para analytics ou progress tracking.

```json theme={null}
{
  "type": "kycert:step",
  "step": 3
}
```

## Exemplo completo com React

```tsx theme={null}
import { useEffect, useRef } from 'react'

export function KycertWidget({ slug, onComplete }) {
  const containerRef = useRef(null)
  const embedRef = useRef(null)

  useEffect(() => {
    if (!containerRef.current) return
    embedRef.current = window.KycertEmbed.init({
      slug,
      container: containerRef.current,
      height:    640,
      onSubmit:  onComplete,
    })
    return () => embedRef.current?.destroy()
  }, [slug])

  return <div ref={containerRef} />
}
```

## Segurança

* O CSP do portal permite `frame-ancestors 'self' *` nas rotas de onboarding.
* A origem do embed não é validada por padrão. Para restringir quais domínios podem incorporar o portal, configure **Origens permitidas** na aba Canais do painel master.
* O canal `widget` pode ser desabilitado globalmente por tenant no painel master.
* Sessões originadas via widget são rastreadas com `source: 'widget'` na tabela de clientes.

<Info>
  O canal `widget` precisa estar habilitado na aba **Canais** do painel master para que o formulário aceite submissões via iframe.
</Info>