Przejdź do treści głównej
ShieldID

Szybki start

Szybki start weryfikacji tożsamości.

Od klucza sandbox do pierwszego podpisanego webhooka, krok po kroku. Każdy krok zawiera działający przykład — proszę go skopiować, podstawić własny klucz i adresy URL i uruchomić.

Zamów klucz sandboxPełna dokumentacja API

Krok po kroku

Siedem kroków, jedno popołudnie.

  1. Uzyskaj klucz sandbox

    Klucze sandbox (prefiks vk_sand_) są wydawane na żądanie, dopóki trwają prace nad samodzielną rejestracją. Proszę o niego poprosić za pomocą formularza kontaktowego — większość próśb jest realizowana tego samego dnia roboczego. Sesje sandbox nigdy nie są rozliczane, więc nie ma powodu, aby zwlekać z rozpoczęciem.

  2. Utworzenie pierwszej sesji

    Jedno wywołanie. Przekazują Państwo return_url (adres, na który trafia wnioskodawca po zakończeniu) oraz webhook_url (adres, na który trafia podpisany wynik). W odpowiedzi otrzymują Państwo session_id oraz 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. Przekazanie wnioskodawcy linku

    Po otwarciu verification_url zobaczą Państwo stronę hostowaną. W przeglądarce na komputerze wyświetla ona kod QR — jego zeskanowanie przekazuje identyczny link na telefon, na którym odbywa się właściwe zdjęcie dokumentu, test żywotności i selfie. Proszę wypróbować to od razu na własnym telefonie.

  4. Uruchomienie punktu końcowego webhooka

    Proszę wskazać w webhook_url trasę, która przyjmuje żądanie POST, odczytuje surową treść żądania (potrzebują ją Państwo nieprzetworzoną, aby sprawdzić podpis) i zwraca status 2xx. W każdym innym przypadku ShieldID ponawia dostarczenie do trzech razy.

    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. Weryfikacja podpisu

    Nie należy podejmować działań na podstawie treści webhooka, dopóki nie sprawdzą Państwo, że faktycznie pochodzi od ShieldID. Proszę obliczyć HMAC-SHA256 z surowej treści przy użyciu sekretu webhooka i porównać wynik z nagłówkiem 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. Odczyt wyniku

    Ładunek webhooka zawiera już wszystko, czego Państwo potrzebują. Jeśli wolą Państwo samodzielnie pobrać wynik — na przykład po przekierowaniu — mogą Państwo wywołać bezpośrednio punkt końcowy wyniku.

    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. Obsługa statusu FAILED i ponowna próba

    Sesja, która kończy ze statusem FAILED, zawiera failure_reason. Proszę pokazać wnioskodawcy coś użytecznego. Wkrótce: ponowna próba dla sesji FAILED, resetująca ją do PENDING. Obecnie FAILED należy traktować jako stan końcowy i utworzyć nową sesję, jeśli wnioskodawca chce spróbować ponownie.

Zanim przełączą Państwo na produkcję

Przejście na produkcję.

Kształt żądania nie zmienia się między sandbox a produkcją — zmienia się tylko klucz. Proszę to potwierdzić, zanim prawdziwy wnioskodawca przejdzie przez sesję vk_live_.

  • Proszę zamienić klucz vk_sand_ na klucz vk_live_. Nic więcej w żądaniu się nie zmienia.
  • Proszę wskazać w webhook_url rzeczywisty, stale działający punkt końcowy, który weryfikuje podpis — a nie request-bin ani laptop.
  • Proszę obsłużyć w aplikacji wszystkie trzy stany końcowe: VERIFIED, FAILED i EXPIRED, a nie tylko scenariusz pomyślny.
  • Proszę upewnić się, że return_url odczytuje parametry zapytania session_id i status, które ShieldID dołącza podczas przekierowania.
  • Proszę sprawdzić aktualny cennik za pomocą GET /v1/pricing/{country} lub na stronie cennika, aby opłaty produkcyjne nie były niespodzianką.
  • Kluczy sandbox należy trzymać z dala od wszystkiego, do czego mógłby dotrzeć prawdziwy wnioskodawca — sesja sandbox jest bezpłatna, ponieważ nie jest prawdziwa.

Pytania

FAQ do krótkiego przewodnika.

Rozpocznij

Wykonajcie Państwo pierwszy krok już teraz.

Proszę zamówić klucz sandbox, wkleić pierwsze polecenie cURL do terminala, a już będą Państwo przed większością integracji.

Zamów klucz sandboxPełna dokumentacja API