GET /v1/verify/:id

Obtem o estado atual de uma verificacao. Este e o endpoint que voce faz polling apos /submit para conseguir o veredicto.

GET https://api.xxuxe.online/v1/verify/vf_AG07CDWRRFQV4T05ZXG2

Autenticacao

Bearer token. Use uma secret key aqui, nao uma publishable. A publishable key esta intencionalmente limitada a /init e /submit de origens whitelisted — obter veredictos do browser permitiria a qualquer um enumerar dados de outros tenants.

Authorization: Bearer qv_sec_SUA_SECRET_KEY

Path parameter

Parametro	Tipo	Descricao
:id	string	O verificationId retornado por /init (ex: vf_AG07CDWRRFQV4T05ZXG2)

Request de exemplo

curl

curl -X GET https://api.xxuxe.online/v1/verify/vf_AG07CDWRRFQV4T05ZXG2 \
  -H "Authorization: Bearer qv_sec_SUA_SECRET_KEY"

JavaScript / Node.js

const response = await fetch(
  `https://api.xxuxe.online/v1/verify/${verificationId}`,
  {
    headers: {
      'Authorization': `Bearer ${process.env.VERIDIA_SECRET_KEY}`,
    },
  }
);
const data = await response.json();
console.log(data.status, data.verdict);

Python

import os
import requests

response = requests.get(
    f"https://api.xxuxe.online/v1/verify/{verification_id}",
    headers={"Authorization": f"Bearer {os.environ['VERIDIA_SECRET_KEY']}"},
)
response.raise_for_status()
data = response.json()
print(data["status"], data.get("verdict"))

PHP

<?php
$ch = curl_init("https://api.xxuxe.online/v1/verify/$verificationId");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer " . $_ENV['VERIDIA_SECRET_KEY'],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $data['status'] . " " . ($data['verdict'] ?? '');

Resposta

200 OK

Enquanto processa:

{
  "verificationId": "vf_AG07CDWRRFQV4T05ZXG2",
  "status": "processing",
  "submittedAt": "2026-05-01T18:39:05Z"
}

Quando completo:

{
  "verificationId": "vf_AG07CDWRRFQV4T05ZXG2",
  "status": "completed",
  "verdict": "approved",
  "confidence": 87.4,
  "scores": {
    "ocrConfidence": 78.0,
    "faceMatch": 96.2,
    "liveness": 91.5,
    "docQuality": 85.0
  },
  "flags": [],
  "submittedAt": "2026-05-01T18:39:05Z",
  "completedAt": "2026-05-01T18:39:08Z"
}

Quando o usuario precisa revisao manual:

{
  "verificationId": "vf_AG07CDWRRFQV4T05ZXG2",
  "status": "completed",
  "verdict": "review",
  "confidence": 64.5,
  "scores": {
    "ocrConfidence": 88.0,
    "faceMatch": 71.2,
    "liveness": 88.0,
    "docQuality": 75.0
  },
  "flags": [
    { "level": "warn", "text": "low_face_match" },
    { "level": "info", "text": "heavy_glare" }
  ],
  "submittedAt": "2026-05-01T18:39:05Z",
  "completedAt": "2026-05-01T18:39:08Z"
}

Campos de resposta

Campo	Tipo	Sempre presente	Descricao
verificationId	string	Sim	O verification ID
status	string	Sim	queued, processing, completed, ou failed
verdict	string	Apenas quando completed	approved, review, ou rejected
confidence	number	Apenas quando completed	Score geral ponderado de confianca (0-100)
scores	object	Apenas quando completed	Breakdown de sinais individuais
scores.ocrConfidence	number	Quando OCR rodou	Confianca VLM auto-reportada na extracao de texto (0-100)
scores.faceMatch	number	Sempre	Similaridade biometrica entre selfie e foto do documento (0-100)
scores.liveness	number	Sempre	Score anti-spoofing — confirma que e uma pessoa viva (0-100)
scores.docQuality	number	Sempre	Score de qualidade da imagem do documento (0-100)
flags	array	Sim	Flags de qualidade / risco. Vazio [] quando esta limpo
flags[].level	string	Sim	info, warn, ou critical
flags[].text	string	Sim	Codigo machine-readable do flag (ex: heavy_glare, low_face_match)
submittedAt	string	Sim	Timestamp ISO 8601 quando /submit foi chamado
completedAt	string	Apenas quando completed ou failed	Timestamp ISO 8601 quando o veredicto foi determinado

