> ## Documentation Index
> Fetch the complete documentation index at: https://legitimuz.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Instale o @legitimuz/websdk e abra o primeiro fluxo de verificação na sua página.

Ao final deste guia, o fluxo de verificação abre dentro da sua página e os eventos da sessão chegam
ao seu código.

## Pré-requisitos

* Uma `sdkUrl` válida. Ela identifica uma verificação, é emitida pelo servidor da Legitimuz e vale
  por tempo limitado. Trate-a como credencial.
* Node.js 18 ou superior e npm, se for instalar via pacote.

## Abra o primeiro fluxo

<Steps>
  <Step title="Instale o Web SDK">
    <CodeGroup>
      ```bash npm theme={null}
      npm install @legitimuz/websdk
      ```

      ```html CDN theme={null}
      <script src="https://embed.legitimuz.com/v1/websdk.js"></script>
      ```
    </CodeGroup>

    Pelo CDN, o SDK fica disponível como `window.Legitimuz`, com a mesma API do pacote npm.
  </Step>

  <Step title="Reserve o container">
    O widget renderiza dentro de um elemento seu e ocupa 100% da altura dele. Sem altura, o widget
    existe na página e não aparece.

    ```html theme={null}
    <div id="verificacao" style="height: 640px"></div>
    ```
  </Step>

  <Step title="Monte o fluxo">
    ```ts theme={null}
    import { mount } from "@legitimuz/websdk";

    const handle = mount({
      sdkUrl: "<SUA_SDK_URL>",
      target: document.querySelector("#verificacao"),
      onReady: () => {
        // o widget carregou e a primeira tela está visível
      },
      onComplete: (result) => {
        // o fluxo terminou; cheque result.status antes de tratar como sucesso
      },
      onError: (error) => {
        // erros chegam aqui, nunca como exceção
      },
    });
    ```

    `mount()` retorna um handle com `destroy()` e a promise `ready`. Chame `handle.destroy()` ao
    remover o widget da página.
  </Step>

  <Step title="Confira que funcionou">
    A tela de boas-vindas aparece dentro do container e o `onReady` dispara. Se nada aparecer em 15
    segundos, o `onError` recebe o código `6005`; as causas comuns estão logo abaixo.
  </Step>
</Steps>

## Quando não funciona

<AccordionGroup>
  <Accordion title="Nada aparece e o onError recebe 6005">
    O widget não sinalizou `ready` dentro do tempo limite. As causas mais comuns:

    * a origem da sua página não está na allowlist da integração (o navegador recusa o iframe sem
      avisar o host);
    * a `sdkUrl` expirou ou está inacessível.

    O campo `context.likelyCauses` do erro lista as hipóteses. Veja
    [tratamento de erros](/web-sdk/errors).
  </Accordion>

  <Accordion title="O onError recebe 6003 ou 6004">
    Falta `sdkUrl` ou `target` (`6003`), ou a `sdkUrl` não é a URL absoluta esperada (`6004`). O
    campo `context.param` do erro aponta qual opção corrigir.
  </Accordion>
</AccordionGroup>

## Próximos passos

<Columns cols={2}>
  <Card title="Usar com React" icon="atom" href="/web-sdk/react">
    O hook `useLegitimuz` e o componente `LegitimuzWidget`.
  </Card>

  <Card title="Opções do mount()" icon="settings-2" href="/web-sdk/options">
    Aparência, idioma, timeout e todos os callbacks.
  </Card>
</Columns>