> ## 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. # تقرير التحقق من رقم الهاتف: بيانات JSON لرمز OTP والمشغّل > حلل تقارير التحقق من رقم الهاتف مع Didit: بيانات المشغّل، نوع الخط، دورة OTP وتحذيرات المخاطر. بدءاً من $0.02 لكل OTP + رسوم المشغّل. يلتقط تقرير التحقق من رقم الهاتف النتيجة الكاملة لتحدي رمز OTP للهاتف: الجهة التي أرسلنا الرمز إليها، وشركة الاتصالات والقناة اللتين تعاملتا معه، وعدد المحاولات المستغرقة، وما إذا كان الرقم قابلاً للاستخدام لمرة واحدة أو رقم VoIP، وأي تطابقات عبر الجلسات مع قائمة الحظر الخاصة بك أو جلسات المستخدمين الآخرين. توثق هذه الصفحة بنية JSON التي يعيدها endpoint القرار لتتمكن من تحليل نتائج OTP، والبيانات الوصفية لشركات الاتصالات، وعلامات المخاطر لكل رقم تم التحقق منه. ![Didit phone verification report showing OTP outcome, carrier metadata and risk flags](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/phone-verification-report.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=9b5c6c6112303ebc60c0f287aafdb996) ## نظرة عامة يتم إنشاء تقرير التحقق من رقم الهاتف في كل مرة تُشغّل فيها عقدة سير العمل ميزة التحقق من رقم الهاتف. يمثل كل تقرير تحدي OTP واحداً لرقم هاتف واحد، ويتضمن: * رقم الهاتف مقسماً إلى البادئة، والرقم الوطني، والصيغة الكاملة وفق E.164، بالإضافة إلى رمز الدولة وفق ISO واسم الدولة. * البيانات الوصفية لشركة الاتصالات (`name`، `type`) التي تم تحديدها من شبكة الوجهة. * علامات المخاطر المنطقية (`is_disposable`، `is_virtual`) المستمدة من تحليل نوع الخط. * قناة التسليم الفعلية المستخدمة (`verification_method`) وعدد محاولات إرسال OTP. * سجل `lifecycle[]` زمني لكل عملية إرسال، وإعادة محاولة، وحدث تسليم، ومحاولة للتحقق من الرمز. * مصفوفة `matches[]` تُظهر ظهور الرقم نفسه في جلسات أخرى — بأي حالة، عبر عمليات التحقق من KYC وKYB والتحقق عبر API المستقل — أو في قائمة الحظر الخاصة بك. * مصفوفة `warnings[]` — أحداث المخاطر الصادرة أثناء عملية التحقق (راجع [تحذيرات التحقق من رقم الهاتف](https://docs.didit.me/ar/core-technology/phone-verification/warnings-phone-verification.md)). * معرّف `node_id` يحدد عقدة مخطط سير العمل التي أنتجت التقرير (جلسات V3 فقط). في تدفقات التحقق المستضافة، تتولى Didit إدارة عملية تبادل OTP نيابةً عنك. أما في عمليات التكامل المباشر عبر API، فيتكون التدفق نفسه من استدعاءين — [`POST /v3/phone/send/`](https://docs.didit.me/ar/standalone-apis/phone-send) لتسليم الرمز و[`POST /v3/phone/check/`](https://docs.didit.me/ar/standalone-apis/phone-check) للتحقق من صحة ما أدخله المستخدم. يكون رمز OTP المعلق صالحاً لمدة **5 دقائق من أول عملية إرسال** (ولا تمدد عمليات إعادة المحاولة هذه النافذة الزمنية). في جلسات سير العمل، يحصل المستخدمون افتراضياً على محاولتَي إرسال لرمز OTP (`phone_max_retries`) ومحاولتَي إدخال للرمز (`phone_max_check_attempts`) — وكلاهما قابل للضبط لكل عقدة سير عمل؛ واستنفاد أي من الحدين يُنهي الخطوة بالحالة `Declined` مع الرمز `VERIFICATION_CODE_ATTEMPTS_EXCEEDED`. ويتيح API المستقل للهاتف 3 محاولات لإدخال الرمز لكل عملية تحقق. ## أين يظهر في استجابات API يعيد endpoint القرار (`GET /v3/session/{sessionId}/decision/`) تقارير الهاتف تحت مفتاح المصفوفة بصيغة الجمع **`phone_verifications`**. تحتوي المصفوفة على إدخال واحد لكل عقدة تحقق من رقم الهاتف في مخطط سير العمل — عادةً ما يكون إدخالاً واحداً، ولكن قد تُنتج تدفقات التحقق الإضافي عدة إدخالات. ```json theme={null} { "session_id": "11111111-1111-1111-1111-111111111111", "status": "Approved", "phone_verifications": [ { "status": "Approved", "node_id": "feature_phone_1", "...": "..." } ] } ``` تعني القيمة `null` أنه لم يتم تشغيل أي خطوة تحقق من رقم الهاتف بعد. كرّر المرور على المصفوفة (بدلاً من قراءة `phone_verifications[0]`) عندما يمكن لسير العمل الخاص بك جمع أكثر من رقم هاتف واحد. ## المخطط يوجد المخطط القياسي، حقلًا بحقل، في صفحة [نماذج البيانات](https://docs.didit.me/ar/reference/data-models.md#التحقق-من-رقم-الهاتف). ```typescript theme={null} interface PhoneVerification { status: "Not Finished" | "Approved" | "Declined" | "In Review" | "Expired"; phone_number_prefix: string; // E.g. "+34" phone_number: string; // National number, no prefix full_number: string; // Full E.164, e.g. "+34600600600" country_code: string; // ISO 3166-1 alpha-2, e.g. "ES" country_name: string; carrier: { name: string; type: // From LineTypeChoices | "mobile" | "fixed_line" | "voip" | "isp" | "vpn" | "toll_free" | "premium_rate" | "shared_cost" | "local_rate" | "satellite" | "pager" | "payphone" | "voice_mail" | "calling_cards" | "service" | "short_codes_commercial" | "universal_access" | "other" | "unknown"; }; is_disposable: boolean; // Temporary / burner number is_virtual: boolean; // true when carrier.type is voip, isp or vpn verification_method: // Actual channel that delivered the OTP | "sms" | "whatsapp" | "telegram" | "voice" | "rcs" | "viber" | "zalo"; verification_attempts: number; // OTP send attempts (initial send + resends) verified_at: string | null; // ISO 8601, set when a valid OTP was entered warnings: Warning[]; // Risk events emitted during verification lifecycle: PhoneLifecycleEvent[]; // OTP send/retry/delivery/check timeline matches: PhoneMatch[]; // Cross-session / blocklist matches (max 5) node_id: string; // Workflow graph node that produced this report } ``` ### قيم الحالة | الحالة | المعنى | | - | - | | `Not Finished` | بدأ إرسال رمز OTP ولكن لم يتم إنهاء عملية التحقق بعد. | | `Approved` | أدخل المستخدم رمز OTP صالحاً ولم يتطابق أي خطر يؤدي إلى الرفض. | | `Declined` | انطلق تحذير رفض تلقائي (قائمة الحظر، مخاطر عالية، تجاوز عدد المحاولات) أو تطابق إجراء مخاطر تم تكوينه على `DECLINE`. | | `In Review` | وجّه إجراء مخاطر تم تكوينه على `REVIEW` الخطوة إلى مراجعة يدوية. | | `Expired` | انقضت نافذة رمز OTP المحددة بـ 5 دقائق دون إدخال رمز صالح — ينطبق على عمليات التحقق المنشأة عبر API الهاتف المستقل. | ### أنواع أحداث دورة الحياة يتم ترتيب `lifecycle[]` زمنياً. يحتوي كل حدث على `type` و`timestamp` و`details` ورسم `fee` قابل للفوترة (عند الاقتضاء): | نوع الحدث | يُرسَل عند | | - | - | | `PHONE_VERIFICATION_MESSAGE_SENT` | محاولة إرسال رمز OTP الأولى عبر القناة المطلوبة. | | `PHONE_VERIFICATION_RETRY_MESSAGE_SENT` | إرسال رمز OTP لاحق بعد أن طلب المستخدم إعادة الإرسال. | | `PHONE_VERIFICATION_BLOCKED` | تم حظر الإرسال (رسائل مزعجة، مريب، محاولات متكررة، رقم غير صالح). | | `PHONE_DELIVERY_DELIVERED` | أكدت شركة الاتصالات التسليم عبر القناة الفعلية المستخدمة. | | `PHONE_DELIVERY_UNDELIVERABLE` | أبلغت شركة الاتصالات بتعذر تسليم الرسالة. | | `VALID_CODE_ENTERED` | أرسل المستخدم رمز OTP الصحيح. | | `INVALID_CODE_ENTERED` | أرسل المستخدم رمز OTP غير صحيح (يُحتسب ضمن الحد الأقصى لإدخال الرمز). | | `PHONE_VERIFICATION_APPROVED` | تم تعيين الحالة على مستوى الميزة إلى `Approved`. | | `PHONE_VERIFICATION_DECLINED` | تم تعيين الحالة على مستوى الميزة إلى `Declined`. | | `PHONE_VERIFICATION_IN_REVIEW` | تم تعيين الحالة على مستوى الميزة إلى `In Review`. | | `PHONE_VERIFICATION_EXPIRED` | انقضت نافذة رمز OTP دون إدخال رمز صالح. | يعتمد payload الخاص بـ `details` على عائلة الحدث: * **أحداث الإرسال** (`PHONE_VERIFICATION_MESSAGE_SENT` و`PHONE_VERIFICATION_RETRY_MESSAGE_SENT` و`PHONE_VERIFICATION_BLOCKED`) — `{ status, reason, channel, actual_channel }`. تكون قيمة `status` إما `Success` أو `Retry` أو `Blocked`؛ وتكون قيمة `reason` هي `null` ما لم يتم حظر الإرسال (`invalid_phone_number`، `repeated_attempts`، `suspicious`، `spam`، `unknown`)؛ ويمثل `channel` القناة المطلوبة و`actual_channel` القناة التي قامت بالتسليم فعلياً (على سبيل المثال، إرسال عبر WhatsApp رجع تلقائياً إلى SMS كبديل). * **أحداث التسليم** (`PHONE_DELIVERY_DELIVERED` و`PHONE_DELIVERY_UNDELIVERABLE`) — `{ channel, status }` مع كون `status` إما `delivered` أو `undeliverable`. * **أحداث التحقق** (`VALID_CODE_ENTERED` و`INVALID_CODE_ENTERED`) — `{ code_tried, status }` مع كون `status` إما `Approved` أو `Declined` أو `Failed` أو `Expired or Not Found`. * **أحداث الحالة النهائية** — `null`، باستثناء `PHONE_VERIFICATION_DECLINED` / `PHONE_VERIFICATION_IN_REVIEW` اللذين يحملان `{ "reason": "" }` (على سبيل المثال `PHONE_NUMBER_IN_BLOCKLIST`). الرسوم `fee` في حدث الإرسال هي السعر الإجمالي لعملية الإرسال تلك: سعر شركة الاتصالات أو WhatsApp بالإضافة إلى رسوم Didit البالغة $0.02، أو رسوم Didit البالغة $0.02 فقط لرمز WhatsApp مُرسل من [رقم WhatsApp Business الخاص بك](https://docs.didit.me/ar/core-technology/phone-verification/overview.md#إرسال-رموز-whatsapp-من-رقمك-الخاص). وتكون هي السعر التقديري حتى يتم تأكيد التسليم، ثم يصبح المبلغ الفعلي المفوتر. عمليات الإرسال ذات الحالة `Blocked` فقط هي المضمونة بأنها مجانية: حيث تُفرض رسوم أي إرسال آخر عند إنهاء عملية التحقق أو انتهاء صلاحيتها، حتى لو لم يتم تأكيد التسليم مطلقاً أو كانت الرسالة غير قابلة للتسليم. وتحمل أحداث التسليم والتحقق والحالة دائماً `fee: 0`. ### التطابقات عبر الجلسات يسجل `matches[]` الجلسات الأخرى في نفس التطبيق التي ظهر فيها نفس الرقم — عبر عمليات التحقق من KYC وKYB وAPI المستقل، بغض النظر عن حالتها — بالإضافة إلى مطابقات قائمة الحظر المكونة في [قوائم Management API](https://docs.didit.me/ar/management-api/lists/overview.md). يتم استبعاد الجلسات التي تشارك `vendor_data` الخاصة بالجلسة الحالية (فالمستخدم النهائي نفسه لا يطابق نفسه)، ويبلغ الحد الأقصى للمصفوفة **5** إدخالات. وعندما يكون الرقم موجوداً في قائمة الحظر الخاصة بك ولكن لا توجد أي جلسة متطابقة مدرجة في قائمة الحظر، يُضاف إدخال تركيبي مع `source: "list_entry"` (مع تعيين جميع حقول الجلسة إلى `null`) في بداية المصفوفة. ```typescript theme={null} interface PhoneMatch { session_id: string | null; // null when source = "list_entry" session_number: number | null; vendor_data: string | null; verification_date: string | null; // ISO 8601, creation date of the matched session phone_number: string; status: string | null; // Status of the matched session is_blocklisted: boolean; api_service: string | null; // Set when the matched session came from a standalone API source: "session" | "list_entry"; // "list_entry" = manual blocklist hit } ``` ## أمثلة ### مقبولة — رمز OTP عبر WhatsApp، مشغّل شبكة الجوال ```json theme={null} { "status": "Approved", "phone_number_prefix": "+34", "phone_number": "600600600", "full_number": "+34600600600", "country_code": "ES", "country_name": "Spain", "carrier": { "name": "Orange", "type": "mobile" }, "is_disposable": false, "is_virtual": false, "verification_method": "whatsapp", "verification_attempts": 1, "verified_at": "2025-08-24T09:12:39.684292Z", "warnings": [], "lifecycle": [ { "type": "PHONE_VERIFICATION_MESSAGE_SENT", "timestamp": "2025-08-24T09:12:30.580554Z", "details": { "status": "Success", "reason": null, "channel": "whatsapp", "actual_channel": "whatsapp" }, "fee": 0.0509 }, { "type": "PHONE_DELIVERY_DELIVERED", "timestamp": "2025-08-24T09:12:31.000000Z", "details": { "channel": "whatsapp", "status": "delivered" }, "fee": 0 }, { "type": "VALID_CODE_ENTERED", "timestamp": "2025-08-24T09:12:39.662157Z", "details": { "code_tried": "123456", "status": "Approved" }, "fee": 0 }, { "type": "PHONE_VERIFICATION_APPROVED", "timestamp": "2025-08-24T09:12:39.684292Z", "details": null, "fee": 0 } ], "matches": [], "node_id": "feature_phone_1" } ``` ### مرفوضة — رقم VoIP مدرج في قائمة الحظر أدخل المستخدم رمز OTP صالحاً، لكن إتمام العملية أظهر أن الرقم موجود في قائمة الحظر الخاصة بالتطبيق (رفض تلقائي) واكتشف أن نوع خطه هو VoIP (تُرك `voip_number_action` على `NO_ACTION`، لذا يُسجّل كـ `information`). ولأنه لا توجد جلسة متطابقة مدرجة في قائمة الحظر، يظهر تطابق قائمة الحظر كتطابق `list_entry` تركيبي. ```json theme={null} { "status": "Declined", "phone_number_prefix": "+1", "phone_number": "5551234567", "full_number": "+15551234567", "country_code": "US", "country_name": "United States", "carrier": { "name": "VoIP Carrier", "type": "voip" }, "is_disposable": false, "is_virtual": true, "verification_method": "sms", "verification_attempts": 1, "verified_at": "2025-08-24T09:11:10.221340Z", "warnings": [ { "feature": "PHONE", "risk": "PHONE_NUMBER_IN_BLOCKLIST", "additional_data": { "blocklisted_session_id": null, "blocklisted_session_number": null, "api_service": null }, "log_type": "error", "short_description": "Phone number in blocklist", "long_description": "The system detected that the phone number is in the blocklist, which is not allowed.", "node_id": "feature_phone_1" }, { "feature": "PHONE", "risk": "VOIP_NUMBER_DETECTED", "additional_data": null, "log_type": "information", "short_description": "VoIP number detected", "long_description": "The system detected that the phone number is a VoIP number, which is not allowed.", "node_id": "feature_phone_1" } ], "lifecycle": [ { "type": "PHONE_VERIFICATION_MESSAGE_SENT", "timestamp": "2025-08-24T09:11:00.000000Z", "details": { "status": "Success", "reason": null, "channel": "sms", "actual_channel": "sms" }, "fee": 0.0509 }, { "type": "VALID_CODE_ENTERED", "timestamp": "2025-08-24T09:11:10.221340Z", "details": { "code_tried": "482917", "status": "Approved" }, "fee": 0 }, { "type": "PHONE_VERIFICATION_DECLINED", "timestamp": "2025-08-24T09:11:10.350000Z", "details": { "reason": "PHONE_NUMBER_IN_BLOCKLIST" }, "fee": 0 } ], "matches": [ { "session_id": null, "session_number": null, "vendor_data": null, "verification_date": null, "phone_number": "+15551234567", "status": null, "is_blocklisted": true, "api_service": null, "source": "list_entry" } ], "node_id": "feature_phone_1" } ``` ## ذات صلة * [نظرة عامة على التحقق من رقم الهاتف](https://docs.didit.me/ar/core-technology/phone-verification/overview.md) — سلوك الميزة، الأسعار، القنوات المدعومة. * [تحذيرات التحقق من رقم الهاتف](https://docs.didit.me/ar/core-technology/phone-verification/warnings-phone-verification.md) — كل رمز مخاطر، والمُشغِّلات التي تؤدي إلى الرفض والإجراءات القابلة للتكوين. * [نماذج البيانات — التحقق من رقم الهاتف](https://docs.didit.me/ar/reference/data-models.md#التحقق-من-رقم-الهاتف) — المخطط القياسي حقلاً بحقل. * [API الهاتف المستقل](https://docs.didit.me/ar/standalone-apis/phone-send.md) — نقطتا endpoint الخاصتان بـ `POST /v3/phone/send/` و[`POST /v3/phone/check/`](https://docs.didit.me/ar/standalone-apis/phone-check). * [Management API — القوائم](https://docs.didit.me/ar/management-api/lists/overview.md) — إدارة قائمة حظر الهواتف التي تغذي `matches[]` بـ `source: list_entry`. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.