Sobre esta API
Compara o rosto do documento com uma selfie e responde se são a mesma pessoa, com a distância medida e o limiar usado.
Envie doc_photo e selfie — foto, HEIC ou PDF, inclusive a CNH digital. Com crop_rg e crop_selfie, os rostos também são recortados antes de comparar.
Processado em motor próprio, sem envio da imagem a terceiros. Não faz prova de vida.
Motor próprio · Atualização: tempo real
Requisição
POST /api/v1/oracle/face/verifyAutenticação HTTP Basic: public_key:secret_key em Base64. Guarde a chave secreta no servidor.
| Cabeçalho | Descrição |
|---|---|
AuthorizationObrigatório | Chave de API em Basic: public_key:secret_key em Base64. |
X-Project-IdOpcional | Projeto que recebe a chamada. Sem ele, vale o projeto padrão da conta. |
Idempotency-KeyOpcional | Repetir a mesma chave em até 24 horas devolve a resposta anterior, sem executar nem cobrar de novo. |
Parâmetros
| Campo | Tipo e local | Descrição |
|---|---|---|
doc_photoObrigatório | filefile | Foto ou PDF do documento (CNH, RG, CNH digital). |
selfieObrigatório | filefile | Selfie da pessoa. |
crop_rgOpcional | booleanquery | Recorta o rosto do documento antes de comparar. Exemplo: |
crop_selfieOpcional | booleanquery | Recorta o rosto da selfie antes de comparar. Exemplo: |
curl --request POST 'https://api.apifordevs.com/api/v1/oracle/face/verify?crop_rg=false&crop_selfie=false' \
--user "afd_live_pk_...:$AFD_SECRET_KEY" \
--header "X-Project-Id: $AFD_PROJECT_ID" \
--form 'doc_photo=@./doc_photo.jpg' \
--form 'selfie=@./selfie.jpg'
import os
import requests
doc_photo = open("./doc_photo.jpg", "rb")
selfie = open("./selfie.jpg", "rb")
response = requests.request(
"POST",
"https://api.apifordevs.com/api/v1/oracle/face/verify?crop_rg=false&crop_selfie=false",
auth=("afd_live_pk_...", os.environ["AFD_SECRET_KEY"]),
headers={"X-Project-Id": os.environ["AFD_PROJECT_ID"]},
files={"doc_photo": doc_photo, "selfie": selfie},
timeout=30,
)
response.raise_for_status()
print(response.json())
doc_photo.close()
selfie.close()
import { readFile } from "node:fs/promises";
const form = new FormData();
form.append("doc_photo", new Blob([await readFile("./doc_photo.jpg")]), "doc_photo.jpg");
form.append("selfie", new Blob([await readFile("./selfie.jpg")]), "selfie.jpg");
const response = await fetch("https://api.apifordevs.com/api/v1/oracle/face/verify?crop_rg=false&crop_selfie=false", {
method: "POST",
headers: {
Authorization: "Basic " + Buffer.from(
"afd_live_pk_...:" + process.env.AFD_SECRET_KEY
).toString("base64"),
"X-Project-Id": process.env.AFD_PROJECT_ID,
},
body: form,
signal: AbortSignal.timeout(30000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Campos de resposta
Campos e tipos publicados no catálogo desta API.
- Mesma pessoa
verifiedboolean - Os dois rostos são da mesma pessoa.
- Distância medida
distancenumber - Limiar
thresholdnumber - Limiar usado. Abaixo dele,
verifiedé verdadeiro. - Comparação que decidiu
planstring - Qual comparação decidiu:
original(imagens inteiras) ourecorte(rostos recortados). - Detalhe
detailstring
Exemplo de resposta
{
"success": true,
"code": 200,
"code_message": "A requisição foi processada com sucesso.",
"errors": [],
"header": null,
"data_count": 1,
"data": [
{
"verified": true,
"distance": 0.31,
"threshold": 0.68,
"plan": "original",
"detail": null
}
]
}
Respostas e cobrança
| HTTP | Descrição | Cobrança |
|---|---|---|
200 | Sucesso. | Sujeita à cobrança |
400
| Arquivo ou parâmetro que a rota não consegue processar, projeto inválido, ou dev_mode=true com chave de produção. | Sem cobrança |
401
| Credencial ausente, inválida ou revogada. | Sem cobrança |
402
| Saldo insuficiente ou limite de gasto diário atingido. | Sem cobrança |
403
| E-mail da conta não verificado, chave sem escopo para o serviço, IP fora da allowlist do projeto ou chave de teste sem dev_mode=true. | Sem cobrança |
409
| Requisição com a mesma Idempotency-Key ainda em andamento. | Sem cobrança |
413
| Arquivo acima de 20 MB. | Sem cobrança |
422
| Parâmetro obrigatório ausente ou fora do formato, ou Idempotency-Key repetida com outro conteúdo. | Sem cobrança |
429
| Limite de requisições por minuto da chave atingido. | Sem cobrança |
500
| Falha interna. | Sem cobrança |
503
| Serviço desativado (service_unavailable), ou o processamento não respondeu a tempo (upstream_error). Não é cobrada; com upstream_error, pode ser repetida. | Sem cobrança |
Casos de uso
Onboarding com selfie
Confirmar que quem está abrindo a conta é o titular do documento apresentado.
Reautenticação em operação sensível
Pedir selfie antes de transferência alta ou troca de dispositivo e comparar com o documento já cadastrado.