Ir para o conteúdo principal
ShieldID

Início rápido

O guia de início rápido da verificação de identidade.

Da chave sandbox ao primeiro webhook assinado, em ordem. Cada etapa tem um exemplo funcional — copie, troque pela sua chave e pelas suas URLs, e execute.

Solicitar uma chave sandboxReferência completa da API

Passo a passo

Sete passos, uma tarde.

  1. Obtenha uma chave sandbox

    As chaves sandbox (prefixo vk_sand_) são emitidas sob solicitação enquanto o cadastro self-service está sendo construído. Peça pelo formulário de contato — a maioria dos pedidos é atendida no mesmo dia útil. As sessões sandbox nunca são cobradas, então não há motivo para esperar para começar.

  2. Crie sua primeira sessão

    Uma única chamada. Envie uma return_url (para onde o solicitante vai ao terminar) e uma webhook_url (para onde o resultado assinado é enviado). Você recebe de volta um session_id e uma verification_url.

    bash
    curl -X POST https://api.shieldid.ca/v1/sessions \
  -H "X-Api-Key: vk_sand_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "return_url": "https://yourapp.example/verified",
    "webhook_url": "https://yourapp.example/hooks/shieldid",
    "expected_name": "Jordan Smith",
    "locale": "en",
    "metadata": { "application_id": "app_9182" }
  }'

  3. Entregue o link ao solicitante

    Abra a verification_url e você verá a página hospedada. Em um navegador de desktop, ela mostra um QR code — ao escaneá-lo, o mesmo link é enviado para um celular, onde acontecem a foto do documento, o desafio de prova de vida e a selfie. Experimente agora mesmo no seu próprio celular.

  4. Configure um endpoint de webhook

    Aponte a webhook_url para uma rota que aceite um POST, leia o corpo bruto da requisição (você precisa dele sem processamento para conferir a assinatura) e retorne um status 2xx. Em qualquer outro caso, o ShieldID tenta a entrega novamente até três vezes.

    javascript
    import express from "express";
const app = express();

app.post("/hooks/shieldid", express.raw({ type: "application/json" }), (req, res) => {
  // Verify the signature before you trust this body — see the next step.
  console.log("Received a webhook:", req.body.toString());
  res.status(200).send("ok");
});

app.listen(3000);

  5. Verifique a assinatura

    Não tome nenhuma ação com base no corpo de um webhook até confirmar que ele realmente vem do ShieldID. Calcule um HMAC-SHA256 sobre o corpo bruto com o seu segredo de webhook e compare com o cabeçalho X-Bio-Signature.

    javascript
    import crypto from "node:crypto";

function isValidShieldIdSignature(rawBody, signatureHeader, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const provided = signatureHeader || "";
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(provided, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// rawBody must be the exact, unparsed request body
app.post("/hooks/shieldid", express.raw({ type: "application/json" }), (req, res) => {
  const ok = isValidShieldIdSignature(req.body, req.headers["x-bio-signature"], process.env.SHIELDID_WEBHOOK_SECRET);
  if (!ok) return res.status(401).send("invalid signature");

  const result = JSON.parse(req.body);
  // result.session_id, result.status, result.checks, …
  res.status(200).send("ok");
});

  6. Leia o resultado

    O payload do webhook já contém tudo de que você precisa. Se preferir buscar o resultado por conta própria — após um redirecionamento, por exemplo — chame diretamente o endpoint de resultado.

    bash
    curl https://api.shieldid.ca/v1/sessions/ses_9f2c1a/result \
  -H "X-Api-Key: vk_sand_your_key"

# → { "session_id": "ses_9f2c1a", "status": "VERIFIED", "checks": { "document": "PASS", … }, … }

  7. Trate FAILED e uma nova tentativa

    Uma sessão que chega a FAILED traz um failure_reason. Mostre ao solicitante algo útil. Em breve: repetir uma sessão FAILED para redefini-la para PENDING. Por enquanto, trate FAILED como estado final e crie uma nova sessão se o solicitante quiser tentar de novo.

Antes de virar a chave

Vá para produção.

O formato da requisição não muda entre sandbox e produção — apenas a chave. Confirme estes pontos antes de enviar um solicitante real para uma sessão vk_live_.

  • Troque vk_sand_ por uma chave vk_live_. Nada mais na requisição muda.
  • Aponte a webhook_url para um endpoint real, sempre ativo, que verifique a assinatura — não um request-bin nem um notebook.
  • Trate os três estados finais no seu app: VERIFIED, FAILED e EXPIRED, e não apenas o caminho feliz.
  • Confirme que a sua return_url lê os parâmetros de consulta session_id e status que o ShieldID anexa no redirecionamento.
  • Consulte os preços atuais com GET /v1/pricing/{country} ou na página de preços, para que as cobranças em produção não sejam uma surpresa.
  • Mantenha as chaves de sandbox longe de qualquer coisa que um solicitante real possa acessar — uma sessão de sandbox é gratuita porque não é real.

Perguntas

Perguntas frequentes sobre o início rápido.

Comece agora

Execute o primeiro passo agora mesmo.

Solicite uma chave sandbox, cole o primeiro comando cURL em um terminal e você já estará à frente da maioria das integrações.

Solicitar uma chave sandboxReferência completa da API