Gerenciando resultados

Apos uma verificacao rodar, voce tem tres formas de receber o veredicto. Cada uma se encaixa numa arquitetura diferente.

Comparacao rapida

Metodo	Quando usar	Latencia	Confiabilidade
Eventos do widget	SPAs, feedback UX imediato	`<100ms`	Boa
Polling	Fluxos server-side, sem URL publica de webhook	2-5s tipico	Boa
Webhooks	B2B em producao, processamento async	1-3s tipico	Melhor

Para a maioria dos sistemas em producao, webhooks sao a opcao recomendada. Polling esta bom para prototipos.

O widget emite um evento veridia:complete no browser assim que a API aceita a verificacao. Caminho mais simples para SPAs.

O que voce recebe

{
  "verificationId": "vf_AG07CDWRRFQV4T05ZXG2",
  "userRef": "customer-12345",
  "status": "queued"   // ou "processing" ou "completed"
}

O status e o estado inicial. O veredicto ainda nao esta aqui — voce precisa fazer fetch.

Padrao

<veridia-widget id="kyc" publishable-key="qv_pub_..."></veridia-widget>

<script>
  document.getElementById('kyc').addEventListener('veridia:complete', async (e) => {
    const { verificationId } = e.detail;

    // Enviar ao seu proprio backend, que chama GET /v1/verify/:id com a SECRET key
    const response = await fetch('/api/kyc-completed', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ verificationId }),
    });

    const result = await response.json();
    console.log('Veredicto:', result.verdict);  // approved / review / rejected
  });
</script>

:::warning Nunca chame /v1/verify/:id do browser A publishable key do browser (qv_pub_*) e intencionalmente limitada. Para obter veredictos, use uma request server-side com sua secret key (qv_sec_*). Caso contrario, qualquer um poderia consultar qualquer verificacao. :::

Metodo 2 — Polling GET /v1/verify/:id

Se seu backend recebeu o verificationId (do evento ou via form submission), faca polling no endpoint de status ate que seja completed.

curl

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

Resposta quando pronto:

{
  "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"
}

JavaScript / Node.js

async function pollVerification(verificationId, maxAttempts = 30) {
  for (let i = 0; i < maxAttempts; i++) {
    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, 1000));  // espera 1s
  }
  throw new Error('A verificacao nao completou a tempo');
}

const result = await pollVerification('vf_AG07CDWRRFQV4T05ZXG2');
console.log('Veredicto:', result.verdict);

Python

import os
import time
import requests

def poll_verification(verification_id, max_attempts=30):
    headers = {"Authorization": f"Bearer {os.environ['VERIDIA_SECRET_KEY']}"}

    for _ in range(max_attempts):
        r = requests.get(
            f"https://api.xxuxe.online/v1/verify/{verification_id}",
            headers=headers,
            timeout=10,
        )
        r.raise_for_status()
        data = r.json()

        if data["status"] in ("completed", "failed"):
            return data

        time.sleep(1)

    raise TimeoutError("A verificacao nao completou a tempo")

result = poll_verification("vf_AG07CDWRRFQV4T05ZXG2")
print("Veredicto:", result["verdict"])

PHP

<?php
function pollVerification(string $verificationId, int $maxAttempts = 30): array {
    $secretKey = $_ENV['VERIDIA_SECRET_KEY'];

    for ($i = 0; $i < $maxAttempts; $i++) {
        $ch = curl_init("https://api.xxuxe.online/v1/verify/$verificationId");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            "Authorization: Bearer $secretKey",
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        $data = json_decode($response, true);

        if (in_array($data['status'], ['completed', 'failed'], true)) {
            return $data;
        }

        sleep(1);
    }

    throw new RuntimeException("A verificacao nao completou a tempo");
}

$result = pollVerification("vf_AG07CDWRRFQV4T05ZXG2");
echo "Veredicto: " . $result['verdict'] . "\n";

Metodo 3 — Webhooks (recomendado para producao)

Webhooks sao push: quando uma verificacao completa, Veridia envia um POST HTTP assinado ao seu endpoint. Sem polling, sem eventos perdidos, audit trail completo.

Setup

No seu dashboard, va a Webhooks
Configure a webhook URL ao seu endpoint (ex: https://seuapp.com/webhooks/veridia)
Copie o webhook secret — voce vai precisar para verificar assinaturas
Pronto. Cada verificacao completa dispara um POST.

O que voce recebe

{
  "event": "verification.review_required",
  "verificationId": "vf_AG07CDWRRFQV4T05ZXG2",
  "tenantId": "tn_default_demo",
  "userRef": "customer-12345",
  "verdict": "review",
  "confidence": 77.85,
  "scores": {
    "faceMatch": 99.5,
    "liveness": 88.0,
    "ocrConfidence": 20.0,
    "docQuality": 75.7
  },
  "flags": [
    { "level": "warn", "text": "heavy_glare" }
  ],
  "completedAt": "2026-05-01T18:39:08Z"
}

O campo event vai ser um de:

verification.approved
verification.rejected
verification.review_required

A request HTTP inclui um header de assinatura que voce deve verificar (veja verificacao de assinatura para o algoritmo exato).

Por que preferir webhooks

Aspecto	Polling	Webhooks
Latencia	Polling 1s = 1s delay medio	`<100ms` apos completion
API calls	Muitas	So a entrega
Confiabilidade	Seu codigo precisa rodar	Veridia tenta 5 vezes com backoff exponencial
Audit trail	Nenhum	Log completo de delivery no dashboard
Cold starts	Acorda serverless em cada poll	Dispara uma vez

Agindo sobre o veredicto

Qualquer que seja o metodo que voce use, a acao e a mesma:

function onVerdict(result) {
  switch (result.verdict) {
    case 'approved':
      // Marcar usuario como KYC, habilitar acesso completo
      enableUserAccount(result.userRef);
      break;

    case 'review':
      // Enviar para fila de revisao manual, pausar acoes sensiveis
      queueForReview(result.verificationId, result.flags);
      break;

    case 'rejected':
      // Bloquear, pedir ao usuario que tente de novo ou contate suporte
      blockUserKyc(result.userRef, result.flags);
      break;

    default:
      // Nunca deveria acontecer, logar
      console.error('Veredicto desconhecido:', result.verdict);
  }
}

Proximos passos

Quickstart completo. A partir daqui, dependendo do que voce esta construindo:

Documentacao do Widget — cada atributo, evento e opcao de estilo
Referencia API — REST API completa para integracoes server-side
Webhooks — verificacao de assinatura, retry behavior, exemplos
Compliance — retencao de dados, SEPRELAD, LGPD, GDPR

Precisa de ajuda? Contatar suporte.

Comparacao rapida​

Metodo 1 — Eventos do widget​

O que voce recebe​

Padrao​

Metodo 2 — Polling GET /v1/verify/:id​

curl​

JavaScript / Node.js​

Python​

PHP​

Metodo 3 — Webhooks (recomendado para producao)​

Setup​

O que voce recebe​

Por que preferir webhooks​

Agindo sobre o veredicto​

Proximos passos​

Comparacao rapida

Metodo 1 — Eventos do widget

O que voce recebe

Padrao

Metodo 2 — Polling GET /v1/verify/:id

curl

JavaScript / Node.js

Python

PHP

Metodo 3 — Webhooks (recomendado para producao)

Setup

O que voce recebe

Por que preferir webhooks

Agindo sobre o veredicto

Proximos passos