> For the complete documentation index, see [llms.txt](https://doc.ozforensics.com/oz-knowledge/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.ozforensics.com/oz-knowledge/oz-knowledge/pt-br/geral/integration-quick-start-guides/como-integrar-oz-liveness-a-sua-aplicacao-web.md).

# Como integrar Oz Liveness à sua aplicação web

Oz Liveness Web SDK implementa a interface de usuário pronta para uso para captura facial, essencial para uma experiência do cliente fluida e resultados de liveness precisos. O SDK detecta ataques de apresentação e de injeção.

Este guia orienta você em sua primeira verificação de liveness usando Web SDK e Oz API. Aqui, cobrimos o [modelo SaaS](/oz-knowledge/oz-knowledge/pt-br/geral/conceitos-chave-de-oz-liveness-e-biometry/saas-on-premise-on-device-what-to-choose.md#when-to-choose-saas).

O fluxo descrito combina:

* **Modo de captura** – o Web SDK (ou Mobile SDK) captura o vídeo de Liveness no navegador/app e o backend do cliente o encaminha para a Oz API. Os resultados da captura não são enviados diretamente do SDK para a Oz API; o backend do cliente atua como intermediário.
* **OzCapsula** – um contêiner binário criptografado proprietário. O SDK empacota a mídia capturada nele; apenas a Oz API pode descriptografá-lo e processá-lo. No dispositivo, ele é um blob opaco – não é possível decodificá-lo ou inspecioná-lo, apenas encaminhá-lo como está.

Cada etapa é marcada:

* **\[Oz SDK]** – chame nossa API do SDK.
* **\[Seu código]** – chame seu próprio backend ou seu próprio código.

`{{host}}` nos exemplos abaixo é a URL base da sua implantação da Oz API, fornecida durante a configuração da implantação.

<figure><img src="https://2275968150-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5g6dgsxRbyrCvB0uAf8f%2Fuploads%2F8THYsB4RSEojAXtepYJ8%2Fweb-sdk-ozcapsula-capture-flow.svg?alt=media&amp;token=8501e87a-9482-448e-b9b9-93e785e644bb" alt=""><figcaption></figcaption></figure>

## Requisitos

| Componente | Versão mínima |
| ---------- | ------------- |
| Oz API     | **6.6.1**     |
| Web SDK    | **1.9.10**    |

É necessário um Web Adapter dedicado. Expanda a seção abaixo se ele ainda não tiver sido configurado para sua empresa.

<details>

<summary>Como obter o Web Adapter</summary>

Informe os nomes de domínio das páginas a partir das quais você chamará o Web SDK e o e-mail para acesso de administrador, por exemplo:

| <p>Nomes de domínio a partir dos quais o Web SDK será chamado:</p><ol><li>[www.yourbrand.com](http://www.yourbrand.com)</li><li>[www.yourbrand2.com](http://www.yourbrand2.com)</li></ol><p>E-mail para acesso de administrador:</p><ul><li><j.doe@yourcompany.com></li></ul> |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

Em resposta, você receberá URLs e credenciais para integração e uso posteriores. Ao usar a API SaaS, você os obtém [de nós](mailto:info@ozforensics.com):

| <p>Login: <j.doe@yourcompany.com></p><p>Senha: …<br><br></p><p>API: https\://\<link>.ozforensics.com/</p><p>Web Console: https\://\<link>.ozforensics.com</p><p>Web Adapter: https\://\<link>.ozforensics.com/your\_company\_name/</p> |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

</details>

Esses parâmetros são obrigatórios para o OzCapsula funcionar. Defina-os no arquivo de configuração da sua API.

{% code title="" expandable="true" %}

```py
OZ_SESSION_TOKEN_LIFETIME=<your_ttl_for_session_token>
OZ_JWT_PRIVATE_KEY_PATH=<jwt_private_key_path>
OZ_JWT_PUBLIC_KEY_PATH=<jwt_public_key_path>
OZ_MALEWICZ_ANALYSIS_ENABLED=true
```

{% endcode %}

## Instruções

{% stepper %}
{% step %}

### (Oz SDK) Incorpore o plugin

A Oz fornece a URL do plugin (servida pelo adaptador hospedado pela Oz). Adicione-a à sua página:

```html
<script src="https://path-to-websdk/plugin_liveness.php"></script>
```

{% endstep %}

{% step %}

### (seu código) Obtenha um `session_token` do seu backend

O OzCapsula usa um session\_token. O token é obrigatório para o OzCapsula.

Seu backend solicita um session\_token da Oz API. Solicite-o antes de cada sessão de captura, o mais próximo possível do momento em que o usuário iniciar a captura.

**Endpoint:**

```
GET {{host}}/api/authorize/session_token
```

**Solicitação:**

```shell
curl --location -g '{{host}}/api/authorize/session_token' \\
--header 'X-Forensic-Access-Token: {{access_token}}' ## opcional, depende das configurações da instalação
```

O mecanismo de autorização para chamadas à Oz API (`access_token`) depende das configurações da sua instalação: ao usar a Instant API, você pode integrá-la ao seu próprio esquema de autorização. Se um access token for exigido no seu caso, consulte [Autenticação](https://doc.ozforensics.com/oz-knowledge/guides/developer-guide/api/oz-api/use-cases/authentication). Nunca exponha o token de acesso no navegador. Além disso, observe que [o token de acesso e o session\_token são tokens diferentes emitidos para finalidades diferentes](/oz-knowledge/oz-knowledge/pt-br/outros/faq.md#what-is-the-difference-between-access_token-and-session_token).

**Resposta:**

```json
{
  "session_token": "<session_token>"
}
```

Esse token é de curta duração (validade padrão: 900 segundos para API Full, 120 segundos para Instant API). Solicite um por sessão de captura e passe-o ao SDK imediatamente – não armazene em cache nem reutilize tokens entre sessões.
{% endstep %}

{% step %}

### (Oz SDK) Inicie o plugin com o `session_token`

```js
OzLiveness.open({
  lang: 'en',
  action: ['video_selfie_blank'],  // liveness passivo
  session_token: session_token,    // session_token da Etapa 2
  on_capture_complete: function (action, ozCapsula) {
    // ozCapsula = o contêiner OzCapsula (Blob) — Etapa 4
    sendToYourBackend(ozCapsula);
  },
  on_error: function (err) { /* tratar */ }
});
```

{% endstep %}

{% step %}

### (Oz SDK) Obtenha o contêiner OzCapsula

Quando a captura é concluída, o SDK dispara o `on_capture_complete` retorno de chamada. O contêiner é entregue como o segundo argumento – um `Blob` com o tipo MIME `application/octet-stream`.

> O contêiner é um **blob criptografado opaco**. Você **não pode** decodificá-lo, inspecioná-lo ou extrair imagens / quadros / metadados individuais dele no dispositivo. Ele deve ser encaminhado como está para o seu backend. Se precisar de acesso às imagens capturadas (por exemplo, [a melhor captura](/oz-knowledge/oz-knowledge/pt-br/guias/developer-guide/api/oz-api/basic-scenarios/liveness/best-shot.md)), recupere-as da resposta de análise da Oz API no lado do servidor.

Envie-o para o seu backend como `application/octet-stream`.
{% endstep %}

{% step %}

### (seu código) Envie o contêiner para a Oz API

Seu backend envia o contêiner em uma única solicitação síncrona `POST` solicitação.

**Endpoint (Instant API):**

```shellscript
POST {{host}}/api/instant/folders/
```

**Endpoint (Full API):**

```shellscript
POST {{host}}/api/folders/
```

**Cabeçalhos:**

* `Content-Type: application/octet-stream` (obrigatório).
* `X-Forensic-Access-Token: {{access_token}}`. (opcional, depende das configurações da instalação).

**Corpo da solicitação:** os bytes brutos do contêiner – sem envelope JSON, sem multipart, sem encapsulamento base64.

**Solicitação (Instant API):**

```shell
curl -X POST '{{host}}/api/instant/folders/' \\
  --header 'X-Forensic-Access-Token: {{access_token}}' ## opcional, depende das configurações da instalação
  -H 'Content-Type: application/octet-stream' \\
  --data-binary '@/path/to/container.dat'
```

**Solicitação (Full API):**

```shell
curl -X POST '{{host}}/api/folders/' \\
  --header 'X-Forensic-Access-Token: {{access_token}}' ## opcional, depende das configurações da instalação
  -H 'Content-Type: application/octet-stream' \\
  --data-binary '@/path/to/container.dat'
```

**Em caso de sucesso:** HTTP `201` com um objeto JSON de pasta descrevendo o resultado. Consulte a Etapa 6.

**Em caso de erro no nível do contêiner:** HTTP `400` – consulte [Exceções](https://doc.ozforensics.com/oz-knowledge/guides/developer-guide/api/oz-api/ozcapsula-data-container#exceptions).

Este guia cobre a análise de Liveness. Para executar uma análise de Face Matching dentro do fluxo do OzCapsula, consulte [Como Executar uma Análise de Face Matching no Fluxo do OzCapsula](https://doc.ozforensics.com/oz-knowledge/guides/developer-guide/api/oz-api/ozcapsula-data-container/how-to-perform-a-face-matching-analysis-within-ozcapsula-flow).
{% endstep %}

{% step %}

### (seu código) Trate a resposta

Seu backend agora tem a resposta – um objeto JSON de pasta descrevendo o resultado.

Tome a decisão de aceitar/rejeitar usando apenas estes dois campos de nível superior:

```json
$.resolution_status   // "FINISHED" – análises concluídas; "FAILED" – erro no processamento da análise
$.system_resolution   // "SUCCESS", "DECLINED" ou "FAILED"
```

Interprete `system_resolution`:

* `SUCCESS` – todas as verificações foram aprovadas; aceite o usuário.
* `DECLINED` – uma ou mais verificações falharam; rejeite o usuário.
* `FAILED` – um erro de sistema impediu que pelo menos uma análise fosse concluída; não trate como aceitação ou rejeição.

Para veredictos por análise (por exemplo, para saber se liveness foi aprovado, mas biometria falhou), leia `$.analyses[*].resolution_status` com os valores descritos acima.
{% endstep %}
{% endstepper %}

## Lista de verificação

* [ ] Web SDK **1.9.10+**, Oz API **6.6.1+**.
* [ ] A Etapa 1 incorpora o plugin a partir da URL fornecida pela Oz.
* [ ] A Etapa 2 obtém um novo `session_token` do seu backend antes de cada captura.
* [ ] A Etapa 3 passa isso `session_token` para `OzLiveness.open(...)`.
* [ ] A Etapa 4 pega o contêiner do segundo argumento de `on_capture_complete`; nenhuma tentativa é feita para decodificá-lo/inspecioná-lo no navegador.
* [ ] A Etapa 5 envia o contêiner para `POST {{host}}/api/instant/folders/` (Instant API) ou `POST {{host}}/api/folders/` (Full API) como bytes brutos com `Content-Type: application/octet-stream`.
* [ ] A decisão de aceitar/rejeitar usa apenas `resolution_status` e `system_resolution`.
* [ ] `session_token` nunca é armazenado em cache, reutilizado ou compartilhado entre sessões/usuários.

***

Com estas etapas, a integração básica do Web SDK em sua aplicação web está concluída. Será possível acessar a mídia gravada e os resultados da análise em [Web Console](/oz-knowledge/oz-knowledge/pt-br/guias/user-guide/oz-webui.md) via navegador ou programaticamente por meio de [API](/oz-knowledge/oz-knowledge/pt-br/guias/developer-guide/api/oz-api.md) (consulte as instruções aqui: [recuperação de um vídeo MP4](/oz-knowledge/oz-knowledge/pt-br/guias/developer-guide/sdk/oz-liveness-websdk/web-plugin/launching-the-plugin/capturing-video-and-description-of-the-on_capture_complete-callback.md#please-note), [obtenção de resultados da análise](/oz-knowledge/oz-knowledge/pt-br/guias/developer-guide/api/oz-api/basic-scenarios/liveness.md)).

Na [Guia do Desenvolvedor do Web Plugin,](https://doc.ozforensics.com/oz-knowledge/guides/developer-guide/sdk/oz-liveness-websdk/configuration-and-usage/web-plugin) podem ser encontradas instruções para as próximas etapas comuns:

* Personalização da aparência e do comportamento do plugin
* Adição de um pacote de idioma personalizado
* Ajuste do comportamento do plugin
* Parâmetros e callbacks do plugin
* Recomendações de segurança

Encontre um exemplo para Oz Liveness Web SDK [aqui](https://gitlab.com/oz-forensics/oz-liveness-sample-web/-/blob/master/OzLivenessWebSDKSample.html). Para fazer funcionar, substitua `<web-adapter-url>` pelo URL do Web Adapter que você recebeu de nós.

Para Angular e React, substitua `https://<link>.ozforensics.com` em index.html.

* [Exemplo de Angular](https://gitlab.com/oz-forensics/oz-liveness-sample-web-angular)
* [Exemplo de React](https://gitlab.com/oz-forensics/oz-liveness-sample-web-react/-/tree/main)
* [Vue](https://gitlab.com/oz-forensics/oz-liveness-sample-web-vue) sample
* [Svelte](https://gitlab.com/oz-forensics/oz-liveness-sample-web-svelte) sample


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://doc.ozforensics.com/oz-knowledge/oz-knowledge/pt-br/geral/integration-quick-start-guides/como-integrar-oz-liveness-a-sua-aplicacao-web.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.