> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.
# التحقق عبر NFC: واجهة API للجوازات والهويات الإلكترونية
> تحقق من جوازات السفر والهويات الإلكترونية عبر NFC مع Didit بأعلى درجات الأمان والتحقق التشفيري. الدفع لكل استدعاء $0.15.
تتيح لك المصادقة القائمة على تقنية NFC التحقق من مستندات الهوية عن طريق قراءة الشريحة الآمنة المدمجة في جوازات السفر وبطاقات الهوية الحديثة باستخدام إمكانيات NFC في الهاتف المحمول. ويوفر هذا **أعلى مستوى أمان متاح** لخدمة التحقق من الهوية.
موجّه التكامل للتحقق عبر NFC
نسخ الموجّه إلى الحافظة
\
\````# Goal
Integrate Didit NFC Verification — cryptographic ePassport / eID chip read — into your app.
\# Delivery mode
NFC is **session-only**. There is no standalone /v3/nfc/ endpoint. The chip is read by the Didit Web/Mobile SDK during a hosted session, which uses the device's NFC radio.
\# Steps
1\. Create a workflow that includes the NFC feature (Business Console or POST /v3/workflows/). NFC normally runs alongside ID Verification: the user first photographs the document so the SDK derives BAC/PACE keys from the MRZ, then taps the chip.
2\. Create a session — POST /v3/session/ with { workflow_id, vendor_data, callback }. See /sessions-api/create-session.
3\. Open the returned session.url on a mobile device with NFC (iOS 13+/Android with NFC enabled), or mount the native SDK in your app.
4\. After completion fetch the decision — GET /v3/session/{sessionId}/decision/ (or subscribe to session.status.updated).
curl (create session):
\```bash
curl -X POST 'https://verification.didit.me/v3/session/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"workflow_id": "YOUR_WORKFLOW_ID",
"vendor_data": "user-123",
"callback": "https://yourapp.com/post-kyc"
}'
\```
\# Decision shape
The NFC result is returned under the plural array `nfc_verifications[]` on the decision payload.
\> Heads-up: the V3 schema deliberately keeps the **plural-array** name `nfc_verifications[]` even though early integrators occasionally hit a singular `nfc_verification` key. Always read from the plural array — it is the canonical, multi-instance shape and matches every other feature.
\# Status enum (per nfc_verifications[].status)
"Not Started" | "In Progress" | "Approved" | "In Review" | "Declined" | "Abandoned" | "Kyc Expired"
\# Warnings (LogWarningChoices.NFC)
The warnings[] array on each nfc_verification includes risk codes such as:
NFC_NOT_READ, NFC_DATA_INVALID, NFC_DATA_DOES_NOT_MATCH_OCR, NFC_BAC_FAILED, NFC_PASSIVE_AUTHENTICATION_FAILED, NFC_ACTIVE_AUTHENTICATION_FAILED, NFC_CHIP_CLONED, NFC_DOCUMENT_REVOKED.
Full catalogue: /core-technology/nfc-verification/warnings-nfc-verification.
\# Failure modes to handle
\- Device has no NFC chip or NFC is disabled — the SDK falls back to OCR + face match; nfc_verifications[] will be empty.
\- The user fails to hold the chip long enough — status="Declined" with NFC_NOT_READ or NFC_BAC_FAILED. Allow a retry.
\- nfc_verifications[].status="Declined" with NFC_DATA_DOES_NOT_MATCH_OCR — the chip and the printed data disagree (likely tampered document). Do not approve.
\- Passive Authentication failed — the chip's signing certificate did not chain back to a trusted CSCA. Stop the flow.
\# Japan My Number Card (JPKI)
\- The My Number Card is read through JPKI, not ICAO 9303: native SDKs only, and the person enters the card PIN. Its item has chip_protocol "jpki", its evidence under jpki (chain_valid, signature_valid, revocation_status good | revoked | unchecked, attributes, attributes_match_ocr), and null ICAO fields (chip_data, authenticity, certificate_summary).
\- iOS host apps add D392F000260100000001 to com.apple.developer.nfc.readersession.iso7816.select-identifiers.
\- Not enabled in production yet: until it is, a My Number Card in a native SDK on an NFC phone skips NFC with nfc_skip_reason JPKI_UNAVAILABLE.
\# See also
\- Canonical schema: /reference/data-models#nfc-verification
\- Per-feature report: /core-technology/nfc-verification/report-nfc-verification
\- Risk catalogue: /core-technology/nfc-verification/warnings-nfc-verification
\- Supported documents: /core-technology/nfc-verification/supported-documents-nfc-verification
\- Full integration playbook: /integration/integration-prompt````
\
الصق في
***## المزايا الرئيسية| الفائدة | الوصف |
| - | - |
| **أعلى مستوى أمان** | يتحقق من التوقيعات التشفيرية مباشرة من الجهات الحكومية المصدرة |
| **سهل الاستخدام** | يعمل تلقائياً مع أي هاتف مزود بتقنية NFC |
| **مقاوم للتلاعب** | يكتشف التلاعب في المستندات الذي لا يمكن للعين البشرية رؤيته |
| **بيانات شاملة** | يستخرج بيانات إضافية لا تتوفر من خلال OCR وحده |
| **آلية احتياطية مرنة** | ينتقل بسلاسة إلى التحقق القياسي إذا لم تكن تقنية NFC متوفرة |***## كيفية تفعيل التحقق عبر NFC### التكامل مع SDK الأصلي (موصى به)يتوفر التحقق عبر NFC من خلال **حزم SDK الأصلية** الخاصة بنا، والتي تتيح الوصول الكامل إلى إمكانيات NFC في الجهاز:| المنصة | دعم NFC | التوثيق |
| - | - | - |
| **iOS** | ✅ دعم كامل | [توثيق iOS SDK](https://docs.didit.me/ar/integration/native-sdks/ios-sdk.md) |
| **Android** | ✅ دعم كامل | [توثيق Android SDK](https://docs.didit.me/ar/integration/native-sdks/android-sdk.md) |يتولى iOS SDK جميع إعدادات NFC تلقائياً، بما في ذلك:- معرّفات تطبيقات ISO7816 لجوازات السفر الإلكترونية
- إعداد الصلاحيات والإمكانيات
- قراءة الشريحة في الوقت الفعلي مع تقديم استجابة بصرية### تكامل الويب> ⚠️ **قيود المتصفح**
>
> إن التحقق عبر NFC **غير متوفر في متصفحات الويب** بسبب قيود المنصة:
>
> | المتصفح | دعم NFC |
> | - | - |
> | **Chrome (Android)** | واجهة Web NFC API تجريبية - غير مستقرة وتتطلب أذونات صريحة |
> | **Safari (iOS)** | لا يوجد دعم لواجهة Web NFC API |
> | **المتصفحات الأخرى** | لا يوجد دعم |
>
> بالنسبة لتكاملات الويب، يتم تخطي التحقق عبر NFC تلقائياً ويتابع المستخدمون إجراءات التحقق القياسية من المستند + صورة سيلفي.***## آلية العمل**1. بدء الجلسة**يبدأ المستخدم عملية التحقق من خلال تطبيقك أو منصتك:- **SDK الأصلي**: إطلاق سير عمل التحقق مباشرة داخل تطبيقك
- **الويب/ويب الأجهزة المحمولة**: يتم توجيه المستخدم لاستخدام تطبيق Didit App للتحقق عبر NFC، أو المتابعة باستخدام التحقق القياسي**2. التقاط صورة المستند**يلتقط المستخدم صورة لمستند الهوية الخاص به، مع التقاط:- **MRZ** (المنطقة المقروءة آلياً) — تُستخدم لاشتقاق مفاتيح الوصول إلى الشريحة
- **صور الوجهين الأمامي والخلفي للمستند** — البيانات المرئية وميزات الأمان
- **ميزات الأمان المرئية** — الصور المجسمة (الهولوغرام)، والعلامات المائية، والطباعة الدقيقة**3. اكتشاف دعم NFC**يتحقق النظام تلقائياً من توافق الجهاز والمستند:| الفحص | الوصف |
| - | - |
| **نوع المستند** | هل هو جواز سفر إلكتروني/بطاقة هوية إلكترونية مزود بشريحة NFC؟ |
| **إمكانات الجهاز** | هل يدعم الهاتف قراءة NFC؟ |
| **الأذونات** | هل تم منح أذونات NFC اللازمة؟ |> [!NOTE]
>
> إذا كان NFC غير متاح، تستمر عملية التحقق بسلاسة عبر التحقق القياسي من المستندات والتحقق البيومتري.**4. قراءة شريحة NFC**بالنسبة للأجهزة والمستندات المتوافقة:1) يتم توجيه المستخدم لوضع مستنده بالقرب من قارئ NFC في الهاتف
2) توفر استجابة مرئية توضح تقدم القراءة في الوقت الفعلي
3) يتم إنشاء اتصال آمن مع الشريحة باستخدام بروتوكولات PACE/BAC**5. استخراج البيانات**يستخرج النظام بيانات شاملة من الشريحة وفقاً لمعايير **ICAO 9303**:| مجموعة البيانات | المحتويات | الوصف |
| - | - | - |
| **SOD** | كائن أمان المستند | التوقيعات الرقمية لجميع مجموعات البيانات |
| **DG1** | البيانات الشخصية | الاسم، ورقم الهوية، وتاريخ الميلاد، وتاريخ الانتهاء |
| **DG2** | صورة الوجه | صورة رقمية عالية الدقة لحامل المستند |
| **DG7** | التوقيع | تمثيل رقمي لتوقيع حامل المستند |
| **DG11-14** | بيانات إضافية | قد تتضمن بصمات الأصابع، ومسح قزحية العين (إذا كانت مخزنة) |**6. التحقق التشفيري**تخضع البيانات المستخرجة لعملية تحقق تشفيري صارمة:> [accordion] التحقق من التوقيع الرقمي
>
> يتم التحقق من تجزئة كل مجموعة بيانات مقابل التوقيعات المخزنة في SOD، مما يضمن سلامة البيانات.> [accordion] التحقق من صحة سلسلة الشهادات
>
> يتم التحقق من صحة سلسلة الثقة: **شهادة المستند ← جهة تصديق توقيع الدولة ← الجذر الخاص بـ ICAO PKD**، مع المطابقة مقابل القوائم الرئيسية لـ CSCA ودليل المفاتيح العامة لـ ICAO.> [accordion] فحص إلغاء الشهادات
>
> يتم فحص الشهادات مقابل قوائم إلغاء الشهادات (CRLs) للتأكد من عدم إلغائها وعدم الإبلاغ عن سرقة المستند أو اختراقه.> [accordion] التحقق المتبادل
>
> تتم مطابقة البيانات المستخرجة عبر NFC والتحقق منها تبادلياً مقابل بيانات OCR المستخرجة من صور المستند، والمقارنة البيومترية للوجه، والتحقق من المجموع الاختباري لـ MRZ.**7. النتيجة ودرجة الثقة**تتضمن نتيجة التحقق النهائية ما يلي:| المخرجات | الوصف |
| - | - |
| **حالة التحقق عبر NFC** | ناجحة، أو فاشلة، أو تم تخطيها |
| **درجة اتساق البيانات** | مدى تطابق بيانات NFC مع البيانات المرئية |
| **التحقق من صحة الشهادة** | حالة التحقق من السلسلة الكاملة |
| **تعزيز الثقة** | يضيف NFC درجة ثقة كبيرة إلى عملية التحقق الإجمالية |***## المستندات المدعومةيعمل التحقق عبر NFC مع **جوازات السفر الإلكترونية (ePassports)** و**بطاقات الهوية الإلكترونية (eIDs)** التي تحتوي على شريحة NFC، وعادةً ما يُشار إليها بهذا الرمز على المستند:تحتوي معظم جوازات السفر الصادرة بعد عام 2006 على شرائح NFC. وتختلف التغطية حسب الدولة بالنسبة لبطاقات الهوية الوطنية. اطّلع على جميع [المستندات المدعومة](https://docs.didit.me/ar/core-technology/nfc-verification/supported-documents-nfc-verification.md).تحتوي بطاقة My Number اليابانية على نوع مختلف من الشرائح، وتتم قراءتها عبر JPKI بدلاً من ICAO 9303. راجع [بطاقة My Number اليابانية (JPKI)](#بطاقة-ماي-نمبر-اليابانية-jpki).***## بطاقة ماي نمبر اليابانية (JPKI)تحتوي بطاقة ماي نمبر اليابانية (マイナンバーカード) على شريحة، ولكنها ليست شريحة ICAO 9303. فهي تحمل شهادات صادرة بموجب JPKI، وهي البنية التحتية للمفاتيح العامة في اليابان، ومفاتيح خاصة لا توقّع إلا بعد إدخال حامل البطاقة لرمز PIN الخاص بها. تقرأ Didit هذه البطاقة في خطوة NFC نفسها، عبر JPKI بدلاً من ICAO 9303، وتوضّح كل نتيجة NFC البروتوكول المستخدم في `chip_protocol` (سواء `icao` أو `jpki`).> [!WARNING]
>
> **غير متوفرة بعد.** قراءة بطاقة ماي نمبر عبر JPKI غير مفعلة في بيئة الإنتاج. وإلى حين تفعيلها، فإن بطاقة ماي نمبر الملتقطة عبر SDK أصلي تتخطى خطوة NFC مع سبب التخطي `JPKI_UNAVAILABLE`، وتجري عملية التحقق من البطاقة عبر التقاط المستند ومطابقة الوجه كما كان من قبل.### المتطلبات| المتطلب | التفاصيل |
| - | - |
| **المستند** | بطاقة ماي نمبر اليابانية فقط. تحافظ جوازات السفر اليابانية على قراءة شريحة ICAO 9303. |
| **التكامل** | إصدار SDK أصلي يقرأ بطاقات ماي نمبر (iOS أو Android أو حزم SDK لـ React Native و Flutter المبنية عليهما). يُخطر الـ SDK منصة Didit بقدرته على قراءة JPKI؛ ويتخطى أي إصدار أقدم الخطوة مع `JPKI_UNAVAILABLE`. أما عمليات تكامل الويب و WebView فتتخطاها مع `INTEGRATION_WITHOUT_NFC_ACCESS`. |
| **الجهاز** | هاتف مزود بقارئ NFC. بدون وجوده، يجري تخطي الخطوة مع `DEVICE_WITHOUT_NFC`. |
| **تطبيق iOS المضيف** | وجود `D392F000260100000001` في معرّفات تحديد ISO7816 للتطبيق. راجع [إعداد NFC لنظام iOS](https://docs.didit.me/ar/integration/native-sdks/ios-sdk.md#إعداد-nfc). |
| **الشخص** | يعرف رمز PIN المكون من 4 أرقام للبطاقة، وأيضاً كلمة مرور التوقيع عندما يطلب سير العمل بيانات حامل البطاقة. |### ما يفعله الشخص**1. تصوير البطاقة**يلتقط الشخص صورة لبطاقة ماي نمبر في خطوة التحقق من الهوية، كما هو الحال مع أي مستند. تتعرف Didit على البطاقة وترسل خطوة JPKI NFC بدلاً من قراءة شريحة جواز السفر.**2. إدخال رمز PIN للبطاقة**يطلب الـ SDK رمز PIN المكون من 4 أرقام للبطاقة (利用者証明用電子証明書の暗証番号). وعند تفعيل إعداد `jpki_request_attributes` في عقدة NFC (وهو الإعداد الافتراضي)، فإنه يطلب أيضاً كلمة مرور التوقيع، وتسمى أيضاً رمز PIN للتوقيع (署名用電子証明書の暗証番号، من 6 إلى 16 محرفاً من الأحرف الكبيرة والأرقام).**3. تقريب البطاقة من الهاتف**يقرأ الـ SDK شهادات البطاقة، وتقوم البطاقة بتوقيع تحدٍّ لمرة واحدة من Didit باستخدام مفتاحها الخاص. يرفع الـ SDK الشهادات والتوقيعات. ولا تُرسل رموز PIN إلا إلى البطاقة فقط، ولا تصل إلى Didit على الإطلاق.> [!NOTE]
>
> تحسب البطاقة عدد المحاولات الخاطئة: إذ تقفل رمز PIN المكون من 4 أرقام بعد 3 محاولات متتالية خاطئة وكلمة مرور التوقيع بعد 5 محاولات، ويجب إعادة تعيين الرمز المقفل في المكتب البلدي التابع له حامل البطاقة. بعد أي إدخال خاطئ، يعرض الـ SDK عدد المحاولات المتبقية. ولا ينفذ أبداً المحاولة الأخيرة: فعندما تتبقى محاولة واحدة فقط، يتوقف ويخبر الشخص بالمكان الذي يمكنه إعادة التعيين فيه. اطلب من المستخدمين تجهيز رمز PIN وكلمة مرور التوقيع قبل البدء.### ما تتحقق منه Didit| الفحص | ما تتحقق منه Didit | التحذير عند الفشل (الإجراء الافتراضي) |
| - | - | - |
| **سلسلة الشهادات** | تتسلسل كل شهادة إلى جهة التصديق التابعة لـ JPKI والخاصة بنوعها، وتكون ضمن فترة صلاحيتها، وهي شهادة بطاقة ماي نمبر (`jpki.chain_valid`). | `JPKI_CERTIFICATE_INVALID` (رفض) |
| **البطاقة ورمز PIN** | يُتحقق من توقيع البطاقة على التحدي لمرة واحدة باستخدام شهادتها (`jpki.signature_valid`). لا توقّع البطاقة إلا بعد إدخال رمز PIN الخاص بها، لذا يثبت هذا أن الشخص يحمل البطاقة ويعرف رمز PIN. | `JPKI_SIGNATURE_INVALID` (رفض) |
| **الإلغاء** | لم يتم إلغاء أي شهادة (`jpki.revocation_status`). | `JPKI_CERTIFICATE_REVOKED` عند `revoked` (رفض)، و `JPKI_REVOCATION_UNCHECKED` عند `unchecked` (المراجعة) |
| **بيانات حامل البطاقة** | تطابق الاسم وتاريخ الميلاد والجنس والعنوان في شهادة التوقيع مع البيانات المقروءة من صورة البطاقة نفسها (`jpki.attributes_match_ocr`، `jpki.mismatched_attributes`). | `JPKI_AND_OCR_DATA_NOT_SAME` (المراجعة) |كل إجراء هو عبارة عن إعداد في عقدة NFC، لذا يمكنك تغييره إلى **لا يوجد إجراء** أو **المراجعة** أو **رفض**. راجع [تحذيرات NFC](https://docs.didit.me/ar/core-technology/nfc-verification/warnings-nfc-verification.md#بطاقة-my-number-اليابانية-jpki) و[تهيئة ميزة NFC](https://docs.didit.me/ar/management-api/workflows/feature-configs.md#nfc-/-جواز-السفر-الإلكتروني).### ما تعنيه حالة الإلغاء غير المفحوصة (unchecked)تعني `revocation_status: "unchecked"` أن Didit تحققت من سلسلة الشهادات وتوقيع البطاقة، ولكنها لم تتلقَّ أي رد حول ما إذا كانت الشهادة قد أُلغيت أم لا. تُلغى الشهادة على سبيل المثال عند الإبلاغ عن فقدان البطاقة. ونظراً لأنه لا يمكن استبعاد أن تكون البطاقة ملغاة، فلا تُعامل حالة `unchecked` على أنها `good` على الإطلاق. وتؤدي إلى إطلاق `JPKI_REVOCATION_UNCHECKED`، مما يرسل خطوة NFC إلى المراجعة افتراضياً. يمكنك اختيار نتيجة مختلفة باستخدام `jpki_revocation_unchecked_action`.عندما تكون سلسلة الشهادات غير صالحة أو يكون التوقيع غير صالح، لا تستفسر Didit عن الإلغاء: فتبقى الحالة `unchecked` ويتم إطلاق تحذير السلسلة أو التوقيع فقط.### بيانات حامل البطاقة والخصوصية- عند تفعيل `jpki_request_attributes`، يتضمن القرار اسم حامل البطاقة وتاريخ ميلاده وجنسه وعنوانه من شهادة التوقيع تحت `jpki.attributes`. وعند إيقاف تفعيله، يدخل الشخص رمز PIN المكون من 4 أرقام فقط: ولا تزال القراءة تثبت حيازة البطاقة ومعرفة رمز PIN، ولكنها لا تتضمن بيانات حامل البطاقة ولا تجري مقارنتها بصورة البطاقة.
- لا تقرأ خطوة NFC أبداً الرقم الفردي المكوّن من 12 رقماً (My Number) من الشريحة.
- يُبلغ القرار عما أثبتته البطاقة، ولا يُبلغ أبداً عن الشهادات نفسها أو أرقامها التسلسلية أو التوقيعات.تتضمن النتيجة الكاملة تفاصيل موضحة في [تقرير التحقق عبر NFC](https://docs.didit.me/ar/core-technology/nfc-verification/report-nfc-verification.md#بطاقة-my-number-اليابانية-jpki).***## أمثلة التكامل### حزمة SDK لنظام iOS (متوفرة الآن)```swift theme={null}
import DiditSdk
// NFC is automatically enabled when the document supports it
let config = DiditSdk.Configuration(
// NFC configuration is handled automatically
// Just ensure your app has the required entitlements
)
let result = try await DiditSdk.shared.startVerification(
with: sessionId,
configuration: config
)
```**[توثيق iOS SDK الكامل ←](https://docs.didit.me/ar/integration/native-sdks/ios-sdk.md)**### حزمة SDK لنظام Android (متوفرة الآن)```kotlin theme={null}
import me.didit.sdk.DiditSdk
// NFC is automatically enabled when the document supports it
DiditSdk.startVerification(
token = "your-session-token"
) { result ->
handleResult(result)
}
```**[توثيق Android SDK ←](https://docs.didit.me/ar/integration/native-sdks/android-sdk.md)*****## بنية الأمان```
┌─────────────────────────────────────────────────────────────┐
│ NFC Verification Flow │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────────────────┐ │
│ │ Document │───▶│ Phone │───▶│ Didit Backend │ │
│ │ NFC Chip │ │ NFC Read │ │ │ │
│ └──────────┘ └──────────┘ │ ┌────────────────┐ │ │
│ │ │ ICAO PKD │ │ │
│ │ │ Validation │ │ │
│ │ └────────────────┘ │ │
│ │ ┌────────────────┐ │ │
│ │ │ CSCA Master │ │ │
│ │ │ List Check │ │ │
│ │ └────────────────┘ │ │
│ │ ┌────────────────┐ │ │
│ │ │ CRL Revocation │ │ │
│ │ │ Check │ │ │
│ │ └────────────────┘ │ │
│ └──────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────┐ │
│ │ Verification Result │ │
│ │ + Confidence Score │ │
│ └──────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```***## الأسئلة الشائعة
**ماذا لو كان هاتف المستخدم لا يدعم NFC؟**
يكتشف مسار التحقق دعم NFC تلقائيًا. وإذا لم يكن متاحًا، يتابع المستخدمون إجراءات التحقق القياسية عبر المستند + صورة سيلفي. وتظل عملية التحقق آمنة، ولكن دون تعزيز الثقة الإضافي الذي توفره تقنية NFC.
**ماذا لو كان المستند لا يحتوي على شريحة NFC؟**
العديد من المستندات (خاصة جوازات السفر القديمة وبعض بطاقات الهوية الوطنية) لا تحتوي على شرائح NFC. يكتشف النظام ذلك ويستمر بسلاسة في عملية التحقق القياسية.
**ما مدى تحسين التحقق عبر NFC للدقة؟**
يوفر التحقق عبر NFC دليلاً تشفيرياً على أصالة المستند مباشرة من الحكومة المصدرة له. يزيد هذا بشكل كبير من الثقة في نتيجة التحقق ويكتشف محاولات التزوير المعقدة التي قد تجتاز الفحص البصري.
**هل التحقق عبر NFC مطلوب؟**
لا. يُعد NFC تحسينًا وليس متطلبًا إلزاميًا. يمكن تهيئة سير عمل التحقق لديك ليطلب NFC، أو يفضله عندما يكون متاحًا، أو يتخطاه تمامًا بناءً على مستوى تقبلك للمخاطر.
***
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.