Certiface SaaS API

Sumário

Visão Geral
Ambientes
Autenticação
Criação do token

4.1. Modo A

4.2. Modo B
Tipo de Jornada
Retorno da Url
Webhook
Cancelamento do token
Consulta do resultado
Estrutura da resposta do resultado
Biometria do Documento
Códigos de erro (HTTP)
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 . É possível disparar essa consulta de três formas:

returnUrl seção 7 - 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 - 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
Produção	https://apis.biometria.io/certiface-saas

A base URL é concatenada com as rotas deste guia. Exemplo: https://apis.biometria.io/certiface-saas/api/v1/login.

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).

POST /api/v1/login

Headers

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:

{
  "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 - é 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 <jwt>:

{
  "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:

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.

{
  "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<string>`	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 . 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<string>	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.
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 .
webhook	`object`	Não	Configuração de webhook por token. Ver seção 8 .

❗️
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.

🔍
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 .

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 . 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 , depois a criação usando o Bearer obtido.

POST /api/v1/protected/genToken

Authorization: Bearer <jwt-do-login>
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

{
  "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 .

📘
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

"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 ou use o webhook seção 8 .

7. Webhook

Para receber uma notificação automática ao final da jornada, envie o objeto webhook na criação do token.

Configuração

"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. Ao receber, consulte GET /api/v1/token/tokenGerado para confirmar o status.

Payload entregue (corpo POST)

{
  "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=<base64>`.
`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=<assinatura>. Para validar:

Pegue o valor de X-Certiface-Timestamp e o corpo cru (bytes recebidos).

Concatene timestamp + "." + corpo.

Calcule o HMAC-SHA256 com o seu secret e codifique em Base64.

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 <token>`
`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:[email protected]/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.

DELETE /api/v1/token/tokenGerado

Headers da Requisição

Authorization: Bearer <jwt-do-login>

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.

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 <jwt-do-login>

📘
A consulta usa o mesmo JWT do login
A consulta usa o mesmo JWT do login seção 3 - 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).

{
  "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": "<selfie em base64>",
      "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<string>`	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 .

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.

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.

CPF
15929792038
25178629078
34963067005
44707559077
57742988097

CPF
69680042081
77571154006
80277279011
91995827088
07034479046

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.

{
  "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:

ResponseClientDadosOcrDTO

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

{
  "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.

{
  "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:

{
  "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:

{
  "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.

{
  "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.

{
  "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.

{
  "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:

{
  "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.