Maquina de estados

Uma verificacao se move atraves destes estados:

queued -> processing -> completed
                     -> failed

Status	O que significa	Proximo
queued	O job esta esperando na fila do backend ML	Vai mover para processing em segundos
processing	O pipeline esta rodando ativamente	Vai mover para completed ou failed
completed	O veredicto esta pronto	Estado terminal — sem mais mudancas
failed	O pipeline nao pode completar (raro)	Estado terminal — veja flags para causa

Veredictos explicados

Veredicto	O que significa	O que voce deve fazer
approved	Alta confianca, todos os sinais passam	Confiar no usuario, completar onboarding
review	Sinais mistos, revisao manual recomendada	Enviar a sua fila de revisao
rejected	Baixa confianca ou flag critico	Bloquear, pedir ao usuario para tentar de novo, ou escalar

O threshold entre veredictos e configuravel por tenant (defaults: <60 rejected, 60-80 review, >=80 approved).

Flags comuns

Flag	Nivel	Significado
heavy_glare	warn	O documento tem reflexo brilhoso obscurecendo o texto
low_face_match	warn	A selfie e a foto do documento parecem diferentes
low_liveness	warn	Score anti-spoofing abaixo do threshold
low_doc_quality	warn	Imagem do documento muito borrada ou de baixa resolucao
expired_document	critical	A data de expiracao do documento ja passou
mrz_mismatch	critical	O checksum MRZ falhou (passaporte potencialmente alterado)
name_mismatch	warn	O nome enviado nao faz fuzzy-match com o OCR
age_under_minimum	critical	Idade calculada abaixo do minimo do tenant (default 18)

Padrao de polling

Para polling, use um loop de retry limitado com backoff:

async function waitForVerdict(verificationId, timeoutMs = 30000) {
  const start = Date.now();
  let interval = 500;  // comeca em 500ms

  while (Date.now() - start < timeoutMs) {
    const response = await fetch(
      `https://api.xxuxe.online/v1/verify/${verificationId}`,
      {
        headers: { 'Authorization': `Bearer ${process.env.VERIDIA_SECRET_KEY}` },
      }
    );
    const data = await response.json();

    if (data.status === 'completed' || data.status === 'failed') {
      return data;
    }

    await new Promise(r => setTimeout(r, interval));
    interval = Math.min(interval * 1.5, 3000);  // backoff exponencial, cap 3s
  }

  throw new Error('A verificacao expirou');
}

Melhor que polling: use webhooks. Disparam assim que o veredicto esta pronto — sem polling, sem eventos perdidos.

Erros

HTTP	Error code	Quando
404	verification_not_found	O ID nao existe, ou pertence a outro tenant
401	unauthorized / invalid_key	Issue de auth. Veja Autenticacao
429	rate_limited	Atingiu o rate limit de /verify/:id (600 req/min por padrao)
500	internal	Issue do backend. Inclua o requestId no seu ticket de suporte

Catalogo completo: Erros.

Notas

• A propriedade do tenant e enforced — voce so pode obter verificacoes criadas com suas proprias API keys
• O endpoint e seguro para fazer polling ate 600 vezes por minuto por padrao. Precisa mais? Contate o suporte
• Uma vez que uma verificacao esta completed ou failed, a resposta e imutavel — voce pode cachear indefinidamente
• submittedAt e completedAt sao ISO 8601 em UTC

Proximos passos

• Erros — referencia completa de codigos de erro
• Webhooks — receba veredictos via push em vez de polling
• Compliance — retencao de dados e detalhes regulatorios