Ana içeriğe geç
ShieldID

Hızlı başlangıç

Kimlik doğrulama hızlı başlangıç kılavuzu.

Sandbox anahtarından ilk imzalı webhook'a, sırasıyla. Her adımda çalışan bir örnek vardır — kopyalayın, kendi anahtarınızı ve URL'lerinizi ekleyin ve çalıştırın.

Sandbox anahtarı talep edinTam API referansı

Adım adım

Yedi adım, bir öğleden sonra.

  1. Sandbox anahtarı alın

    Sandbox anahtarları (vk_sand_ öneki), self-servis kayıt geliştirilirken talep üzerine verilir. İletişim formu üzerinden isteyin — çoğu talep aynı iş günü içinde sonuçlanır. Sandbox oturumları asla ücretlendirilmez, bu nedenle başlamak için beklemenize gerek yok.

  2. İlk oturumunuzu oluşturun

    Tek bir çağrı. Bir return_url (başvuru sahibinin işlemi bitirdiğinde yönlendirileceği adres) ve bir webhook_url (imzalı sonucun gönderileceği adres) iletin. Karşılığında bir session_id ve bir verification_url alırsınız.

    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. Bağlantıyı başvuru sahibine iletin

    verification_url adresini açtığınızda barındırılan sayfayı görürsünüz. Masaüstü tarayıcıda bir QR kod gösterilir; bu kodu taramak aynı bağlantıyı telefona aktarır. Belge fotoğrafı, canlılık testi ve selfie işlemleri de asıl olarak telefonda gerçekleşir. Şimdi kendi telefonunuzda deneyin.

  4. Bir webhook uç noktası hazırlayın

    webhook_url değerini, bir POST kabul eden, ham istek gövdesini okuyan (imzayı doğrulamak için gövdeye ayrıştırılmamış haliyle ihtiyacınız vardır) ve 2xx durum kodu döndüren bir rotaya yönlendirin. Aksi halde ShieldID teslimatı en fazla üç kez yeniden dener.

    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. İmzayı doğrulayın

    Bir webhook gövdesinin gerçekten ShieldID'den geldiğini doğrulamadan işlem yapmayın. Webhook gizli anahtarınızla ham gövde üzerinden bir HMAC-SHA256 hesaplayın ve sonucu X-Bio-Signature başlığıyla karşılaştırın.

    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. Sonucu okuyun

    Webhook yükü ihtiyacınız olan her şeyi zaten içerir. Sonucu kendiniz almak isterseniz (örneğin bir yönlendirmeden sonra), sonuç uç noktasını doğrudan çağırın.

    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. FAILED durumunu ve yeniden denemeyi ele alın

    FAILED durumuna düşen bir oturum bir failure_reason içerir. Başvuru sahibine faydalı bir bilgi gösterin. Yakında: FAILED durumundaki bir oturumu yeniden deneyerek PENDING durumuna sıfırlama. Bugün için FAILED durumunu nihai kabul edin; başvuru sahibi tekrar denemek isterse yeni bir oturum oluşturun.

Anahtarı çevirmeden önce

Canlıya geçin.

İstek yapısı sandbox ile canlı ortam arasında hiç değişmez; yalnızca anahtar değişir. Gerçek bir başvuru sahibini vk_live_ oturumundan geçirmeden önce şunları doğrulayın.

  • vk_sand_ anahtarını bir vk_live_ anahtarıyla değiştirin. İsteğin başka hiçbir yönü değişmez.
  • webhook_url değerini, imzayı doğrulayan, gerçek ve her zaman açık bir uç noktaya yönlendirin; bir request-bin'e ya da bir dizüstü bilgisayara değil.
  • Uygulamanızda üç nihai durumun hepsini ele alın: VERIFIED, FAILED ve EXPIRED; yalnızca sorunsuz senaryoyu değil.
  • return_url adresinizin, ShieldID'nin yönlendirme sırasında eklediği session_id ve status sorgu parametrelerini okuduğunu doğrulayın.
  • Canlı ortam ücretleri sürpriz olmasın diye güncel fiyatları GET /v1/pricing/{country} ile veya fiyatlandırma sayfasından kontrol edin.
  • Sandbox anahtarlarını, gerçek bir başvuru sahibinin erişebileceği hiçbir yerde tutmayın; sandbox oturumu gerçek olmadığı için ücretsizdir.

Sorular

Hızlı başlangıç SSS.

Başlayın

İlk adımı hemen çalıştırın.

Bir sandbox anahtarı talep edin, ilk cURL komutunu bir terminale yapıştırın; çoğu entegrasyonun zaten bir adım önündesiniz.

Sandbox anahtarı talep edinTam API referansı