Vai al contenuto principale
ShieldID

Guida rapida

La guida rapida alla verifica dell'identità.

Dalla chiave sandbox al primo webhook firmato, in ordine. Ogni passaggio ha un esempio funzionante: lo copi, inserisca la Sua chiave e i Suoi URL, ed eseguilo.

Richieda una chiave sandboxRiferimento API completo

Passo dopo passo

Sette passaggi, un pomeriggio.

  1. Ottenere una chiave sandbox

    Le chiavi sandbox (prefisso vk_sand_) vengono rilasciate su richiesta finché la registrazione self-service è in fase di sviluppo. La richieda tramite il modulo di contatto — la maggior parte delle richieste viene evasa entro il giorno lavorativo. Le sessioni sandbox non vengono mai fatturate, quindi non c'è motivo di attendere per iniziare.

  2. Creare la prima sessione

    Una sola chiamata. Invii un return_url (la pagina in cui il richiedente arriva al termine) e un webhook_url (dove viene inviato il risultato firmato). Riceverà un session_id e un 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. Consegnare il link al richiedente

    Apra verification_url e vedrà la pagina ospitata. Su un browser desktop mostra un codice QR: scansionandolo, lo stesso identico link passa a un telefono, dove avvengono la foto del documento, la prova di liveness e il selfie. Lo provi subito sul Suo telefono.

  4. Predisporre un endpoint webhook

    Faccia puntare webhook_url a una route che accetti una POST, legga il corpo grezzo della richiesta (serve non elaborato per verificare la firma) e restituisca uno stato 2xx. In caso contrario ShieldID ritenta la consegna fino a tre volte.

    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. Verificare la firma

    Non agisca sul corpo di un webhook finché non ha verificato che provenga davvero da ShieldID. Calcoli un HMAC-SHA256 sul corpo grezzo con il Suo webhook secret e lo confronti con l'header 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. Legga il risultato

    Il payload del webhook contiene già tutto ciò che serve. Se preferisce recuperare il risultato da sé, ad esempio dopo un reindirizzamento, chiami direttamente l'endpoint del risultato.

    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. Gestire FAILED e un nuovo tentativo

    Una sessione che arriva a FAILED riporta un failure_reason. Mostri al richiedente un'informazione utile. Prossimamente: riprovare una sessione FAILED per riportarla a PENDING. Oggi consideri FAILED come stato finale e crei una nuova sessione se il richiedente vuole riprovare.

Prima di passare in produzione

Passi in produzione.

La struttura della richiesta non cambia tra sandbox e produzione: cambia solo la chiave. Verifichi questi punti prima di far completare a un richiedente reale una sessione vk_live_.

  • Sostituisca vk_sand_ con una chiave vk_live_. Nient'altro nella richiesta cambia.
  • Faccia puntare webhook_url a un endpoint reale, sempre attivo, che verifichi la firma, non a un request-bin o a un portatile.
  • Gestisca nella Sua app tutti e tre gli stati finali: VERIFIED, FAILED ed EXPIRED, non solo il caso favorevole.
  • Verifichi che il Suo return_url legga i parametri di query session_id e status che ShieldID aggiunge al reindirizzamento.
  • Controlli i prezzi correnti con GET /v1/pricing/{country} o dalla pagina dei prezzi, così che gli addebiti in produzione non siano una sorpresa.
  • Tenga le chiavi sandbox lontane da qualsiasi cosa a cui un richiedente reale possa accedere: una sessione sandbox è gratuita perché non è reale.

Domande

FAQ sulla guida rapida.

Inizia ora

Esegua subito il primo passaggio.

Richieda una chiave sandbox, incolli il primo comando cURL in un terminale e sarà già un passo avanti rispetto alla maggior parte delle integrazioni.

Richieda una chiave sandboxRiferimento API completo