Certiface SaaS API

Sumário

1. Visão Geral
2. Ambientes
3. Autenticação
4. Criação do token
5. Corpo da criação do token (campos)
6. journeyType
7. returnUrl
8. Webhook
9. Cancelamento do token
10. Consulta do resultado
11. Estrutura da resposta do resultado
12. documentBiometry (jornada com documento)
13. Códigos de erro (HTTP)
14. Glossário

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 é:

📘

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

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 ver seção 5 e devolvem a mesma resposta. A diferença é apenas como você se autentica.

Modo A: JWT (recomendado)

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.

Modo B: Basic Auth (chamada única)

Uma única chamada, sem login prévio. Você manda 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.

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"
}

5. Corpo da criação do token (campos)

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": "FACETEC",
  "tokenExpirationSeconds": 86400,
  "returnUrl": "https://cliente.example/finalizado?token={token}",
  "webhook": {
    "url": "https://cliente.example/webhooks/certiface",
    "events": ["JOURNEY_FINISHED"],
    "secret": "seu-segredo-compartilhado"
  }
}

❗️

Erros de validação (CPF inválido, data fora do formato, nome inválido, etc.) retornam 422.

6. journeyType

O journeyType define o que o usuário fará na jornada:

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.

7. returnUrl

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 .

8. 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"
  }
}

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.

Payload entregue (corpo POST)

{
  "event": "JOURNEY_FINISHED",
  "token": "be78d31f-31be-4903-a340-33589787c66",
  "timestamp": "2026-05-18T01:25:00-03:00"
}

Headers da entrega

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:

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:

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

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

❗️

Requer o JWT Bearer do login (seção 3).

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

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.

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

Campos de cada item de results

Valores de cause

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

geolocation

serpro (condicional)

Presente quando a Classe de Risco está habilitada para a sua conta.

12. documentBiometry (jornada com 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.

"documentBiometry": {
  "protocol": "987654321",
  "ocr": { "...": "campos do documento - ver tipos abaixo" },
  "faceMatch": {
    "code": "0",
    "cause": "MATCH",
    "score": "0.97"
  },
  "documents": [
    { "description": "Frente", "side": "FRONT", "image": "<base64>" },
    { "description": "Verso",  "side": "BACK",  "image": "<base64>" }
  ]
}

Campos de ocr por tipo de documento

O OCR retorna apenas campos textuais; as imagens do documento são entregues no campo documents, não dentro de ocr. Campos sem valor são omitidos. Datas vêm tanto no formato original (dd/MM/yyyy) quanto normalizado (*Formatada, yyyy-MM-dd).

RG

CNH

DNI

CIN

13. 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"
}

14. Glossário