--- updatedAt: 2026-09-23T19:23:13.000Z agentTools: projectIndex: https://devcenter.certiface.io/llms.txt --- # Certiface SaaS API A **Certiface SaaS API** permite integrar jornadas **biométricas e documentais** em modelo SaaS. Em uma única jornada, o usuário final faz a prova de vida e, quando necessário, a captura do documento e a API retorna um resultado consolidado para apoiar a tomada de decisão do seu fluxo. ## Sumário 1. [Visão Geral](#1-visão-geral) 2. [Ambientes](#2-ambientes) 3. [Autenticação](#3-autenticação) 4. [Criação do token](#4-criação-do-token) 4.1. [Modo A](#41-modo-a-basic-auth-chamada-única) 4.2. [Modo B](#42-modo-b-jwt) 5. [Tipo de Jornada](#5-tipo-de-jornada) 6. [Retorno da Url](#6-retorno-da-url) 7. [Webhook](#6-webhook) 8. [Cancelamento do token](#7-cancelamento-do-token) 9. [Consulta do resultado](#8-consulta-do-resultado) 10. [Estrutura da resposta do resultado](#9-estrutura-da-resposta-do-resultado) 11. [Biometria do Documento](#10-biometria-do-documento) 12. [Códigos de erro (HTTP)](#11-códigos-de-erro-http) 13. [Glossário](#12-glossário) *** ## 1. Visão Geral A API foi desenhada para simplificar: * **Prova de vida (liveness)** - confirmação de que há uma pessoa real, viva, na captura. * **Validação documental** - captura da frente/verso do documento. * **OCR** - extração dos dados impressos no documento (nome, CPF, datas, etc.). * **FaceMatch** - comparação facial entre a foto do documento e a selfie da prova de vida. * **Consulta consolidada** - um único resultado reunindo prova de vida, documento e biometria. A integração é feita por uma **API REST**, com payloads em JSON sobre HTTPS, e pode ser consumida a partir de qualquer linguagem ou plataforma. *** **Visão Geral do Fluxo:** Um **token** representa uma solicitação de verificação para uma pessoa. O ciclo de integração é: | Passo | Ação | Endpoint | | ----- | ------------------------------------------------------------------- | ---------------------------------- | | 1 | Autenticar o operador e obter o **JWT** | `POST /api/v1/login` | | 2 | Criar o token | `POST /api/v1/protected/genToken` | | 3 | Entregar a `url` retornada ao usuário final (ele executa a jornada) | - | | 4 | Consultar o resultado | `GET /api/v1/token/tokenGerado` | | 5 | *(opcional)* Cancelar um token ainda aberto | `DELETE /api/v1/token/tokenGerado` | ### **Quando consultar o resultado:** O resultado é sempre obtido com `GET /api/v1/token/tokenGerado` [passo 4](https://devcenter.certiface.io/docs/certiface-saas-api#4-cria%C3%A7%C3%A3o-do-token) . É possível disparar essa consulta de três formas: - **returnUrl** [seção 7](https://devcenter.certiface.io/docs/certiface-saas-api#7-returnurl) - ao concluir, o usuário é redirecionado de volta ao seu sistema com o `token` na URL; use isso como gancho para consultar. - **webhook** [seção 8](https://devcenter.certiface.io/docs/certiface-saas-api#8-webhook) - a Certiface notifica o seu backend automaticamente ao finalizar. - **polling** - consultar periodicamente até o `status` retornar `true`. É a opção mais simples, mas evite intervalos muito curtos. *** ## 2. Ambientes | Ambiente | Base URL | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | Homologação | [https://apis-dev.biometria.io/certiface-saas](https://apis-dev.biometria.io/certiface-saas "https://apis-dev.biometria.io/certiface-saas") | | Produção | | A base URL é concatenada com as rotas deste guia. Exemplo: . > As credenciais de operador (login/senha) são fornecidas pela CertiFace e são diferentes por ambiente. *** ## 3. Autenticação A API usa **JWT Bearer**. Após a autenticação é retornado um token JWT e o envia no header `Authorization` das chamadas protegidas (criação, consulta e cancelamento do token). **Endpoint** Endpoint público (não requer autenticação prévia). ```http POST /api/v1/login ``` **Headers** ```http Content-Type: application/json ``` **Request** A `password` deve ser enviada como **hash MD5** (hexadecimal, em minúsculas) da senha do operador, **não** em texto puro: ```json { "login": "seu-operador", "password": "5f4dcc3b5aa765d61d8327deb882cf99" } ``` **Senha em MD5 neste endpoint:** No `POST /api/v1/login` a `password` é o **MD5 da senha** do operador. (No modo Basic Auth - `POST /api/v1/token`, [seção 4](https://devcenter.certiface.io/docs/certiface-saas-api#4-cria%C3%A7%C3%A3o-do-token) - é o contrário: a senha vai em **texto puro**, e a API calcula o hash internamente.) **Response **`200` O JWT volta tanto no corpo quanto no header `Authorization: Bearer `: ```json { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } ``` `401`** para credenciais inválidas.** **O JWT tem validade curta** O JWT expira em poucos minutos (20 por padrão). Reautentique quando expirar. O **mesmo JWT do login** é usado para criar o token, **consultar o resultado** e cancelar. Use o token em todas as chamadas protegidas: ```json Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... ``` *** ## 4. Criação do token Existem **dois jeitos** de criar um token. Ambos recebem **o mesmo corpo** e devolvem **a mesma resposta**. A diferença é apenas **como você se autentica**. O mesmo corpo vale para o Modo A e o Modo B. ```json { "documentNumber": "00000014141", "birthDate": "20/12/1960", "fullName": "Nome Completo", "phones": ["11999999999", "1133334444"], "processType": "ALT", "journeyType": 2, "livenessProvider": "face_v2", "livenessReject": ["HANDS_ARMS", "SUNGLASSES", "CLOSED_EYES"], "geolocation": false, "tokenExpirationSeconds": 86400, "returnUrl": "https://cliente.example/finalizado?token={token}", "webhook": { "url": "https://cliente.example/webhooks/certiface", "events": ["JOURNEY_FINISHED", "JOURNEY_CANCELLED"], "secret": "seu-segredo-compartilhado" } } ``` | Campo | Tipo | Obrigatório | Descrição | | ---------------------- | --------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | documentNumber | `string` | **Sim** | CPF do usuário (com ou sem máscara). É validado. | | birthDate | `string` | Não | Data de nascimento no formato `dd/MM/yyyy`. Se ausente ou inválida, a API busca o valor pelo `documentNumber` (CPF). | | fullName | `string` | Não | Nome completo (mínimo nome + sobrenome). Se ausente ou inválido, a API busca o valor pelo `documentNumber` (CPF). | | phones | `array` | Não | Telefones do usuário (cada um até 20 caracteres). O **primeiro** item é tratado como telefone principal; os demais como adicionais. | | processType | `string` | Não | Tipo de processo solicitado (máximo 50 caracteres), definido pelo fluxo do cliente. Ex.: `CADASTRO`, `ALT DADOS`. | | journeyType | `integer` | Não | Tipo de jornada. [Ver seção 6](https://devcenter.certiface.io/docs/certiface-saas-api#6-journeytype) . Padrão `1`. | | livenessProvider | `string` | Não | Provedor de prova de vida desejado: `FACETEC` ou `FORTFACE`. Também aceita os aliases `face_v1` (= FACETEC) e `face_v2` (= FORTFACE), case-insensitive. **OBS**: a CertiFace pode definir o provedor final conforme as regras de negócio da sua conta. | | livenessReject | array\ | Não | Lista de condições de captura que devem reprovar a prova de vida. Só é aceito quando `livenessProvider` é `FORTFACE`/`face_v2`. Valores aceitos (case-insensitive): `HANDS_ARMS` (mão/braço no rosto), `SUNGLASSES` (óculos cobrindo os olhos), `CLOSED_EYES` (os dois olhos fechados). Enviado com outro provedor, ou com valor desconhecido, retorna `400`. | | geolocation | `boolean` | Não | Controla a captura de localização na jornada. Padrão true. Com false, a jornada não solicita localização ao usuário e o bloco geolocation não é retornado no resultado [Ver seção 11](#11-estrutura-da-resposta-do-resultado). | | tokenExpirationSeconds | `integer` | Não | Tempo de vida do token, em segundos. Padrão definido pela sua conta; não pode exceder o máximo configurado. Aceita também os aliases `expiresInSeconds`, `expirationSeconds`, `tokenExpiresInSeconds`. | | returnUrl | `string` | Não | URL de redirecionamento ao fim da jornada. [Ver seção 7](https://devcenter.certiface.io/docs/certiface-saas-api#7-returnurl) . | | webhook | `object` | Não | Configuração de webhook por token. [Ver seção 8](https://devcenter.certiface.io/docs/certiface-saas-api#8-webhook) . | Erros de validação retornam `422`. Para `fullName/birthDate`, o `422` só ocorre quando o valor enviado é inválido e a consulta pelo CPF também não conseguir retornar um valor válido. Para `livenessReject/livenessProvider` inválidos, ver `400` na [seção 13](#13-códigos-de-erro-http). `livenessReject` é case-insensitive tanto no provedor quanto nos valores da lista - "face_v2", "FACE_V2", "hands_arms" etc. são todos aceitos. *** ### 4.1. Modo A: Basic Auth (chamada única) Uma única chamada, sem login prévio. É enviado o login e senha do operador via **HTTP Basic** no header `Authorization`, e o token é criado diretamente. `POST /api/v1/token` ``` Authorization: Basic base64("login:senha") Content-Type: application/json ``` Aqui a senha vai em **texto puro** (a API calcula o hash internamente) - diferente do `POST /api/v1/login`, onde a senha é enviada já em **MD5** [seção 3](https://devcenter.certiface.io/docs/certiface-saas-api#3-autentica%C3%A7%C3%A3o) . Use este modo para integrações **simples / pontuais**, em que você prefere não gerenciar o ciclo de vida do JWT. **O Basic Auth só serve para criar** O modo Basic Auth (`POST /api/v1/token`) só **cria** o token. A **consulta** e o **cancelamento** sempre exigem o **JWT Bearer** do login [seção 3](https://devcenter.certiface.io/docs/certiface-saas-api#3-autentica%C3%A7%C3%A3o) . Ou seja, mesmo usando o Modo B, para consultar o resultado você precisará chamar `POST /api/v1/login` e usar o JWT. *** ### 4.2. Modo B: JWT Duas chamadas: primeiro o login [seção 3](https://devcenter.certiface.io/docs/certiface-saas-api#3-autentica%C3%A7%C3%A3o) , depois a criação usando o `Bearer` obtido. `POST /api/v1/protected/genToken` ``` Authorization: Bearer Content-Type: application/json ``` Use este modo quando você cria **vários tokens** com uma mesma sessão: faz o login uma vez e reaproveita o JWT até ele expirar. *** **Resposta da criação** Resposta da criação em ambos os modos: **Response **`200` ```json { "uuid": "be78d31f-31be-4903-a340-33589787c66", "url": "https://certiface.example.io/?token=be78d31f-31be-4903-a340-33589787c66" } ``` | Campo | Descrição | | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `uuid` | O **token** gerado. É ele que você usa para consultar/cancelar e que identifica a verificação. | | `url` | URL da jornada. **Entregue esta URL ao usuário final** (link, redirect, QR Code). É nela que ele faz a prova de vida e, quando aplicável, a captura do documento. | *** ## 5. Tipo de Jornada O `journeyType` define **o que o usuário fará na jornada**: | Valor | Jornada | O que o usuário faz | | ----- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `1` | Liveness com Bureau | **Prova de vida** (selfie com detecção de vivacidade) combinada com a **consulta ao Bureau** (validação cadastral). É o padrão quando o campo é omitido. | | `2` | Liveness com Bureau + Documento | O mesmo da jornada `1`, **seguido da captura do documento** (frente/verso), com OCR e comparação facial documento vs. selfie. | A escolha em `journeyType = 2` é o que faz a resposta de consulta incluir o bloco `documentBiometry` [seção 12](https://devcenter.certiface.io/docs/certiface-saas-api#12-documentbiometry-jornada-com-documento) . `processType` não tem relação com `journeyType`. Quem escolhe a jornada é o `journeyType`. *** ## 6. Retorno da Url `returnUrl` é a URL para a qual o **frontend da jornada** redireciona o usuário **ao terminar**. É opcional e útil para devolver o usuário ao seu fluxo (ex.: tela de "concluído"). * Deve ser uma URL `https` absoluta (com host). * Pode conter o placeholder `token`, que a API substitui pelo token gerado antes de congelar a jornada. Assim, ao ser redirecionado, seu sistema sabe qual verificação consultar. * Limite de 2048 caracteres. **Exemplo** ```json "returnUrl": "https://cliente.example/finalizado?token={token}" ``` Resultado do redirect (com o token já substituído): ``` https://cliente.example/finalizado?token=be78d31f-31be-4903-a340-33589787c66 ``` O `returnUrl` apenas redireciona o **navegador** do usuário; ele **não** carrega o resultado. Para obter o resultado, consulte o token [seção 10](https://devcenter.certiface.io/docs/certiface-saas-api#10-consulta-do-resultado) ou use o webhook [seção 8](https://devcenter.certiface.io/docs/certiface-saas-api#8-webhook) . *** ## 7. Webhook Para receber uma notificação automática ao final da jornada, envie o objeto webhook na criação do token. **Configuração** ```json "webhook": { "url": "https://cliente.example/webhooks/certiface", "events": ["JOURNEY_FINISHED"], "secret": "seu-segredo-compartilhado", "auth": { "type": "BEARER_TOKEN", "token": "opaque-token" } } ``` | Campo | Obrigatório | Descrição | | ------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | url | sim | Endpoint **HTTPS** do seu sistema que receberá a notificação. | | events | não | Eventos desejados: `JOURNEY_FINISHED` (jornada finalizada) e/ou `JOURNEY_CANCELLED` (jornada cancelada). Se omitido, o webhook é acionado para os dois eventos. | | secret | não | Segredo compartilhado para **assinar** o payload (HMAC-SHA256). Recomendado. | | auth | não | Autenticação que a Certiface usará **ao chamar o seu endpoint**. Ver abaixo. | *** ** Evento JOURNEY\_FINISHED** Disparado quando a jornada do token chega ao fim (concluída - aprovada ou reprovada). Ao receber, consulte `GET /api/v1/token/tokenGerado` para obter o resultado consolidado. *** **Evento JOURNEY\_CANCELLED** Disparado quando o token/jornada é cancelado antes de finalizar [ver seção 9](#9-cancelamento-do-token). Ao receber, consulte `GET /api/v1/token/tokenGerado` para confirmar o status. *** **Payload entregue (corpo POST)** ```json { "event": "JOURNEY_FINISHED", "token": "be78d31f-31be-4903-a340-33589787c66", "timestamp": "2026-05-18T01:25:00-03:00" } ``` | Campo | Descrição | | --------- | ------------------------------------------------------------------------------------------------------------------ | | event | `JOURNEY_FINISHED` ou `JOURNEY_CANCELLED`, conforme o evento ocorrido e o que foi configurado em `webhook.events`. | | token | O token cuja jornada finalizou. Use-o na consulta do resultado. | | timestamp | Momento do evento (fuso `America/Sao_Paulo`, ISO-8601 com offset). | *** **Headers da entrega** | Header | Descrição | | --------------------------------- | ------------------------------------------------------------------ | | `X-Certiface-Webhook-Version` | Versão do contrato do webhook (`1`). | | `X-Certiface-Event` | Nome do evento. | | `X-Certiface-Token` | Token relacionado. | | `X-Certiface-Delivery` | Identificador único da entrega. | | `X-Certiface-Sent-At` | Momento do envio. | | `X-Certiface-Timestamp` | *(quando há *`secret`*)* Timestamp usado na assinatura. | | `X-Certiface-Signature` | *(quando há *`secret`*)* Assinatura no formato `v1=`. | | `X-Certiface-Signature-Algorithm` | *(quando há *`secret`*)* `HMAC-SHA256`. | *** **Verificação da assinatura** Quando é definido `secret`, cada entrega vem assinada para garantir que veio da Certiface e não foi adulterada. A assinatura é calculada assim: ``` assinatura = Base64( HMAC_SHA256( secret, "{X-Certiface-Timestamp}.{corpo-json-cru}" ) ) ``` O header `X-Certiface-Signature` traz `v1=`. Para validar: 1. Pegue o valor de `X-Certiface-Timestamp` e o **corpo cru** (bytes recebidos). 2. Concatene `timestamp + "." + corpo`. 3. Calcule o HMAC-SHA256 com o seu `secret` e codifique em Base64. 4. Compare (comparação de tempo constante) com o valor após `v1=` em `X-Certiface-Signature`. *** **Autenticação no seu endpoint (webhook.auth)** Define como a Certiface se autentica **ao chamar a sua **`url`. Tipos suportados: | `type` | Campos necessários | Comportamento na chamada | | --------------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | `NONE` | - | Sem autenticação (padrão). | | `BASIC` | `username`, `password` | `Authorization: Basic ...` | | `BEARER_TOKEN` | `token` | `Authorization: Bearer ` | | `OAUTH2_CLIENT_CREDENTIALS` | `tokenUrl`, `clientId`, `clientSecret` (e opcionalmente `scopes`, `audience`) | A Certiface obtém um access token via client credentials e o envia como `Bearer`. | * O campo `auth.type` é **opcional**: se omitido, a API infere o tipo pelos campos enviados. * URLs no formato legado `https://usuario:senha@cliente.example/webhook` são aceitas e tratadas como `BASIC` (as credenciais são removidas da URL e guardadas com segurança). *** **Entrega e retentativas** * A entrega é **assíncrona** e só ocorre **após a jornada finalizar**. * Em falhas temporárias (timeout, erro de conexão, HTTP >= 400), há **retentativas automáticas com backoff** (até 10 tentativas no total). Seu endpoint deve ser **idempotente** - a mesma entrega pode chegar mais de uma vez (use `X-Certiface-Delivery` para deduplicar). * Responda `2xx` rapidamente para confirmar o recebimento. *** ## 8. Cancelamento do token Cancela um token associado a uma jornada ainda não finalizada. Útil quando a solicitação foi criada por engano ou não será mais utilizada. ```http DELETE /api/v1/token/tokenGerado ``` **Headers da Requisição** ``` Authorization: Bearer ``` | Resposta | Significado | | -------- | -------------------------------------------------------- | | `200` | Token cancelado. | | `401` | JWT ausente ou inválido. | | `403` | O token não pertence ao escopo do operador autenticado. | | `404` | Token não encontrado. | | `409` | O token **já está finalizado** e não pode ser cancelado. | Requer o **JWT Bearer** do login (seção 3). *** ## 9. Consulta do resultado Retorna o resultado consolidado do token: dados do header, todas as tentativas e, quando a jornada incluiu documento, o bloco `documentBiometry`. ```http GET /api/v1/token/tokenGerado?images=all|liveness|document|none ``` | Parâmetro | Valores | Padrão | Descrição | | --------- | ---------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | images | `all` `liveness` `document` `none` | `all` | Controla quais imagens em Base64 vêm no corpo da resposta. `liveness` retorna só as imagens da prova de vida; `document` retorna só as do documento; `none` omite todas as imagens. Os metadados (OCR, faceMatch, geolocation, scores etc.) são sempre retornados, independente do valor. Valor desconhecido é tratado como `all`. | Use `images=none` quando só precisar checar o `status`/`result` (ex.: polling frequente) - reduz bastante o tamanho da resposta. **Headers da Requisição** ``` Authorization: Bearer ``` **A consulta usa o mesmo JWT do login** A consulta usa o **mesmo JWT do login** [seção 3](https://devcenter.certiface.io/docs/certiface-saas-api#3-autentica%C3%A7%C3%A3o) - não há credencial separada. O token só é retornado se pertencer ao escopo do operador autenticado. | Resposta | Significado | | -------- | --------------------------------------------- | | `200` | Resultado encontrado. | | `401` | JWT ausente ou inválido. | | `403` | Token fora do escopo do operador autenticado. | | `404` | Token não encontrado. | *** ## 10. Estrutura da resposta do resultado Campos `null` são omitidos; `results` está sempre presente (pode vir vazio se ainda não houver tentativas). ```json { "token": "be78d31f-31be-4903-a340-33589787c66", "documentNumber": "00000014141", "birthDate": "1960-12-20", "fullName": "Nome Completo", "phone": "11999999999", "status": true, "result": true, "createDate": "2026-05-17 12:00:00", "expirationDate": "2026-05-18 12:00:00", "phones": ["11999999999", "1133334444"], "processType": "ALT", "results": [ { "protocol": "123456789", "dateTime": "2026-05-17 12:03:10", "cause": "SUCCESS", "valid": true, "userAgent": "Mozilla/5.0 ...", "step": "liveness", "result": 1.2, "score": 850, "ip": "200.200.200.200", "geolocation": { "accuracy": 20.0, "latitude": -23.55, "longitude": -46.63, "altitude": 720.0, "altitudeAccuracy": 5.0 }, "image": "", "serpro": { "code": 0, "cause": "..." } } ] } ``` **Campos do header** | Campo | Tipo | Descrição | | -------------- | --------------- | ----------------------------------------------------------------------------------------- | | token | `string` | O token consultado. | | documentNumber | `string` | CPF do usuário. | | birthDate | `string` | Data de nascimento (`yyyy-MM-dd`). | | fullName | `string` | Nome do usuário. | | phone | `string` | Telefone principal. | | status | `boolean` | **Conclusão** do token: `true` = jornada finalizada; `false` = ainda em aberto/não usado. | | result | `boolean` | **Resultado geral**: `true` = aprovado; `false` = reprovado/não aprovado. | | createDate | `string` | Criação do token (`yyyy-MM-dd HH:mm:ss`). | | expirationDate | `string` | Expiração do token. | | phones | `array` | **Todos** os telefones informados na criação (principal + adicionais). | | processType | `string` | O `processType` enviado na criação. | | results | `array` | Detalhe das tentativas (abaixo). | **Campos de cada item de results** | Campo | Tipo | Descrição | | ---------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | protocol | `string` | Protocolo da tentativa. | | dateTime | `string` | Data/hora da tentativa (`yyyy-MM-dd HH:mm:ss`). | | cause | `string` | Motivo do resultado (ver tabela de causas). | | valid | `boolean` | Resultado da prova de vida: `true` = aprovada. | | userAgent | `string` | Informações do dispositivo do usuário. | | step | `string` | Etapa que gerou o resultado: `liveness` (prova de vida) ou `document` (documento). | | result | `float` | Código numérico do resultado (ver tabela de códigos). | | score | `integer` | Score de risco (presente quando a Classe de Risco está habilitada). | | ip | `string` | IP do usuário (presente quando habilitado para a sua conta). | | geolocation | `object` | Localização capturada. **Condicional**: presente apenas quando `geolocation` não foi definido como `false` na criação do token. | | image | `string` | Selfie da prova de vida em **Base64**. | | serpro | `object` | Resultado da validação SERPRO (condicional - ver abaixo). | | documentBiometry | `object` | Dados de documento + comparação facial, em jornadas com documento. [Ver seção 12](https://devcenter.certiface.io/docs/certiface-saas-api#12-documentbiometry-jornada-com-documento) . | **Valores de cause** | `cause` | Significado | | --------------- | -------------------------------------------------- | | SUCCESS | Usuário concluiu corretamente; aprovado. | | INVALID\_DATA | Nome, documento ou data de nascimento inválidos. | | TIMEOUT | A prova de vida ultrapassou o tempo máximo de uso. | | MAX\_ATTEMPTS | Usuário falhou nas tentativas permitidas. | | CANCELLED | A jornada/token foi cancelado. | | DOCUMENT | Problema na etapa de documento. | | PROVIDER\_ERROR | Erro no provedor de liveness. | Esses são os valores **canônicos** que a API atribui quando ela determina o desfecho da jornada. **Causas reportadas pelo passo de liveness** Quando o desfecho vem de um motivo reportado pelo próprio passo de prova de vida, esse motivo é devolvido **como recebido, em letras maiúsculas** - ou seja, o `cause` pode trazer um texto fora da lista canônica acima. Trate a lista como os valores garantidos e o `cause` como um campo de texto: compare por igualdade com os valores conhecidos e tenha um tratamento padrão para os demais. **Códigos de result** | Código | Significado | | ------- | ---------------------------------- | | `1.1` | Cadastro realizado com sucesso | | `1.2` | Certificação positiva | | `200.1` | Cadastro com alertas | | `200.2` | Certificação negativa | | `200.3` | Certificação positiva desconhecida | | `200.4` | Certificação negativa desconhecida | | `200.5` | Cadastro com risco | | `300.1` | Prova de vida inválida | | `300.2` | Prova de vida bloqueada | **geolocation** > 📘Bloco condicional. Não aparece quando o token foi criado com "geolocation": `false` [seção 5](#5-corpo-da-criação-do-token-campos). | Campo | Tipo | Descrição | | ---------------- | ------- | ------------------------------------ | | accuracy | `float` | Precisão das coordenadas (lat/long). | | latitude | `float` | Latitude. | | longitude | `float` | Longitude. | | altitude | `float` | Altitude. | | altitudeAccuracy | `float` | Precisão da altitude. | **serpro (condicional)** Presente quando a **Classe de Risco** está habilitada para a sua conta. | Campo | Tipo | Descrição | | ----- | --------- | ------------------------------------------------------------------------------ | | code | `integer` | Código de retorno da validação SERPRO. | | cause | `string` | Detalhe/motivo da validação SERPRO (ex.: `Falha da validacao serpro - DV040`). | ### Homologação Em homologação, os retornos **positivo** e **negativo** da validação Serpro estão limitados a um conjunto específico de CPFs de teste. Qualquer outro CPF retorna **Serpro não encontrado**.
Consulte a lista de CPFs de teste #### Retorno positivo (validação positiva) | CPF | | :---------- | | 15929792038 | | 25178629078 | | 34963067005 | | 44707559077 | | 57742988097 | #### Retorno negativo (validação negativa) | CPF | | :---------- | | 69680042081 | | 77571154006 | | 80277279011 | | 91995827088 | | 07034479046 | #### Demais CPFs Qualquer CPF fora das listas acima retorna **Serpro não encontrado**.
*** ## 11. Biometria do Documento Quando o token é criado com `journeyType = 2` (liveness + documento), o item de `results` correspondente à etapa de documento traz o bloco `documentBiometry` com os dados extraídos do documento (OCR), a comparação facial (documento vs. selfie) e as imagens capturadas. ```json { "token": "4c8254aa-01bf-4ac0-8849-071f9ae21b17", "documentType": 1, "documentNumber": "00000014141", "birthDate": "1960-12-20", "fullName": "NOME SOBRENOME", "phone": "11977777777", "status": true, "result": true, "expirationDate": "2026-01-14 16:41:07", "createDate": "2026-01-13 16:41:07", "listPhone": [ "11977777777" ], "processType": "CADASTRO", "results": [ { "protocol": "20260002025", "dateTime": "2026-01-13 16:41:30", "cause": "SUCCESS", "valid": true, "step": "other", "result": 200.0, "image": "/9j..." }, { "protocol": "202600072965", "dateTime": "2026-01-13 16:42:10", "cause": "SUCCESS", "valid": true, "step": "document", "documentBiometry": { "protocol": "202600072965", "ocr": { "responseClientDadosOcrDTO": { "responseClientRGOcrDTO": { "estado": "SP", "documento": "RG", "dtExpedicao": "18/07/2019", "dtExpedicaoFormatada": "2019-07-18", "nrRg": "99.999.999-9", "nome": "NOME SOBRENOME", "filiacao": "NOME DO PAI\nNOME DA MAE", "nomePai": "NOME DO PAI", "nomeMae": "NOME DA MAE", "dtNascimento": "27/05/1984", "dtNascimentoFormatada": "1984-05-27", "cpf": "999999999/99", "pretoEBranco": false, "naturalidade": "SAO PAULO - SP", "nomenclatura": "ESTADO DE SAO PAULO\nSECRETARIA DA SEGURANÇA PÚBLICA", "dtCriacao": "2021-07-30 21:45:20", "flAnalfabeto": "True" }, "ResponseClientCNHOcrDTO": { "estado": "SP", "documento": "CNH", "nome": "NOME SOBRENOME", "docOrigem": "99999999 XX/XX", "documentoOrigem": "99999999", "emissorOrigem": "SSP", "ufOrigem": "SP", "cpf": "XXX.XXX.XXX-XX", "pretoEBranco": false, "dtNascimento": "20/01/1990", "dtNascimentoFormatada": "1990-01-20", "filiacao": "NOME DO PAI\nNOME DA MAE", "nomePai": "NOME DO PAI", "nomeMae": "NOME DA MAE", "permissao": "NULL", "acc": "NULL", "categoria": "XXXXX", "numeroRegistro": "99999999999", "validade": "20/03/1990", "primeiraHabilitacao": "20/01/1990", "local": "SÃO PAULO, SP", "dtExpedicao": "20/01/1990", "dtExpedicaoFormatada": "1990-01-20", "codSeguranca": "9999999999", "espelho": "9999999999", "estadoNome": "ESTADO", "renach": "XX999999999", "dtCriacao": "1990-01-20 21:45:20" }, "ResponseClientDNIOcrDTO": { "estado": "SP", "nomenclatura": "ESTADO DE SAO PAULO\nSECRETARIA DA SEGURANÇA PÚBLICA", "naturalidade": "SAO PAULO - SP", "filiacao": "NOME DO PAI\nNOME DA MAE", "nomePai": "NOME DO PAI", "nomeMae": "NOME DA MAE", "dtNascimento": "20/01/1990", "dtNascimentoFormatada": "1990-01-20", "nome": "NOME SOBRENOME", "observacaoFront": "XXXXXXXXXXXXXXX", "outroRG": "99.999.999-9", "orgao": "XXXXXX-XX", "fator": "XXX", "registroCivil": "CERTIDÃO DE CASAMENTO TESTE", "cnh": "99999999999", "cns": "99999999999", "cpf": "XXX.XXX.XXX-XX", "pretoEBranco": false, "ctps": "XXXXXXXX", "serieCTPS": "XXX", "ufctps": "XX", "dni": "XXXXXXXXXXXXXXX", "tituloEleitor": "XXXX.XXXX.XXXX", "dtExpedicao": "20/01/1990", "dtExpedicaoFormatada": "1990-01-20", "local": "P.:49", "certMilitar": "XXXXXXXXXXXXXX", "nomeSocial": "NOME SOCIAL", "pis": "XXXXXXXXXX-X", "profissional": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "rg": "99.999.999-9", "dtCriacao": "1990-01-20 21:45:20", "flAnalfabeto": "True" }, "ResponseClientCINOcrDTO": { "documento": "CIN", "nomenclatura": "REPUBLICA FEDERATIVA DO BRASIL", "nome": "NOME SOBRENOME", "cpf": "XXX.XXX.XXX-XX", "pretoEBranco": false, "sexo": "F", "dtNascimento": "24/09/1956", "nacionalidade": "BRA", "naturalidade": "ALEGRETE/RS", "dtValidade": "INDETERMINADA", "nrEspelho": "000000000", "posto": "00050000", "filiacao": "PAI\nMAE", "orgaoEmissor": "INSTITUTO GERAL DE TESTE", "local": "PORTO ALEGRE", "dtExpedicao": "06/04/2023", "analfabeto": false, "dtExpedicaoFormatada": "2023-04-06", "dtNascimentoFormatada": "1956-09-24", "dtCriacao": "2023-08-25 12:30:35" }, "ResponseClientDadosOcrDTO": { "responseClientOcrDto": { "nome": "LUIZ GUILHERME SANTOS GALDINO", "cpf": " ", "pretoEBranco": "false", "nrPassaporte": "FW992769", "dtNascimento": "1961-09-06", "sexo": "M", "dtExpedicao": "2018-09-18", "nacionalidade": "BRASILEIRO(A)", "autoridadeEmissora": "SR/DPF/ES", "paisEmissor": "BRA", "tpPassaport": "P", "naturalidade": "VITÓRIA/ES", "documento": "PASSPORT" }, "ResponseClientOcrDto": { "nome": "PAULO MIGUEL PALHA DE SOUSA", "cpf": "06085048742", "pretoEBranco": false, "nrRnm": "B367003-0", "dtNascimento": "1982-01-21", "sexo": "M", "dtExpiracao": "2034-06-30", "nomePais": "RUI FERNANDO GASPAR DE SOUSA ANA MARIA PEREIRA GARCEZ PALHA", "nacionalidade": "PORTUGAL", "autoridadeEmissora": "PF", "classificacao": "RESIDENTE", "documento": "CRNM" } } } }, "faceMatch": { "code": "200", "cause": "Validacao positiva", "score": "0.80692" }, "front": "/9j...", "back": "/9j...", "documents": [ { "description": "FACE A", "side": "FRONT", "image": "/9j..." }, { "description": "FACE B", "side": "BACK", "image": "/9j..." } ] } } ] } ``` | Campo | Tipo | Descrição | | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------ | | protocol | `string` | Protocolo da análise de documento. | | ocr | `object` | Campos extraídos do documento (OCR). O conjunto de campos varia conforme o tipo de documento - ver tabelas abaixo. | | faceMatch | `object` | Comparação facial entre a foto do documento e a selfie da prova de vida. | | faceMatch.code | `string` | Código do resultado da comparação. | | faceMatch.cause | `string` | Descrição/motivo da comparação. | | faceMatch.score | `string` | Similaridade (quanto maior, mais semelhante). | | documents | `array` | Imagens capturadas, cada uma com `description`, `side` (`FRONT`/`BACK`) e `image` (Base64). | **Campos de OCR por Tipo de Documento** O OCR identifica automaticamente o tipo de documento (RG, CNH, DNI, CIN, CRNM ou Passaporte) e retorna apenas os **campos textuais** extraídos. As imagens capturadas do documento são disponibilizadas separadamente no campo `documents`. Campos sem informação não são retornados, e as datas podem ser fornecidas tanto no formato original do documento (`dd/MM/yyyy`) quanto em formato normalizado (`yyyy-MM-dd`). Selecione o documento para visualizar os campos retornados pelo OCR:
RG ResponseClientDadosOcrDTO

