Referência da API

Riv.IA EYE API

Verificação visual de identidade via API REST: prova de vida, comparação facial, anti-spoof e detecção de elementos — tudo em uma única chamada autenticada por Bearer Token.

v1Bearer Auth
Produçãohttps://api.riv.ia.br
Devhttps://dev.riv.ia.br

Como usar a API

Todos os endpoints exigem um Bearer Token. Gere o token primeiro e inclua-o no header de cada requisição.

  1. 1

    Gerar token

    Autentique com client_id e client_secret para receber o Bearer Token.

  2. 2

    Enviar selfie

    Faça POST em /eye/v1/verify com a selfie e os checks desejados.

  3. 3

    Receber veredito

    Resposta JSON explicável com o veredito agregado approved.

Precisa de credenciais?
Para obter seu client_id e client_secret, entre em contato pelo email contato@riviadev.com.br.

Autenticação

Use suas credenciais para gerar um Bearer Token de curta duração. Inclua-o no header Authorization: Bearer <token> em todas as chamadas subsequentes.

Troca suas credenciais por um Bearer Token de acesso.

Body (application/json)

client_idstringobrigatório
Identificador do cliente fornecido pela RiviDev.
client_secretstringobrigatório
Segredo do cliente. Mantenha-o seguro — nunca exponha em código client-side.

Exemplo de requisição

request.sh
curl -X POST https://api.riv.ia.br/auth/v1/tokens/generate \
  -H "Content-Type: application/json" \
  -d '{"client_id":"SEU_CLIENT_ID","client_secret":"SEU_CLIENT_SECRET"}'

Resposta — 200 OK

response.json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Riv.IA EYE

Ponto de entrada único para verificação visual. Combine os checks que precisar — o veredito approved é a conjunção de todos os checks solicitados.

Executa, em uma única chamada, qualquer combinação de liveness, face_match, authenticity e element_detection sobre a mesma selfie (e documento, quando aplicável).

Headers

Authorizationstringobrigatório
Bearer Token obtido em /auth/v1/tokens/generate. Formato: Bearer <token>.

Body (multipart/form-data)

selfiefileobrigatório
Selfie da pessoa a verificar. Formatos: JPG, PNG, GIF, BMP, WEBP, DNG (máx. 10MB). Alvo de liveness, authenticity e element_detection.
checksstringobrigatório
Lista de checks a executar, separados por vírgula. Valores aceitos: liveness, face_match, authenticity, element_detection.
documentfile
Imagem do documento (RG, CNH, passaporte). Obrigatório quando o check face_match é solicitado.
detection_requeststring (JSON)
JSON com a lista de elementos a detectar. Obrigatório quando o check element_detection é solicitado. Ex.: {"elements":[{"type":"object","description":"crachá","required":true}]}.

Exemplos de requisição

Escolha um cenário para ver o cURL correspondente. Use https://api.riv.ia.br (produção) ou https://dev.riv.ia.br (dev).

Prova de vida — só a selfie
Verifica se a imagem é uma selfie real de um ser humano vivo.
Requisição
liveness.sh
curl -X POST https://api.riv.ia.br/eye/v1/verify \
  -H "Authorization: Bearer $RIVIA_KEY" \
  -F "selfie=@selfie.jpg" \
  -F "checks=liveness"
Resposta — 200 OK
response.json
{
  "success": true,
  "approved": true,
  "checks": ["liveness"],
  "liveness": {
    "resultado": true,
    "person_present": true,
    "confidence": 0.93,
    "detalhes": []
  },
  "message": "Verificação aprovada."
}

Apenas os checks solicitados em checks retornam um objeto preenchido — os demais campos vêm como null ou são omitidos.

Campos da resposta

successboolean
Indica se a chamada foi processada com sucesso.
approvedboolean
Veredito agregado: true quando todos os checks solicitados passaram.
checksstring[]
Lista dos checks efetivamente executados, na ordem.
livenessobject | null
Resultado do check de prova de vida (presente apenas se solicitado).
face_matchobject | null
Resultado da comparação facial selfie × documento (presente apenas se solicitado).
authenticityobject | null
Resultado do check de autenticidade / anti-spoof (presente apenas se solicitado).
element_detectionobject | null
Resultado da detecção de elementos na selfie (presente apenas se solicitado).
messagestring | null
Mensagem complementar legível sobre o resultado.

Códigos de status

200OK
Verificação processada com sucesso.
400Bad Request
Parâmetros inválidos ou arquivos não aceitos.
401Unauthorized
Bearer Token ausente, inválido ou expirado.
422Validation Error
Payload válido sintaticamente, mas semanticamente incorreto (ex.: face_match sem document).
500Internal Server Error
Falha interna. Tente novamente; persistindo, contate o suporte.

Notas de comportamento

  • checks é uma lista (CSV) do que você quer executar. Apenas os checks pedidos vêm preenchidos; o restante volta como null.
  • approved é o AND lógico dos checks solicitados (resultado ∧ same_person ∧ is_authentic ∧ all_required_found).
  • document é obrigatório apenas com face_match; detection_request é obrigatório apenas com element_detection. Caso contrário a API retorna 422.
  • Os checks rodam em paralelo. Pedir liveness + authenticity juntos consome uma única inferência (short-circuit).
  • Formatos de imagem aceitos: JPG, PNG, GIF, BMP, WEBP, DNG (máx. 10MB cada).

Pronto para integrar?

Fale com nosso time para receber credenciais de sandbox e iniciar sua integração com o Riv.IA EYE.

Solicitar credenciais →