API de verificação de idade

Estima se a pessoa tem idade suficiente a partir de uma selfie, com recurso à data de nascimento de um documento de identidade quando a estimativa estiver muito próxima do limite.

POST /api/v1/kyc/age-estimation estima a idade aparente do rosto em uma selfie e a compara com uma idade mínima. É a mesma verificação da opção Verificação de idade nos formulários (veja Verificação de idade), disponível também de forma isolada.

O resultado é uma estimativa a partir de uma foto, não uma prova de idade. Toda resposta informa isso (isEstimate, disclaimer). Próximo ao seu limite, a resposta é inconclusive por definição: recorra a uma verificação por documento de identidade.

Autentique-se com uma chave de API (Authorization: Bearer ck_live_…) com o escopo kyc:write. Consulte Autenticação. A foto é processada na memória e nunca é armazenada.

Requisição

Envie multipart/form-data ou JSON.

curl -X POST https://app.certivant.com/api/v1/kyc/age-estimation \
  -H "Authorization: Bearer $CERTIVANT_API_KEY" \
  -H "Idempotency-Key: signup-8841" \
  -F image=@selfie.jpg \
  -F minAge=18 \
  -F buffer=5

{
  "imageBase64": "/9j/4AAQSkZJRg…",
  "minAge": 18,
  "buffer": 5,
  "dateOfBirth": "1990-02-03"
}

Campo	Tipo	Observações
`image` / `imageBase64`	arquivo / string	Uma selfie frontal com um único rosto. JPEG, PNG, WebP ou HEIC, até 10 MB. Uma URL `data:` é aceita
`minAge`	inteiro 1–120, opcional	O padrão é a configuração da sua organização (Configurações → Prevenção de fraude), inicialmente 18
`buffer`	inteiro 0–30, opcional	Anos para cima e para baixo de `minAge` dentro dos quais a estimativa não é considerada confiável. O padrão é a configuração da sua organização, inicialmente 5
`dateOfBirth`	`YYYY-MM-DD`, opcional	A data de nascimento de um documento de identidade que você já verificou. Usada quando a estimativa não é conclusiva

Envie um cabeçalho Idempotency-Key para tornar uma nova tentativa sem custo: a mesma chave é cobrada apenas uma vez.

Resposta

{
  "data": {
    "result": "pass",
    "method": "estimate",
    "minAge": 18,
    "buffer": 5,
    "isEstimate": true,
    "estimatedAge": 31.4,
    "estimateSpread": 3.2,
    "estimateConfidence": "high",
    "disclaimer": "An estimate from a photo, not proof of age.",
    "chargedCents": 7
  }
}

Campo	Observações
`result`	`pass`, `fail` ou `inconclusive`
`method`	`estimate` — a selfie decidiu; `id_document` — `dateOfBirth` decidiu; `none` — nada pôde decidir
`isEstimate`	Verdadeiro quando a estimativa pela selfie faz parte da resposta
`estimatedAge`, `estimateSpread`, `estimateConfidence`	A estimativa em anos, o grau de incerteza e `high` ou `low`. Presentes quando uma estimativa foi feita
`idAge`	Idade em anos completos a partir de `dateOfBirth`, quando foi usada
`fallbackReason`	Motivo pelo qual o documento de identidade foi necessário: `near_limit`, `low_confidence`, `no_estimate` ou `estimate_mismatch`
`mismatch`	Uma estimativa confiável e o documento de identidade discordam. Trate como um caso para revisão manual
`idCheckRequired`	Verdadeiro quando o resultado é `inconclusive` e você não enviou `dateOfBirth`: faça uma verificação de documento de identidade e chame novamente com a data de nascimento, ou encaminhe a pessoa para uma verificação
`disclaimer`	Sempre presente. Exiba-o sempre que mostrar a estimativa
`chargedCents`	Quanto esta chamada custou

Como a decisão é tomada

Estimativa igual ou superior a minAge + buffer → pass.
Estimativa abaixo de minAge − buffer → fail.
Entre esses valores, ou quando o modelo não tem certeza da estimativa → a dateOfBirth decide, caso você tenha enviado uma. Sem ela, o resultado é inconclusive.
Quando você envia uma dateOfBirth que contradiz claramente a estimativa, mismatch é true: uma estimativa muito acima do limite com uma data de nascimento que indica idade abaixo do mínimo resulta em fail (a data de nascimento prevalece); uma estimativa muito abaixo do limite com uma data de nascimento de adulto resulta em inconclusive, para que uma pessoa analise.

Erros

Status	Quando
`400`	Imagem, `minAge`, `buffer` ou `dateOfBirth` ausente ou inválido
`402`	Crédito insuficiente para executar a verificação
`403`	A estimativa de idade não está incluída no seu plano
`413`	Imagem maior que 10 MB
`415`	Tipo de imagem não suportado
`422`	Nenhum rosto utilizável foi encontrado (e nenhuma `dateOfBirth` para usar como alternativa)
`502`	O serviço de estimativa está indisponível. Tente novamente com a mesma `Idempotency-Key`

Quando nenhum rosto é encontrado, mas você enviou uma dateOfBirth, a chamada ainda responde a partir do documento de identidade (method: "id_document").

Faturamento

A estimativa de idade é um recurso do plano, com uma cota mensal incluída e um preço de pagamento por uso por verificação, debitado do seu saldo de créditos. Uma chamada que retorna 402 ou 403 não é cobrada. Cada verificação é registrada no seu registro de auditoria (age_estimation.checked) com o resultado e o método, nunca a foto nem a data de nascimento.

Em uma verificação

Quando um formulário tem a verificação de idade ativada, a própria verificação traz o resultado: seus gatilhos de revisão ou critérios de desqualificação podem conter age_requirement_not_met ou age_check_inconclusive, e políticas e fluxos de trabalho podem testar age.checked, age.result, age.method, age.estimatedAge, age.minimum, age.meetsMinimum e age.mismatch.