Trata-se do conjunto de dados retornados pelo OCR conforme o documento enviado para análise. Neste exemplo, o retorno corresponde ao RG.

```json { "responseClientDadosOcrDTO": { "responseClientRGOcrDTO": { "estado": "SP", "documento": "RG", "dtExpedicao": "18/07/2019", "dtExpedicaoFormatada": "2019-07-18", "nrRg": "99.999.999-9", "nome": "NOME SOBRENOME", "filiacao": "NOME DO PAI\nNOME DA MAE", "nomePai": "NOME DO PAI", "nomeMae": "NOME DA MAE", "dtNascimento": "27/05/1984", "dtNascimentoFormatada": "1984-05-27", "cpf": "999999999/99", "pretoEBranco": false, "naturalidade": "SAO PAULO - SP", "nomenclatura": "ESTADO DE SAO PAULO\nSECRETARIA DA SEGURANÇA PÚBLICA", "dtCriacao": "2021-07-30 21:45:20", "flAnalfabeto": "True" } } } ``` ResponseClientRGOcrDTO | Campo | Descrição | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | estado | Estado onde foi emitido o documento. | | documento | Identificação do tipo do documento. | | dtExpedicao | Data da expedição do documento (formato: dd/MM/yyyy). | | dtExpedicaoFormatada | Data da expedição do documento (formato: yyyy-MM-dd). | | dtNascimentoFormatada | Data de nascimento (formato: yyyy-MM-dd). | | nrRg | Número do documento RG. | | nome | Nome e sobrenome do titular do documento. | | filiacao | Nome do pai e nome da mãe. | | nomePai | Nome do pai. | | nomeMae | Nome da mãe. | | docOrigem | Origem do documento. | | dtNascimento | Data de nascimento (formato: dd/MM/yyyy). | | cpf | Número do CPF. | | naturalidade | Naturalidade. | | nomenclatura | Nome do órgão emissor. | | dtCriacao | Data de criação do processo (formato: yyyy-MM-dd HH:mm:ss). | | flAnalfabeto | Identificação de assinatura do usuário no documento para leitura no OCR.
Enviado de acordo com o tipo de documento (DNI, RG ou CIN).
True = documento não assinado; False = documento assinado. | | pretoEBranco | Indica se a imagem do documento está em preto e branco (true/false). |
DNI ResponseClientDadosOcrDTO Trata-se do conjunto de dados retornados pelo OCR conforme o documento enviado para análise. Neste exemplo, o retorno corresponde ao DNI. ```json { "responseClientDadosOcrDTO": { "ResponseClientDNIOcrDTO": { "estado": "SP", "nomenclatura": "ESTADO DE SAO PAULO\nSECRETARIA DA SEGURANÇA PÚBLICA", "naturalidade": "SAO PAULO - SP", "filiacao": "NOME DO PAI\nNOME DA MAE", "nomePai": "NOME DO PAI", "nomeMae": "NOME DA MAE", "dtNascimento": "20/01/1990", "dtNascimentoFormatada": "1990-01-20", "nome": "NOME SOBRENOME", "observacaoFront": "XXXXXXXXXXXXXXX", "outroRG": "99.999.999-9", "orgao": "XXXXXX-XX", "fator": "XXX", "registroCivil": "CERTIDÃO DE CASAMENTO TESTE", "cnh": "99999999999", "cns": "99999999999", "cpf": "XXX.XXX.XXX-XX", "pretoEBranco": false, "ctps": "XXXXXXXX", "serieCTPS": "XXX", "ufctps": "XX", "dni": "XXXXXXXXXXXXXXX", "tituloEleitor": "XXXX.XXXX.XXXX", "dtExpedicao": "20/01/1990", "dtExpedicaoFormatada": "1990-01-20", "local": "P.:49", "certMilitar": "XXXXXXXXXXXXXX", "nomeSocial": "NOME SOCIAL", "pis": "XXXXXXXXXX-X", "profissional": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "rg": "99.999.999-9", "dtCriacao": "1990-01-20 21:45:20", "flAnalfabeto": "True" } } } ``` ResponseClientDNIOcrDTO | Campo | Descrição | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | estado | Estado de emissão do Documento Nacional de Identidade (DNI). | | nomenclatura | Nome do órgão emissor. | | naturalidade | Naturalidade. | | filiacao | Nome do pai e nome da mãe. | | nomePai | Nome do pai. | | nomeMae | Nome da mãe. | | dtNascimento | Data de nascimento (formato: dd/MM/yyyy). | | dtNascimentoFormatada | Data de nascimento (formato: yyyy-MM-dd). | | nome | Nome e sobrenome do titular do documento. | | observacaoFront | Observação presente na frente do documento. | | outroRG | Número de outro RG, caso possua. | | orgao | Órgão emissor. | | fator | Tipo sanguíneo com fator Rh. | | registroCivil | Informação de origem do registro civil. | | cnh | Número da CNH. | | cns | Número do Cartão Nacional de Saúde (CNS). | | cpf | Número do CPF. | | ctps | Número da Carteira de Trabalho e Previdência Social (CTPS). | | serieCTPS | Série da Carteira de Trabalho e Previdência Social. | | ufctps | UF de emissão da Carteira de Trabalho e Previdência Social. | | dni | Número do Documento Nacional de Identidade (DNI). | | tituloEleitor | Número do Título de Eleitor. | | dtExpedicao | Data de expedição do DNI (formato: dd/MM/yyyy). | | dtExpedicaoFormatada | Data de expedição do DNI (formato: yyyy-MM-dd). | | local | Posto onde o DNI foi emitido. | | certMilitar | Número da Certidão Militar. | | nomeSocial | Nome social do titular. | | pis | Número do PIS. | | profissional | Identidade profissional ou CIP. | | rg | Número do RG. | | dtCriacao | Data de criação do processo (formato: yyyy-MM-dd HH:mm:ss). | | flAnalfabeto | Identificação de assinatura do usuário no documento para leitura no OCR. Enviado de acordo com o tipo de documento (DNI, RG ou CIN). True = documento não assinado; False = documento assinado. | | pretoEBranco | Indica se a imagem do documento está em preto e branco (true/false). |
CNH ResponseClientDadosOcrDTO Trata-se do conjunto de dados retornados pelo OCR conforme o documento enviado para análise. Neste exemplo, o retorno corresponde à CNH, seja física ou digital (ex.: Imagem, PDF ou Binário). **CNH Física:** ```json { "responseClientDadosOcrDTO": { "ResponseClientCNHOcrDTO": { "estado": "SP", "documento": "CNH", "nome": "NOME SOBRENOME", "docOrigem": "99999999 XX/XX", "documentoOrigem": "99999999", "emissorOrigem": "SSP", "ufOrigem": "SP", "cpf": "XXX.XXX.XXX-XX", "pretoEBranco": false, "dtNascimento": "20/01/1990", "dtNascimentoFormatada": "1990-01-20", "filiacao": "NOME DO PAI\nNOME DA MAE", "nomePai": "NOME DO PAI", "nomeMae": "NOME DA MAE", "permissao": "NULL", "acc": "NULL", "categoria": "XXXXX", "numeroRegistro": "99999999999", "validade": "20/03/1990", "primeiraHabilitacao": "20/01/1990", "local": "SÃO PAULO, SP", "dtExpedicao": "20/01/1990", "dtExpedicaoFormatada": "1990-01-20", "codSeguranca": "9999999999", "espelho": "9999999999", "estadoNome": "ESTADO", "renach": "XX999999999", "dtCriacao": "1990-01-20 21:45:20" } } } ``` **CNH Digital:** ```json { "responseClientDadosOcrDTO": { "responseClientCNHOcrDTO": { "documento": "CNH Digital", "formato": "QR Code", "extensao": "Imagem", "nome": "NOME E SOBRENOME", "docOrigem": "12345678 RG BR", "cpf": "12345678911", "dtNascimento": "01/01/2001", "dtNascimentoFormatada": "2001-01-01", "filiacao": "NOME MAE NOME PAI", "categoria": "E", "numeroRegistro": "098765432", "validade": "01/01/2030", "primeiraHabilitacao": "01/01/2019", "local": "CIDADE - UF", "renach": "BR0123456", "nomePai": "NOME PAI", "nomeMae": "NOME MAE", "observacao": "EAR" } } } ``` ResponseClientCNHOcrDTO | Campo | Descrição | | --------------------- | -------------------------------------------------------------------------- | | estado | Sigla do estado de emissão da CNH. | | estadoNome | Nome do estado de emissão da CNH. | | documento | Tipo do documento (CNH ou CNH Digital). | | nome | Nome e sobrenome do titular do documento. | | docOrigem | Dados do documento de origem: número de identificação e emissor de origem. | | documentoOrigem | Número de identificação do documento de origem. | | emissorOrigem | Emissor de origem. | | ufOrigem | UF de origem. | | cpf | Número do CPF. | | dtNascimento | Data de nascimento (formato: dd/MM/yyyy). | | dtNascimentoFormatada | Data de nascimento (formato: yyyy-MM-dd). | | filiacao | Nome do pai e nome da mãe. | | nomePai | Nome do pai. | | nomeMae | Nome da mãe. | | permissao | Indica se o documento é uma Permissão para Dirigir ("PERMISSÃO") ou NULL. | | acc | Autorização para conduzir ciclomotores. | | categoria | Categoria da habilitação (A, B, C, D, E ou combinações). | | numeroRegistro | Número de registro da CNH. | | validade | Data de validade do documento (formato: dd/MM/yyyy). | | primeiraHabilitacao | Data da primeira habilitação (formato: dd/MM/yyyy). | | local | Cidade e estado onde o documento foi emitido. | | dtExpedicao | Data de expedição do documento (formato: dd/MM/yyyy). | | dtExpedicaoFormatada | Data de expedição do documento (formato: yyyy-MM-dd). | | codSeguranca | Código de segurança do documento. | | espelho | Número de controle do documento físico. | | renach | Número do RENACH. | | dtCriacao | Data de criação do processo (formato: yyyy-MM-dd HH:mm:ss). | | pretoEBranco | Indica se a imagem do documento está em preto e branco (true/false). | | formato | Formato do documento quando enviado digitalmente (ex.: QR Code, Foto). | | extensao | Tipo do arquivo enviado (ex.: Imagem, PDF, Binário). | | observacao | Observações presentes na CNH Digital (ex.: EAR). |
CIN ResponseClientDadosOcrDTO Trata-se do conjunto de dados retornados pelo OCR conforme o documento enviado para análise. Neste exemplo, o retorno corresponde ao CIN. ```json { "responseClientDadosOcrDTO": { "ResponseClientCINOcrDTO": { "documento": "CIN", "nomenclatura": "REPUBLICA FEDERATIVA DO BRASIL", "nome": "NOME SOBRENOME", "cpf": "XXX.XXX.XXX-XX", "pretoEBranco": false, "sexo": "F", "dtNascimento": "24/09/1956", "nacionalidade": "BRA", "naturalidade": "ALEGRETE/RS", "dtValidade": "INDETERMINADA", "nrEspelho": "000000000", "posto": "00050000", "filiacao": "PAI\nMAE", "orgaoEmissor": "INSTITUTO GERAL DE TESTE", "local": "PORTO ALEGRE", "dtExpedicao": "06/04/2023", "analfabeto": false, "dtExpedicaoFormatada": "2023-04-06", "dtNascimentoFormatada": "1956-09-24", "dtCriacao": "2023-08-25 12:30:35" } } } ``` ResponseClientCINOcrDTO | Campo | Descrição | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | documento | Tipo do documento (neste caso, CIN). | | estado | Estado de emissão do documento CIN. | | nomenclatura | Nome do órgão emissor. | | nome | Nome e sobrenome do titular do documento. | | cpf | Número do CPF. | | sexo | Sexo do titular do documento. | | dtNascimento | Data de nascimento (formato: dd/MM/yyyy). | | nacionalidade | Nacionalidade. | | naturalidade | Naturalidade. | | dtValidade | Data de validade do documento. | | nrEspelho | Número espelho do documento. | | posto | Local/posto de emissão. | | filiacao | Nome do pai e nome da mãe. | | nomePai | Nome do pai. | | nomeMae | Nome da mãe. | | orgaoEmissor | Órgão emissor. | | local | Cidade onde o documento foi emitido. | | dtExpedicao | Data de expedição do documento (formato: dd/MM/yyyy). | | analfabeto | Identificação de assinatura do usuário no documento para leitura no OCR. True = documento não assinado; False = documento assinado. | | dtExpedicaoFormatada | Data de expedição do documento (formato: yyyy-MM-dd). | | dtNascimentoFormatada | Data de nascimento (formato: yyyy-MM-dd). | | dtCriacao | Data e hora do envio do documento para análise (formato: yyyy-MM-dd HH:mm:ss). | | pretoEBranco | Indica se a imagem do documento está em preto e branco (true/false). |
CRNM ResponseClientDadosOcrDTO Trata-se do conjunto de dados retornados pelo OCR conforme o documento enviado para análise. Neste exemplo, o retorno corresponde ao CRNM. ```json { "ResponseClienDadosOcrDTO": { "ResponseClientOcrDto": { "nome": "PAULO MIGUEL PALHA DE SOUSA", "cpf": "06085048742", "pretoEBranco": false, "nrRnm": "B367003-0", "dtNascimento": "1982-01-21", "sexo": "M", "dtExpiracao": "2034-06-30", "nomePais": "RUI FERNANDO GASPAR DE SOUSA ANA MARIA PEREIRA GARCEZ PALHA", "nacionalidade": "PORTUGAL", "autoridadeEmissora": "PF", "classificacao": "RESIDENTE", "documento": "CRNM" } } } ``` ResponseClientOcrDTO (CRNM) | Campo | Descrição | | ------------------ | -------------------------------------------------------------------- | | documento | Tipo do documento (neste caso, CRNM). | | nome | Nome e sobrenome do titular do documento. | | cpf | Número do CPF. | | nrRnm | Número do Registro Nacional Migratório (RNM). | | dtNascimento | Data de nascimento do titular. | | sexo | Sexo do titular do documento. | | dtExpiracao | Data de validade do documento. | | nomePais | Nome dos pais do titular do documento. | | nacionalidade | País de nacionalidade do titular. | | autoridadeEmissora | Órgão responsável pela emissão do documento. | | classificacao | Classificação migratória do titular (ex.: Residente). | | pretoEBranco | Indica se a imagem do documento está em preto e branco (true/false). |
Passaporte ResponseClientDadosOcrDTO Trata-se do conjunto de dados retornados pelo OCR conforme o documento enviado para análise. Neste exemplo, o retorno corresponde ao Passaporte. ```json { "responseClientDadosOcrDTO": { "responseClientOcrDto": { "nome": "LUIZ GUILHERME SANTOS GALDINO", "cpf": "", "pretoEBranco": false, "nrPassaporte": "FW992769", "dtNascimento": "1961-09-06", "sexo": "M", "dtExpedicao": "2018-09-18", "nacionalidade": "BRASILEIRO(A)", "autoridadeEmissora": "SR/DPF/ES", "paisEmissor": "BRA", "tpPassaport": "P", "naturalidade": "VITÓRIA/ES", "documento": "PASSPORT" } } } ``` ResponseClientOcrDTO (Passaporte) | Campo | Descrição | | ------------------ | -------------------------------------------------------------------- | | documento | Tipo do documento (neste caso, Passaporte). | | nome | Nome e sobrenome do titular do documento. | | cpf | Número do CPF, quando disponível. | | pretoEBranco | Indica se a imagem do documento está em preto e branco (true/false). | | nrPassaporte | Número do passaporte. | | dtNascimento | Data de nascimento do titular. | | sexo | Sexo do titular do documento. | | dtExpedicao | Data de expedição do passaporte. | | nacionalidade | Nacionalidade do titular. | | autoridadeEmissora | Órgão responsável pela emissão do documento. | | paisEmissor | País responsável pela emissão do passaporte. | | tpPassaport | Tipo do passaporte (comum, diplomático, oficial, etc.). | | naturalidade | Cidade ou local de nascimento do titular. |

