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
QUALITYpara Liveness análises eBIOMETRYpara Face Matching análises.
Versões dos componentes
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
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.
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
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.
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.
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.
Corpo da requisição:
A resposta conterá o resultado da análise de Biometry.
Leia a resposta
Campos de nível superior
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[]
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.
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_codeeerror_messagepreenchido.
Para mais detalhes, consulte:
Atualizado
Isto foi útil?
