API حوالہ
شناخت کی تصدیق کی API کا حوالہ۔
ہر وہ اینڈ پوائنٹ جسے آپ کال کر سکتے ہیں، ہر وہ فیلڈ جو آپ کو واپس ملے گی، اور ویب ہک آنے کے بعد اس کے ساتھ کیا کرنا ہے۔ فیلڈ کی ٹھیک ٹھیک اقسام کے لیے اپنے API origin پر /docs پر موجود لائیو OpenAPI دستاویز کو مستند ماخذ سمجھیں — یہ صفحہ اسی کا سادہ زبان والا ورژن ہے۔
بیس URL اور ماحول
ایک بیس URL۔ دو ماحول۔
ہر ریکویسٹ ایک ہی ہوسٹ پر جاتی ہے۔ آپ کس ماحول میں ہیں، اس کا فیصلہ مکمل طور پر اس سے ہوتا ہے کہ آپ کون سی API کی بھیجتے ہیں۔
| بنیادی URL (یہ دستاویزات) | https://api.shieldid.ca — illustrative; your production API origin is published together with your API keys. |
|---|---|
| Auth ہیڈر | X-Api-Key: <your key>، ہر ریکویسٹ پر، سوائے نیچے بیان کیے گئے دو عوامی اینڈ پوائنٹس کے۔ |
| Sandbox کلید کا سابقہ | vk_sand_… — اس کلید سے بنائے گئے سیشنز پر environment: "sandbox" درج ہوتا ہے اور ان کا کبھی بل نہیں بنتا۔ |
| پروڈکشن کلید کا سابقہ | vk_live_… — وہی ریکویسٹس، آپ کے پلان کے مطابق چارج کی جاتی ہیں۔ |
| مواد کی قسم | ہر ریکویسٹ باڈی اور جواب میں application/json۔ |
اینڈ پوائنٹس
مکمل v1 سطح۔
چھ JSON اینڈ پوائنٹس، اس کے ساتھ ایک ہوسٹڈ صفحہ اور ایک عوامی credential چیک جو بالکل JSON نہیں ہیں — آپ بس ان کا لنک دیتے ہیں۔
| Endpoint | Auth | What it does |
|---|---|---|
| POST /v1/sessions | X-Api-Key | ایک تصدیقی سیشن بنائیں۔ return_url اور webhook_url لازمی ہیں۔ session_id، verification_url اور status: "PENDING" واپس کرتا ہے۔ |
| GET /v1/sessions/{id} | X-Api-Key | ایک سیشن کی حالت اور اہم فیلڈز: status، confidence، environment۔ |
| GET /v1/sessions/{id}/result | X-Api-Key | سیشن کے VERIFIED یا FAILED ہونے کے بعد مکمل نتیجہ: person، ہر چیک کا فیصلہ، confidence، verified_until۔ |
| DELETE /v1/sessions/{id} | X-Api-Key | ایسے سیشن کو منسوخ کریں جو ابھی PENDING یا IN_PROGRESS ہو۔ جو سیشن پہلے ہی VERIFIED، FAILED یا EXPIRED ہو اسے منسوخ نہیں کیا جا سکتا۔ |
| GET /v1/credentials/{token} | None — public | جانچیں کہ کوئی تصدیق شدہ credential اس وقت درست ہے یا نہیں۔ API کلید درکار نہیں، لہٰذا اسے براؤزر سے کال کیا جا سکتا ہے۔ نوٹ: آج کے جواب میں صرف درست/غیر درست کا نشان ہی نہیں بلکہ تصدیق شدہ شخص کا نام اور دستاویز کی قسم/ملک بھی شامل ہوتا ہے — یہ لنک کسی ایسے تیسرے فریق کو نہ دیں جسے آپ یہ معلومات دکھانا نہیں چاہتے۔ |
| GET /v1/pricing/{country} | X-Api-Key | دو حرفی ISO 3166-1 ملکی کوڈ کے لیے ملک وار قیمتیں۔ |
| /v/{session_id} | ہوسٹڈ تصدیقی صفحہ — وہی verification_url جو سیشن واپس کرتا ہے۔ ڈیسک ٹاپ پر QR کوڈ دکھایا جاتا ہے؛ اسے اسکین کرنے سے درخواست گزار کے فون پر وہی لنک کھل جاتا ہے تاکہ وہ اپنی دستاویز اور سیلفی لے سکے۔ |
|---|---|
| /c/{session_id} | ایک تصدیق شدہ سیشن کے لیے عوامی، بغیر تصدیقِ شناخت والا credential چیک صفحہ۔ نوٹ: آج کے جواب میں صرف درست/غیر درست کا نشان ہی نہیں بلکہ تصدیق شدہ شخص کا نام اور دستاویز کی قسم/ملک بھی شامل ہوتا ہے — یہ لنک کسی ایسے تیسرے فریق کو نہ دیں جسے آپ یہ معلومات دکھانا نہیں چاہتے۔ |
| /docs | آپ کے اکاؤنٹ کے API origin کے لیے لائیو، انٹرایکٹو OpenAPI ریفرنس۔ |
سیشن بنانا
POST /v1/sessions، شروع سے آخر تک۔
درخواست، اور بالکل وہی جو واپس آتا ہے۔
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" }
}'| return_url | string، لازمی — درخواست گزار کے مکمل کرنے کے بعد اسے جہاں واپس بھیجا جاتا ہے۔ http یا https ہونا ضروری ہے۔ |
|---|---|
| webhook_url | string، لازمی — جہاں دستخط شدہ نتیجہ بھیجا جاتا ہے۔ نیچے ویب ہکس دیکھیں۔ |
| expected_name | string، لازمی — وہ نام جس کی آپ دستاویز پر توقع رکھتے ہیں، تاکہ شناختی کارڈ پر درج نام سے اس کا موازنہ کیا جا سکے۔ |
| expected_dob / expected_address | string، اختیاری — فراہم کرنے پر دستاویز سے موازنہ کیا جاتا ہے؛ تصدیق چلانے کے لیے ضروری نہیں۔ |
| locale | string، اختیاری — "en" یا "fr"۔ درخواست گزار کو نظر آنے والے ہوسٹڈ صفحے کی زبان طے کرتا ہے۔ |
| metadata | object، اختیاری — آپ کا اپنا ریفرنس ڈیٹا — درخواست کی آئی ڈی، ٹیننٹ آئی ڈی، یا کوئی بھی چیز جو آپ چاہتے ہیں کہ نتیجے اور ویب ہک میں بغیر تبدیلی کے واپس آئے۔ |
نتیجہ
GET /v1/sessions/{id}/result — جواب کی ساخت۔
یہی ساخت ویب ہک پے لوڈ میں بھی بھیجی جاتی ہے، اس لیے آپ کو اس اینڈ پوائنٹ کو بار بار poll کرنے کی شاذ ہی ضرورت پڑتی ہے۔
| session_id | وہ id جو آپ نے بنائی تھی۔ |
|---|---|
| status | PENDING، IN_PROGRESS، VERIFIED، FAILED یا EXPIRED۔ |
| environment | "sandbox" یا "production"، اس کلید کے مطابق جس نے سیشن بنایا۔ |
| person | دستاویز سے پڑھی گئی فیلڈز: نام، تاریخ پیدائش، دستاویز کی قسم، دستاویز کا ملک اور دائرہ اختیار، پتہ۔ |
| checks | ہر جانچ کا ایک الگ فیصلہ — نیچے دیکھیں۔ کبھی کوئی ایک مبہم اسکور نہیں۔ |
| confidence | تصدیق کے لیے ایک مجموعی عدد۔ فیس میچ سمیت انفرادی جانچیں پھر بھی مقررہ فیصلہ حد کے مقابل الگ سے رپورٹ ہوتی ہیں — یہ فیلڈ ان کی جگہ نہیں لیتی۔ |
| verified_until | VERIFIED سیشن پر، نتیجہ کتنی دیر تک تازہ سمجھا جاتا ہے۔ |
| failure_reason | FAILED سیشن پر سیٹ ہوتا ہے — مثلاً FACE_MATCH_BELOW_THRESHOLD یا CANCELLED_BY_API۔ ورنہ null۔ |
| metadata | سیشن بناتے وقت آپ نے جو کچھ بھیجا تھا، بلا تبدیلی۔ |
json
{
"session_id": "ses_9f2c1a",
"status": "VERIFIED",
"environment": "sandbox",
"person": {
"name": "Jordan Smith",
"dob": "1994-03-11",
"document_type": "drivers_licence",
"document_country": "CA",
"document_jurisdiction": "ON"
},
"checks": {
"document": "PASS",
"liveness": "PASS",
"antispoof": "PASS",
"face_match": "PASS"
},
"confidence": 88,
"verified_until": "2027-03-11T00:00:00Z",
"failure_reason": null,
"metadata": { "application_id": "app_9182" }
}Add-onchecks.document، checks.liveness، checks.antispoof اور checks.face_match میں سے ہر ایک کا نتیجہ PASS، FAIL یا SKIPPED ہوتا ہے۔ واچ لسٹ اسکریننگ (checks.sanctions — CLEAR، MATCH یا SKIPPED) ایک ایڈ آن ہے اور صرف ان اکاؤنٹس کے لیے ظاہر ہوتی ہے جو اسے آن کریں۔
سیشن کا لائف سائیکل
پانچ حالتیں، ایک راستہ۔
سیشن خود بخود آگے بڑھتا ہے؛ آپ اسٹیٹ مشین کو نہیں چلاتے، صرف اسے پڑھتے ہیں۔
| PENDING | بنایا گیا۔ کسی نے ابھی تک verification_url نہیں کھولا۔ |
|---|---|
| IN_PROGRESS | درخواست گزار نے لنک کھول لیا ہے اور کیپچر کے عمل میں کہیں موجود ہے۔ |
| VERIFIED | تمام جانچیں مکمل ہوئیں اور نتیجہ تیار ہے۔ حتمی حالت — نتیجے کا اینڈ پوائنٹ کال کریں یا ویب ہک پڑھیں۔ |
| FAILED | کم از کم ایک جانچ پاس نہیں ہوئی۔ failure_reason بتاتا ہے کہ کون سی۔ جلد آ رہا ہے: ایک ری ٹرائی جو سیشن کو PENDING پر ری سیٹ کر دے — تب تک FAILED کو حتمی سمجھیں اور اگر درخواست گزار دوبارہ کوشش کرنا چاہے تو نیا سیشن بنائیں۔ |
| EXPIRED | کوئی وقت پر مکمل نہ کر سکا۔ سیشن ایک ڈیفالٹ مدت (30 منٹ) کے بعد خودکار طور پر ختم ہو جاتے ہیں؛ دوبارہ کوشش کے لیے نیا سیشن بنائیں۔ |
DELETE /v1/sessions/{id} کسی PENDING یا IN_PROGRESS سیشن کو وقت سے پہلے منسوخ کر دیتا ہے۔ جو سیشن پہلے ہی VERIFIED، FAILED یا EXPIRED تک پہنچ چکا ہو اسے منسوخ نہیں کیا جا سکتا — وہ پہلے ہی مکمل ہو چکا ہے۔
خرابیاں
کس چیز کی منصوبہ بندی کریں۔
یہ وہ مختصر فہرست ہے جس کے مطابق آج کوڈ لکھنا مناسب ہے۔ خرابی کے کوڈز اور پے لوڈز کا مکمل اور تازہ ترین سیٹ /docs پر موجود لائیو OpenAPI میں درج ہے۔
| Status | Code | Meaning |
|---|---|---|
| 401 | UNAUTHORIZED | X-Api-Key ہیڈر موجود نہیں ہے۔ |
| 401 | INVALID_KEY_FORMAT | کی vk_sand_ یا vk_live_ سے شروع نہیں ہوتی، یا اکاؤنٹ کی کسی کی سے میل نہیں کھاتی۔ |
| 403 | FORBIDDEN | کی درست ہے مگر آپ نے جس سیشن یا وسیلے کی درخواست کی اس تک اس کی رسائی نہیں۔ |
| 404 | NOT_FOUND | اس id کے ساتھ کوئی سیشن، credential یا وسیلہ موجود نہیں۔ |
| 409 | CONFLICT | سیشن ایسی حالت میں نہیں ہے جو اس کارروائی کی اجازت دے — مثال کے طور پر کسی ایسے سیشن کو منسوخ کرنا جو پہلے ہی VERIFIED ہو۔ |
| 422 | VALIDATION_ERROR | کوئی مطلوبہ فیلڈ غائب ہے یا غلط شکل میں ہے — مثلاً return_url درست http یا https URL نہیں ہے۔ |
ویب ہکس
دستخط شدہ، ڈیلیور شدہ، دوبارہ کوشش کے ساتھ۔
جب کوئی سیشن VERIFIED یا FAILED تک پہنچتا ہے تو ShieldID اوپر بیان کردہ شکل آپ کے webhook_url پر POST کرتا ہے۔
- POST کے طور پر ڈیلیور ہوتا ہے، جس کی JSON باڈی اوپر دی گئی نتیجے کی شکل کے مطابق ہوتی ہے۔
- خام ریکویسٹ باڈی پر HMAC-SHA256 سے دستخط شدہ، جو X-Bio-Signature ہیڈر میں بھیجا جاتا ہے۔ پے لوڈ پر بھروسا کرنے سے پہلے اسے اپنے ویب ہک سیکرٹ سے جانچ لیں۔
- اگر آپ کا اینڈ پوائنٹ 2xx اسٹیٹس کے ساتھ جواب نہ دے تو لکیری بیک آف کے ساتھ تین بار تک دوبارہ کوشش کی جاتی ہے۔
- جلد آ رہا ہے: FAILED سیشن کی ری ٹرائی جو حل ہونے پر دوسرا ویب ہک ڈیلیور کرے۔ آج کے لیے، فی سیشن ایک ویب ہک کو اصول سمجھیں۔
- یہاں فیلڈ کے نام اس حوالے سے میل کھاتے ہیں۔ اگر اصل میں جو کچھ آئے وہ مختلف نظر آئے تو اس صفحے کے بجائے لائیو پے لوڈ پر بھروسا کریں اور ہمیں بتائیں — فیلڈ کی فہرست API کے مطابق رکھی جاتی ہے، اس کے برعکس نہیں۔
دستخط کی تصدیق کریں
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");
});Idempotency اور دوبارہ کوششیں
ایسے ہینڈلرز بنائیں جنہیں دو بار چلانا محفوظ ہو۔
فی الحال سیشن بنانے یا ویب ہک ڈیلیوری پر کوئی مخصوص idempotency کی موجود نہیں۔
- دوبارہ کوشش سے بھیجی گئی ویب ہک ڈیلیوری ایک ہی سیشن کے لیے ایک سے زیادہ بار آ سکتی ہے۔ اپنے ہینڈلر کو session_id + status پر مبنی رکھیں اور نتیجہ لکھنے کے عمل کو idempotent بنائیں۔
- ٹائم آؤٹ پر POST /v1/sessions کی آنکھ بند کر کے دوبارہ کوشش نہ کریں — پہلے دیکھ لیں کہ سیشن بنا یا نہیں، ورنہ ایک درخواست گزار کے لیے دو سیشن بن سکتے ہیں۔
- سیشن بنانے کے لیے ایک مخصوص Idempotency-Key ہیڈر منصوبے میں ہے۔
جلد آ رہا ہےسیشن بنانے پر Idempotency-Key کی معاونت
تازہ ترین رہیں
یہ حوالہ بدلتا رہتا ہے۔ چینج لاگ پر نظر رکھیں۔
فیلڈ کے اضافے، نئے خرابی کوڈز اور اینڈ پوائنٹ کی تبدیلیوں کا اعلان یہاں اس صفحے پر آنے سے پہلے وہاں ہوتا ہے۔
سوالات
حوالہ جاتی FAQ۔
اگلا
اس ریفرنس کو عملی استعمال میں لائیں۔
کوئیک اسٹارٹ پر عمل کریں اور ترتیب وار sandbox کلید سے تصدیق شدہ سیشن اور دستخط شدہ ویب ہک تک پہنچیں۔