For the complete documentation index, see llms.txt. This page is also available as Markdown.

Como integrar o Oz Liveness usando o modo não persistente do Oz API

Este guia orienta a integração completa: obter um token de sessão, capturar mídia com o SDK, enviar o resultado OzCapsula container para o Oz Instant API, ler a resposta, tomar a decisão de aceitar/rejeitar, reduzir o tamanho da resposta e executar diagnósticos mínimos.

Este fluxo combina três coisas:

  • Modo de captura – o Web SDK (ou Mobile SDK) captura o vídeo de Liveness no navegador/app e seu backend o encaminha para o Oz API. Os resultados da captura não são enviados do SDK diretamente para o Oz API; seu backend atua como intermediário.

  • OzCapsula – um contêiner binário criptografado proprietário. O SDK empacota a mídia capturada e os metadados nele; o Oz API o descriptografa e processa. Ele protege os dados capturados contra adulteração entre o dispositivo do usuário e o Oz API. 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 seu backend. Se for necessário acessar imagens capturadas (por exemplo, a melhor captura), recupere-as da resposta de análise do Oz API no lado do servidor.

  • Instant API – o modo não persistente do Oz API. Os resultados são retornados imediatamente na resposta e nada é armazenado, a menos que se queira salvar dados para auditoria no S3.

Em conjunto: o SDK captura e empacota a mídia em OzCapsula → seu backend encaminha o contêiner para o Oz Instant API → o Oz API retorna o resultado de forma síncrona, sem armazenar nada.

Não abordado: Full API, non-OzCapsula, Collection, fluxos de trabalho diretos Web SDK ↔ Oz API.

Glossário

Alguns termos usados ao longo deste guia:

  • {{host}} – a URL base da sua implantação do Oz API. Fornecida durante a configuração da implantação.

  • Token de sessão – um token de curta duração que vincula um OzCapsula a uma sessão de captura específica, impedindo a reprodução do mesmo contêiner posteriormente. Obrigatório para OzCapsula.

  • Pasta – o objeto de resposta que o Oz API cria para uma única submissão. Ele agrupa a mídia enviada e as análises aplicadas a ela.

  • Tipo de análise – o que o Oz API executa na mídia. A API retorna QUALITY para Liveness análises e BIOMETRY para Face Matching análises.

Versões dos componentes

Componente
Versão mínima

Oz API

6.6.1

SDKs móveis (iOS, Android)

10.0.0

Web SDK

1.9.10

Configuração inicial

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

OzCapsula requer um token de sessão para cada sessão de captura.

Para habilitar a funcionalidade de token de sessão, gere um par de chaves JWT. Encontre as instruções para criá-las no chart Helm do Instant API: acesse readme.md e, na Preparação seção, localize a subseção Criar um segredo JWT. Depois de ter as chaves, crie uma pasta dentro da instalação, coloque as chaves lá e insira este caminho em API_KEYS_DIR (por exemplo, API_KEYS_DIR=/opt/oz/api/keys). Isso deve ser feito uma vez para a instalação.

Instruções de uso

1

Obtenha um token de sessão

Obtenha um token de sessão do Oz Instant API. Solicite um antes de cada sessão de captura, o mais próximo possível do momento em que o usuário inicia a captura, e repasse-o imediatamente ao SDK – não armazene em cache nem reutilize tokens entre sessões.

Endpoint:

Cabeçalhos:

  • Content-Type: application/json

Requisição:

Resposta:

O token tem curta duração (tempo de vida padrão: 120 segundos para o Instant API).

O mecanismo de autorização para a chamada ao Oz API depende da instalação; por padrão, nenhum token de acesso é necessário nos cabeçalhos. Se ele for exigido no seu caso, consulte Autenticação.

2

Capture e empacote no dispositivo

O SDK captura mídia do usuário e a empacota em um OzCapsula contêiner.

Mobile SDK (iOS, Android)

Inicie a análise com o token de sessão. O contêiner é retornado por meio do callback de resultado.

Android (Kotlin)

iOS (Swift)

O contêiner é retornado como um bytearray (Android) ou Data (iOS). Encaminhe-o ao seu backend sem nenhuma transformação.

Web SDK

Certifique-se de que os seguintes parâmetros de configuração estejam definidos no seu arquivo de configuração:

  • architecture: lite

  • use_wasm_container: true

  • api_use_session_token: client

Chame OzLiveness.open() com o token de sessão. Quando a captura é concluída, o SDK dispara o on_capture_complete callback. O contêiner é fornecido como o segundo argumento.

