API التحقق من رقم الهاتف: فحص رمز SMS

curl

curl -X POST https://verification.didit.me/v3/phone/check/ \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "phone_number": "+14155552671",
    "code": "123456",
    "voip_number_action": "DECLINE"
  }'

import Didit from "@didit-protocol/sdk-node";

// Reads DIDIT_API_KEY.
const didit = new Didit();

const result = await didit.phone.checkCode({
  phone_number: "+14155552671",
  code: "123456",
});
console.log(result);

ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()

result, err := client.Phone.CheckCode(ctx, didit.PhoneCheckCodeParams{
	PhoneNumber: "+14155552671",
	Code:        "123456",
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)

import me.didit.Didit;
import me.didit.types.PhoneCheckCodeParams;

// Reads DIDIT_API_KEY.
Didit client = new Didit();

var result = client.phone().checkCode(PhoneCheckCodeParams.builder()
        .phoneNumber("+14155552671")
        .code("123456")
        .build());
System.out.println(result);

<?php

require 'vendor/autoload.php';

use Didit\DiditClient;

// Reads DIDIT_API_KEY.
$didit = new DiditClient();

$result = $didit->phone->checkCode([
    'phone_number' => '+14155552671',
    'code' => '123456',
]);
print_r($result->toArray());

using System;
using System.Text.Json;
using Didit;

// Reads DIDIT_API_KEY.
using var client = new DiditClient();

var result = await client.Phone.CheckCodeAsync(new PhoneCheckCodeParams
{
    PhoneNumber = "+14155552671",
    Code = "123456",
});
Console.WriteLine(JsonSerializer.Serialize(result));

{
  "request_id": "e39cb057-92fc-4b59-b84e-02fec29a0f24",
  "status": "Approved",
  "message": "The verification code is correct.",
  "phone": {
    "status": "Approved",
    "phone_number_prefix": "+1",
    "phone_number": "4155552671",
    "full_number": "+14155552671",
    "country_code": "US",
    "country_name": "United States",
    "carrier": {
      "name": "AT&T",
      "type": "mobile"
    },
    "is_disposable": false,
    "is_virtual": false,
    "verification_method": "whatsapp",
    "verification_attempts": 1,
    "verified_at": "2026-06-12T01:24:47.311323Z",
    "warnings": [],
    "lifecycle": [
      {
        "type": "PHONE_VERIFICATION_MESSAGE_SENT",
        "timestamp": "2026-06-12T01:23:39.580554+00:00",
        "details": {
          "status": "Success",
          "reason": null,
          "channel": "whatsapp",
          "actual_channel": "whatsapp"
        },
        "fee": 0.0509
      },
      {
        "type": "PHONE_DELIVERY_DELIVERED",
        "timestamp": "2026-06-12T01:23:43.118220+00:00",
        "details": {
          "channel": "whatsapp",
          "status": "delivered"
        },
        "fee": 0
      },
      {
        "type": "VALID_CODE_ENTERED",
        "timestamp": "2026-06-12T01:24:47.311201+00:00",
        "details": {
          "code_tried": "123456",
          "status": "Approved"
        },
        "fee": 0
      },
      {
        "type": "PHONE_VERIFICATION_APPROVED",
        "timestamp": "2026-06-12T01:24:47.384292+00:00",
        "details": null,
        "fee": 0
      }
    ],
    "matches": []
  },
  "vendor_data": "user-1234",
  "metadata": null,
  "created_at": "2026-06-12T01:24:47.401719+00:00"
}

POST

phone

check

curl

curl -X POST https://verification.didit.me/v3/phone/check/ \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "phone_number": "+14155552671",
    "code": "123456",
    "voip_number_action": "DECLINE"
  }'

import Didit from "@didit-protocol/sdk-node";

// Reads DIDIT_API_KEY.
const didit = new Didit();

const result = await didit.phone.checkCode({
  phone_number: "+14155552671",
  code: "123456",
});
console.log(result);

ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()

