# Como incorporar o link de KYC Onboarding no seu site?
> Depois de gerar um `linkOnboarding` com o _endpoint_ [`POST /api/v1/kyc/onboarding`](./api-onboarding-create.mdx), você pode entregá-lo ao merchant de três formas:
export const KycPreview = () => {
const [status, setStatus] = useState('PENDING');
return (
);
};
1. **Redirecionamento** — enviar o merchant diretamente para a página de KYC (recomendado)
2. **Nova aba / popup** — abrir o KYC sem perder o contexto do seu site
3. **Iframe** — renderizar o KYC dentro de uma página do seu site
Este guia cobre as três abordagens e como detectar a conclusão do onboarding.
:::info Pré-requisitos
Antes de incorporar, você precisa ter o `linkOnboarding` em mãos. Caso ainda não tenha, siga [Como criar um onboarding KYC via API?](./api-onboarding-create.mdx).
:::
:::tip Referência completa
Para o schema, parâmetros e exemplos interativos do endpoint que gera o `linkOnboarding`, veja a [API Reference](/api#tag/kyc/POST/api/v1/kyc/onboarding).
:::
:::tip Experiência white-label (sem a logo da Woovi)
Para uma integração white-label, você pode ocultar a logo da Woovi no topo do formulário adicionando `?embed=true` à URL de onboarding. Veja [Como ocultar a logo da Woovi no link de onboarding?](./api-onboarding-white-label.mdx).
:::
## Opção 1 — Redirecionamento (recomendado)
A forma mais simples e segura de integrar é redirecionar o merchant diretamente para o `linkOnboarding`. O merchant preenche todo o cadastro na página da Woovi e, quando terminar, você pode trazê-lo de volta via um botão no seu sistema ou consultando o status pela API.
```html
Iniciar cadastro KYC
```
Ou, programaticamente:
```js
window.location.href = data.linkOnboarding;
```
## Opção 2 — Nova aba / popup
Se você quer manter o merchant no seu site enquanto ele preenche o KYC, abra o link em uma nova aba:
```html
Iniciar cadastro KYC
```
Ou como popup:
```js
const popup = window.open(
data.linkOnboarding,
'woovi-kyc',
'width=480,height=800',
);
```
## Opção 3 — Iframe
O frontend de KYC **não envia headers `X-Frame-Options` nem `Content-Security-Policy: frame-ancestors`**, então é possível renderizá-lo dentro de um `
```
### Atributos recomendados
| Atributo | Valor sugerido | Por quê |
|----------|----------------|---------|
| `width` | `100%` (até ~640px) | O formulário é otimizado para telas estreitas/mobile |
| `height` | `900` ou mais | O formulário é multi-step e pode precisar de scroll interno |
| `allow` | `camera; clipboard-read; clipboard-write` | Útil para upload de documentos via câmera e colar dados |
| `title` | `Cadastro KYC` | Acessibilidade |
### Limitações do iframe
- **Não há comunicação `postMessage`** do KYC para a página pai. Você não recebe eventos de "formulário enviado" ou "passo concluído" dentro do iframe.
- Para saber quando o merchant finalizou o cadastro, você precisa [consultar o status via API](#detectando-a-conclusão-do-onboarding).
- Upload de arquivos dentro de iframe pode ter restrições em alguns navegadores mobile — teste o fluxo completo antes de subir para produção.
## Detectando a conclusão do onboarding
A API **não envia webhook** quando o merchant conclui o cadastro. Para saber em que estágio ele está, consulte o status do `AccountRegister` usando o `correlationID` ou `taxID` enviados na criação.
### Estados possíveis
| Status | Significado |
|--------|-------------|
| `PENDING` | Link criado, merchant ainda não submeteu |
| `IN_REVIEW` | Merchant submeteu — em análise pela equipe |
| `APPROVED` | Cadastro aprovado |
| `REJECTED` | Cadastro rejeitado |
### Estratégias
- **Polling**: consulte a cada N minutos, especialmente se o merchant estiver dentro de um iframe
- **Callback manual**: coloque um botão "Já finalizei o cadastro" no seu site que dispara a consulta
- **Verificação antes de liberar funcionalidades**: consulte o status sempre que o merchant tentar acessar recursos que dependem de KYC aprovado
## Exemplo completo — backend + iframe
**Backend (Node.js)**
```js
// 1. Crie o onboarding a partir do seu backend
app.post('/start-kyc', async (req, res) => {
const { taxID, correlationID } = req.body;
const response = await fetch('https://api.woovi.com/api/v1/kyc/onboarding', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': process.env.WOOVI_APPID,
},
body: JSON.stringify({
taxID,
correlationID,
}),
});
const data = await response.json();
// Devolva apenas o link para o frontend (nunca o AppID!)
res.json({ linkOnboarding: data.linkOnboarding });
});
```
**Frontend (HTML)**
```html
Cadastro KYC — Woovi
Woovi
Ambiente seguro
Cadastro de conta
Preencha seus dados para ativar sua conta Woovi. O processo leva menos de 5 minutos.
```
### Pré-visualização
Selecione um status para renderizar o `linkOnboarding` correspondente:
:::caution Nunca exponha o AppID no frontend
Sempre gere o `linkOnboarding` no seu backend. O `AppID` é uma credencial sensível e não deve ser enviado para o navegador.
:::
## Boas práticas
- **Use sempre HTTPS** na página que hospeda o iframe — browsers bloqueiam iframes HTTP em páginas HTTPS.
- **Envie um `correlationID` único** (ex: o ID do pedido no seu sistema) para facilitar a consulta de status depois.
- **Reutilize o link**: a API é idempotente por `correlationID`. Se o merchant fechar o site antes de terminar, você pode devolver o mesmo link sem criar um registro novo.
- **Comunique o passo ao merchant**: antes de abrir o iframe/redirect, explique que ele será levado para o cadastro da Woovi.
- **Trate o retorno**: após detectar `APPROVED`, libere as funcionalidades do BaaS no seu produto.