O contêiner chega como um Blob com tipo MIME application/octet-stream. Encaminhe-o ao seu backend sem nenhuma transformação.

3

Análise de Liveness: envie o contêiner para o Instant API

Seu backend envia o contêiner em uma única POST requisição.

Endpoint:

Cabeçalhos:

  • Content-Type: application/octet-stream (obrigatório)

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

Em caso de sucesso: HTTP 201 com um objeto JSON de pasta descrevendo o resultado.

Em caso de erro no nível do contêiner: HTTP 400 (veja Resultados sem sucesso).

A QUALITY análise (Liveness) fornece a melhor captura. Localize a QUALITY entrada em analyses[] matriz e leia:

O valor é um JPEG codificado em base64. Decodifique-o para JPEG.

4

Análise de Biometry (Face Matching) (opcional)

Se não for necessário correspondência facial, pule esta etapa e vá diretamente para Etapa 5.

Chame POST /api/instant/folders/ com sua foto de referência e a melhor captura obtida na análise de Liveness na Etapa 3.

As chaves dos seus arquivos de mídia e os respectivos nomes de arquivo devem corresponder.

Corpo da requisição:

A resposta conterá o resultado da análise de Biometry.

5

Leia a resposta

Campos de nível superior

Campo
Uso

folder_id

Identificador exclusivo da requisição

resolution_status

Se o processamento foi concluído: FINISHED ou FAILED

system_resolution

Resultado geral: SUCCESS, DECLINED, ou FAILED

resolution_comment

Observação sobre a resolução da análise. Útil em FAILED (lista quais análises falharam)

meta_data

Bloco de metadados. O bloco contém event_session_id, o identificador da sessão necessário para rastrear a requisição até a sessão do usuário no frontend

media

Arquivos de mídia enviados no contêiner

analyses

Matriz de resultados por análise

Dentro de analyses[]

Campo
Uso

type

QUALITY para Liveness, BIOMETRY para correspondência facial

estado

Estado de processamento desta análise: FINISHED ou FAILED

resolution_status

Resultado desta análise: SUCCESS, DECLINED, ou FAILED

error_code, error_message

Exibido apenas quando a análise falhou tecnicamente

results_data

Valores de resultado agregados

results_media

Itens de mídia gerados. Para a QUALITY análise, contém a melhor captura em output_images[] – veja Etapa 3

source_media

Mídia de entrada

Tome a decisão de aceitar/rejeitar

Use apenas estes dois campos de nível superior:

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 do sistema impediu que pelo menos uma análise fosse concluída; não trate como aceitação ou rejeição (veja Resultados sem sucesso).

Para veredictos por análise (por exemplo, para saber se Liveness foi aprovado, mas Biometry falhou), leia $.analyses[*].resolution_status com os mesmos três valores.

Outros campos

A resposta também contém identificadores internos (group_id, media_association_id), hashes de arquivos, campos relacionados ao operador (operator_comment, operator_status, is_cleared), e outros campos do sistema. Eles não são necessários para o fluxo de integração descrito neste guia.

6

Resultados sem sucesso

Contêiner inválido – HTTP 400

Quando o contêiner falha na validação, o Oz API responde com HTTP 400 e error_message: "Invalid request data". O específico error_code indica a causa:

error_code

Condição

3

Payload ausente

4

Nenhuma mídia no contêiner

5

O contêiner está corrompido

13

Nenhum contêiner na requisição

14

Contêiner inválido – qualquer motivo (falha na descriptografia, assinatura, hash ou session_token falha de validação)

Códigos 13 e 14 disparam antes de o contêiner ser descompactado; os códigos 3, 4, 5 disparam após a descompactação quando o próprio payload falha na validação de regras de negócio.

Para o código 14, envie a instância do contêiner e o error_code ao suporte da Oz Forensics – a causa específica está disponível apenas nos logs do lado do servidor.

Recusado – HTTP 201

O contêiner era válido e as análises foram executadas, mas pelo menos uma verificação não foi aprovada.

  • resolution_status: FINISHED.

  • system_resolution: DECLINED.

  • resolution_comment: "[]" (não informativo – o motivo da recusa é implícito no resultado por análise).

  • Por análise resolution_status: DECLINED.

Falhou – HTTP 201

Um erro do sistema impediu que pelo menos uma análise fosse concluída.

  • resolution_status: FAILED.

  • system_resolution: FAILED.

  • resolution_comment – string que lista quais análises falharam e com qual código.

  • Por análise state: FAILED, resolution_status: FAILED, error_code e error_message preenchido.

Para mais detalhes, consulte:

Atualizado

Isto foi útil?