result, err := client.Phone.CheckCode(ctx, didit.PhoneCheckCodeParams{
	PhoneNumber: "+14155552671",
	Code:        "123456",
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)

import me.didit.Didit;
import me.didit.types.PhoneCheckCodeParams;

// Reads DIDIT_API_KEY.
Didit client = new Didit();

var result = client.phone().checkCode(PhoneCheckCodeParams.builder()
        .phoneNumber("+14155552671")
        .code("123456")
        .build());
System.out.println(result);

<?php

require 'vendor/autoload.php';

use Didit\DiditClient;

// Reads DIDIT_API_KEY.
$didit = new DiditClient();

$result = $didit->phone->checkCode([
    'phone_number' => '+14155552671',
    'code' => '123456',
]);
print_r($result->toArray());

using System;
using System.Text.Json;
using Didit;

// Reads DIDIT_API_KEY.
using var client = new DiditClient();

var result = await client.Phone.CheckCodeAsync(new PhoneCheckCodeParams
{
    PhoneNumber = "+14155552671",
    Code = "123456",
});
Console.WriteLine(JsonSerializer.Serialize(result));

{
  "request_id": "e39cb057-92fc-4b59-b84e-02fec29a0f24",
  "status": "Approved",
  "message": "The verification code is correct.",
  "phone": {
    "status": "Approved",
    "phone_number_prefix": "+1",
    "phone_number": "4155552671",
    "full_number": "+14155552671",
    "country_code": "US",
    "country_name": "United States",
    "carrier": {
      "name": "AT&T",
      "type": "mobile"
    },
    "is_disposable": false,
    "is_virtual": false,
    "verification_method": "whatsapp",
    "verification_attempts": 1,
    "verified_at": "2026-06-12T01:24:47.311323Z",
    "warnings": [],
    "lifecycle": [
      {
        "type": "PHONE_VERIFICATION_MESSAGE_SENT",
        "timestamp": "2026-06-12T01:23:39.580554+00:00",
        "details": {
          "status": "Success",
          "reason": null,
          "channel": "whatsapp",
          "actual_channel": "whatsapp"
        },
        "fee": 0.0509
      },
      {
        "type": "PHONE_DELIVERY_DELIVERED",
        "timestamp": "2026-06-12T01:23:43.118220+00:00",
        "details": {
          "channel": "whatsapp",
          "status": "delivered"
        },
        "fee": 0
      },
      {
        "type": "VALID_CODE_ENTERED",
        "timestamp": "2026-06-12T01:24:47.311201+00:00",
        "details": {
          "code_tried": "123456",
          "status": "Approved"
        },
        "fee": 0
      },
      {
        "type": "PHONE_VERIFICATION_APPROVED",
        "timestamp": "2026-06-12T01:24:47.384292+00:00",
        "details": null,
        "fee": 0
      }
    ],
    "matches": []
  },
  "vendor_data": "user-1234",
  "metadata": null,
  "created_at": "2026-06-12T01:24:47.401719+00:00"
}

التعامل مع انقطاع مزود الخدمة

إذا كان مزود خدمة الهاتف غير متاح مؤقتاً، تُرجع نقطة النهاية هذه الرمز 502 مع رمز ثابت مقروء آلياً:

{
  "detail": "The phone verification provider is temporarily unavailable.",
  "code": "phone_provider_unavailable"
}

عامل هذه الاستجابة على أنها قابلة لإعادة المحاولة. استخدم تأخيراً قصيراً قبل إعادة المحاولة، واعرض على المستخدم رسالة تفيد بأن الخدمة غير متاحة مؤقتاً، بدلاً من أن تطلب منه تغيير رقم هاتف صالح أو رمز صالح.

إضافة ذكاء الهاتف

اضبط enable_enrichment على true لتشغيل ذكاء الهاتف على الرقم أيضاً، فتحصل على درجة مخاطر، ونوع الخط، وما إذا كان الرقم قد نُقل مؤخراً إلى شركة اتصالات أخرى، إضافةً إلى مؤشر ثقة. تُحتسب الإضافة بسعر $0.05 لكل طلب وفق السعر المعلن، وتُضاف إلى سعر عملية التحقق نفسها. يُرجع الطلب الرمز 403 إذا كان رصيدك لا يغطي تكلفتها. تحدد أربعة حقول ما تفعله الإشارات. كل حقل إما NO_ACTION (وهي القيمة الافتراضية) أو DECLINE، ولا يسري أي منها إلا إذا كان enable_enrichment مساوياً لـ true.

الحقل	يُرفض عندما
`phone_intelligence_score_action`	درجة المخاطر أعلى من الحد.
`phone_type_risk_action`	الرقم من نوع خط عالي المخاطر.
`recent_port_action`	الرقم نُقل إلى شركة اتصالات أخرى مؤخراً.
`low_phone_trust_action`	مؤشر الثقة أقل من الحد أو يساويه.

مع NO_ACTION، تُعاد الإشارة في phone.phone_intelligence، فيمكنك تطبيق قاعدتك الخاصة.

التفويضات

x-api-key

string

header

مطلوب

مفتاح API الخاص بتطبيقك، من Developers -> API keys في Business Console. يمتلك المفتاح الأساسي وصولاً كاملاً. يمكن تحديد نطاق المفتاح المسمى: لا شيء، أو قراءة، أو كتابة لكل مورد، ومحدوداً ببعض مسارات العمل أو بالجلسات المقبولة، وبقائمة من عناوين IP، وبتاريخ انتهاء الصلاحية. يشير 401 إلى أن المفتاح غير صحيح أو ملغى أو منتهي الصلاحية؛ ويشير 403 إلى أنه لم يتم إرسال أي مفتاح، أو أن المفتاح ليس لديه حق الوصول إلى هذا المورد أو الإجراء، أو أن الطلب جاء من عنوان خارج قائمة عناوين IP الخاصة به؛ ويشير 404 في مسار جلسة إلى أن الجلسة خارج مسارات العمل أو الحالات الخاصة بالمفتاح. يتلقى المفتاح الذي لا يمتلك حق الوصول إلى الوسائط عناوين URL للصور ومقاطع الفيديو وملفات PDF كـ null، ويتلقى المفتاح الذي لا يمتلك إذن كتابة للجلسات روابط الجلسة وtoken كـ null. راجع https://docs.didit.me/console/api-keys.

الجسم

application/json

phone_number

string

مطلوب

رقم الهاتف نفسه المستخدم في استدعاء POST /v3/phone/send/ المطابق، بتنسيق E.164. هذا ما يربط التحقق بعملية الإرسال.

Maximum string length: 20

مثال:

"+14155552671"

code

string

مطلوب

رمز OTP الذي استلمه المستخدم النهائي. يجب أن يتكون من 4 إلى 8 أرقام — أي شيء آخر يُرجع 400 دون استهلاك أي محاولة. الرمز المكتمل التنسيق ولكن الخاطئ يُرجع 200 مع status: "Failed" ويستهلك إحدى المحاولات الثلاث.

Required string length: 4 - 8

Pattern: ^[0-9]{4,8}$

مثال:

"123456"

duplicated_phone_number_action

enum<string>

افتراضي:NO_ACTION

الإجراء المتخذ عند استخدام نفس الرقم مسبقاً من قبل مستخدم مختلف (بيانات vendor_data مختلفة) لتطبيقك. يؤدي خيار DECLINE إلى تحويل status النهائي إلى Declined؛ ويسجل خيار NO_ACTION المخاطر في phone.warnings ويملأ phone.matches.

الخيارات المتاحة:

NO_ACTION,

DECLINE

disposable_number_action

enum<string>

افتراضي:NO_ACTION

الإجراء المتبع عندما يشير فحص شركة الاتصالات إلى أن الرقم مؤقت أو للاستخدام الواحد (phone.is_disposable). يحول DECLINE القيمة النهائية لـ status إلى Declined؛ ويسجل NO_ACTION الخطر في phone.warnings.

الخيارات المتاحة:

NO_ACTION,

DECLINE

voip_number_action

enum<string>

افتراضي:NO_ACTION

الإجراء المتبع عندما يبلغ فحص شركة الاتصالات عن نوع خط افتراضي — voip أو isp أو vpn (phone.is_virtual). يحول DECLINE القيمة النهائية لـ status إلى Declined؛ ويسجل NO_ACTION الخطر في phone.warnings.

الخيارات المتاحة:

NO_ACTION,

DECLINE

enable_enrichment

boolean

افتراضي:false

عندما تكون true، يتم أيضاً تشغيل استخبارات الهاتف على الرقم: درجة المخاطر، ونوع الخط، وما إذا كان قد تم نقله مؤخراً، ومؤشر الثقة. تتم الفوترة كوحدة phone_intelligence_api واحدة لكل طلب ($0.05 بسعر القائمة) بالإضافة إلى سعر endpoint هذا نفسه. يُرجع الطلب 403 عندما لا يكفي رصيدك لتغطية التكلفة.

مثال:

false

phone_intelligence_score_action

enum<string>

افتراضي:NO_ACTION

الإجراء عند تجاوز درجة مخاطر معلومات الهاتف للحد المعين. القيمة DECLINE تحول الـ status النهائي إلى Declined؛ والقيمة NO_ACTION تسجل الإشارة دون رفض. يسري مفعوله فقط عندما يكون enable_enrichment مضبوطاً على true.

الخيارات المتاحة:

NO_ACTION,

DECLINE

phone_type_risk_action

enum<string>

افتراضي:NO_ACTION

الإجراء عندما يكون الرقم من نوع خط عالي المخاطر. القيمة DECLINE تحول الـ status النهائي إلى Declined؛ والقيمة NO_ACTION تسجل الإشارة دون رفض. يسري مفعوله فقط عندما يكون enable_enrichment مضبوطاً على true.

الخيارات المتاحة:

NO_ACTION,

DECLINE

recent_port_action

enum<string>

افتراضي:NO_ACTION

الإجراء عند نقل الرقم إلى مشغل شبكة آخر مؤخراً. القيمة DECLINE تحول الـ status النهائي إلى Declined؛ والقيمة NO_ACTION تسجل الإشارة دون رفض. يسري مفعوله فقط عندما يكون enable_enrichment مضبوطاً على true.

الخيارات المتاحة:

NO_ACTION,

DECLINE

low_phone_trust_action

enum<string>

افتراضي:NO_ACTION

الإجراء عندما يكون مؤشر الثقة لمعلومات الهاتف مساوياً للحد المعين أو أقل منه. القيمة DECLINE تحول الـ status النهائي إلى Declined؛ والقيمة NO_ACTION تسجل الإشارة دون رفض. يسري مفعوله فقط عندما يكون enable_enrichment مضبوطاً على true.

الخيارات المتاحة:

NO_ACTION,

DECLINE

عند التعيين على true، يتم أيضاً البحث عن الأثر الرقمي الاجتماعي للرقم - منصات المراسلة والمنصات الاجتماعية والتجارة الإلكترونية والمهنية المسجل عليها. يُفوتر كوحدة phone_social واحدة لكل طلب بالإضافة إلى سعر هذا الـ endpoint نفسه.

مثال:

true

الإجراء عندما يجد فحص الأثر الاجتماعي أن الرقم غير مسجل على أي من المنصات التي يغطيها. يُقبل فقط NO_ACTION وDECLINE في هذا الـ endpoint؛ يتوفر REVIEW في مفتاح تهيئة سير العمل الذي يحمل نفس الاسم.

الخيارات المتاحة:

NO_ACTION,

DECLINE

الاستجابة

اكتمل التحقق — تُرجع الرموز الخاطئة وعمليات التحقق المفقودة أيضاً الرمز 200؛ تحقّق من status، وليس رمز HTTP. يتم ملء phone فقط في النتائج النهائية (Approved/Declined)، ويكون null عند Failed، وغير موجود عند Expired or Not Found.

request_id

string<uuid>

عند Approved/Declined: معرّف الجلسة لعملية التحقق المتطابقة — مطابق لـ request_id المُرجع بواسطة POST /v3/phone/send/. عند Failed وExpired or Not Found: معرّف UUID عشوائي لمرة واحدة لا يمكن البحث عنه لاحقاً.

status

enum<string>

Approved — رمز صحيح، دون وجود مخاطر تؤدي إلى الرفض. Declined — نهائية: تطابقت مخاطر تؤدي إلى الرفض أو استُنفد الحد المسموح به من المحاولات (3). Failed — رمز خاطئ، مع بقاء محاولات متبقية. Expired or Not Found — لا توجد عملية تحقق معلقة لهذا الرقم خلال آخر 5 دقائق.

الخيارات المتاحة:

Approved,

Declined,

Failed,

Expired or Not Found

message

string

تفسير سهل القراءة للنتيجة، بما في ذلك عدد المحاولات المتبقية بعد إدخال رمز خاطئ.

phone

object | null

تقرير الهاتف الكامل. يتواجد (غير فارغ non-null) فقط في النتائج النهائية (Approved/Declined)؛ ويكون null في حالة Failed وغير موجود في حالة Expired or Not Found.

Show child attributes

vendor_data

string | null

vendor_data لجلسة التحقق المطابقة. وتكون null عند Expired or Not Found.

metadata

object | null

metadata لجلسة التحقق المتطابقة. null عند Expired or Not Found.

created_at

string<date-time>

الطابع الزمني لاستجابة هذا الفحص.

آخر تعديل في ٧ نوفمبر ٢٠٢٦

​التعامل مع انقطاع مزود الخدمة

​إضافة ذكاء الهاتف

التفويضات

الجسم

الاستجابة

التعامل مع انقطاع مزود الخدمة

إضافة ذكاء الهاتف