*** ## 12. Códigos de erro (HTTP) Erros são padronizados no corpo: ```json { "timestamp": "2026-05-18T01:25:00-03:00", "status": 422, "error": "Unprocessable Entity", "message": "Invalid data", "path": "/api/v1/protected/genToken" } ``` | Código | Quando ocorre | | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `200` | Sucesso. | | `400` | Valor inválido de campo: `livenessReject` com valor desconhecido, `livenessReject` enviado sem `livenessProvider` = `FORTFACE`/`face_v2`, ou `livenessProvider` com valor desconhecido. | | `401` | Credenciais (login/senha ou JWT) inválidas ou ausentes. | | `403` | Token fora do escopo do operador autenticado. | | `404` | Token não encontrado. | | `409` | Conflito de estado (ex.: cancelar token já finalizado). | | `422` | Dados inválidos (CPF, URLs, etc.). Para nome e data de nascimento, o `422` só ocorre quando o valor enviado é inválido e a API também não consegue obtê-lo pelo CPF. | | `5xx` | Erro interno ou indisponibilidade de serviço de apoio. | *** ## 13. Glossário | Termo | Significado | | ------------------------ | ------------------------------------------------------------------------------------------------ | | Operador | Conta autenticada (login/senha) que cria, consulta e cancela tokens. | | Token | Identificador único (UUID) de uma verificação/jornada. | | Jornada (journey) | Sequência executada pelo usuário final: prova de vida e, quando aplicável, captura do documento. | | Liveness (prova de vida) | Verificação de que há uma pessoa real e viva na captura. | | Documento | Captura da frente/verso do documento de identificação. | | OCR | Leitura/extração dos dados textuais impressos no documento. | | FaceMatch | Comparação facial entre a foto do documento e a selfie da prova de vida. | | Provedor (provider) | Motor que executa a prova de vida (`FACETEC`, `FORTFACE`). | | JWT | Token de autenticação Bearer emitido no login, usado nas chamadas protegidas. | | Webhook | Callback HTTP enviado ao seu sistema quando a jornada finaliza. | | returnUrl | URL para a qual o navegador do usuário é redirecionado ao fim da jornada. |