Primeira verificação em 10 minutos

1. Obtenha uma chave de teste

Crie a conta e, no console, abra Chaves de API. Gere uma chave de ambiente de teste (prefixo vf_test_). A chave aparece uma única vez: guarde em lugar seguro. No banco fica só o hash e o prefixo.

2. Crie a verificação

Um POST em /verifications abre a sessão. O único campo obrigatório é a jornada (leve, padrao ou rigorosa). O Idempotency-Key evita sessão duplicada em caso de repetição.

curl -X POST https://api.provalidface.com.br/api/v1/verifications \
  -H "Authorization: Bearer vf_test_sua_chave_de_teste" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1042" \
  -d '{
    "journey": "padrao",
    "external_reference": "pedido-1042",
    "callback_url": "https://api.suaempresa.com.br/webhooks/validface",
    "subject_cpf": "390.533.447-05"
  }'

Campos do corpo: journey (obrigatório), external_reference (o seu identificador, opcional), callback_url (opcional) e subject_cpf (opcional; a jornada sem leitura de documento usa esse CPF na etapa de CPF). O CPF pode vir com ou sem máscara.

A resposta é 201 com a sessão recém-criada, ainda em pending:

{
  "id": "3f1c8e0a-9d4b-4c2e-8a10-2b7c5e9f0a11",
  "journey": "padrao",
  "external_reference": "pedido-1042",
  "status": "pending",
  "score": null,
  "reasons": [],
  "session_url": "https://verify.provalidface.com.br/s/AbC123.../",
  "session_token": "AbC123...",
  "expires_at": "2026-09-30T12:30:00Z",
  "callback_url": "https://api.suaempresa.com.br/webhooks/validface",
  "steps": [],
  "created_at": "2026-09-30T12:00:00Z",
  "decided_at": null
}

3. Abra o link do titular

Envie o session_url para a pessoa concluir no celular: ela aceita o consentimento e envia o documento e a selfie. A sessão expira sozinha em expires_at se ninguém concluir. No sandbox, o conteúdo do arquivo enviado decide o resultado (veja os marcadores do sandbox).

4. Consulte o resultado

Enquanto integra, consulte a sessão pelo id. Em produção, prefira o webhook a ficar consultando em laço.

curl https://api.provalidface.com.br/api/v1/verifications/3f1c8e0a-9d4b-4c2e-8a10-2b7c5e9f0a11 \
  -H "Authorization: Bearer vf_test_sua_chave_de_teste"

Quando a decisão sai, o corpo traz o status, o score e os motivos:

{
  "id": "3f1c8e0a-9d4b-4c2e-8a10-2b7c5e9f0a11",
  "journey": "padrao",
  "external_reference": "pedido-1042",
  "status": "approved",
  "score": 95,
  "reasons": [{"code": "APPROVED", "message": "Verificacao aprovada."}],
  "session_url": "https://verify.provalidface.com.br/s/AbC123.../",
  "session_token": "AbC123...",
  "expires_at": "2026-09-30T12:30:00Z",
  "callback_url": "https://api.suaempresa.com.br/webhooks/validface",
  "steps": [
    {"step": "face_match", "engine": "mock", "engine_version": "1.0.0", "ok": true, "score": 95.0, "cost": "0.1500"}
  ],
  "created_at": "2026-09-30T12:00:00Z",
  "decided_at": "2026-09-30T12:00:07Z"
}

5. Leia o status e os motivos

O status assume pending, processing, approved, rejected, review ou expired. O score de 0 a 100 é o do face match, onde a decisão de fato acontece. Cada item de reasons tem um code estável, como APPROVED, FACE_MATCH_BELOW_THRESHOLD, CPF_IRREGULAR ou LIVENESS_FAILED. Trate pelo código; a mensagem é só para leitura.

Quando o score fica intermediário ou um motor falha, a sessão vai para review em vez de ser reprovada: o seu time decide na fila de revisão do console.