الانتقال إلى المحتوى الرئيسي
POST
curl
تؤكد واجهة Address Validation API من Didit أن العنوان البريدي موجود، وتعيده موحَّدًا مع أسطر التوصيل ومكوناته وإحداثياته. استخدم POST /v3/address-validation/ عندما يملك الخادم الخلفي لديك عنوانًا ويحتاج إلى معرفة ما إذا كان موجودًا، وبأي شكل موحَّد. يؤكد Address Validation العنوان فقط. ولا يربط العنوان بأي شخص أبدًا: فالنتيجة verified تعني أن المكان موجود، لا أن أحدًا يقيم فيه.

إرسال العنوان

أرسله في سطر واحد ضمن address، أو كحقول مُهيكلة: address_line_1 وعند توفرها address_line_2 وcity وregion وpostal_code. لا ترسل الشكلين معًا في الطلب نفسه أبدًا. الحقل country مطلوب دائمًا، ويكون رمز ISO 3166-1 alpha-2 أو alpha-3.

تفسير الاستجابة

  • address_validation.status هي الإجابة التي تبني عليها:
    • verified: تم تأكيد العنوان حتى مستوى المبنى (أو الشقة أو صندوق البريد).
    • partially_verified: تم تأكيده حتى مستوى الشارع فقط، أو حتى أدق مستوى تحتفظ به البيانات المرجعية البريدية لذلك المكان.
    • not_verified: لم يتطابق إلا المنطقة أو المدينة، أو لم يتطابق شيء.
    • unavailable: تعذّر تشغيل التحقق. أعد المحاولة لاحقًا.
  • address_validation.verification_level هو أدق مستوى تمت مطابقته: administrative_area أو locality أو thoroughfare أو premise أو delivery_point.
  • address_validation.address وaddress_validation.formatted_address يحملان العنوان الموحَّد، مكتوبًا بالطريقة التي تكتب بها الدولة عناوينها.
  • address_validation.latitude وaddress_validation.longitude يحددان موقع العنوان المتطابق.
  • يُعرّف request_id الطلب. لا تُنشأ أي جلسة، ولا تُعاد النتيجة إلا في هذه الاستجابة، لذا احفظ ما تحتاجه.
يكون رمز HTTP هو 200 لكل طلب مكتمل، بما في ذلك unavailable.

Address Validation داخل سير العمل

الفحص نفسه إضافة لخطوتي سير العمل: التحقق من الهوية وإثبات العنوان. فعّل address_validation_enabled في إعدادات الخطوة، وسيُتحقَّق من العنوان الذي قدّمه الشخص (المطبوع على وثيقة الهوية، أو على إثبات العنوان) مرة واحدة بعد قراءة الملف الذي رفعه. النتيجة هي الكائن address_validation ضمن إدخال تلك الخطوة في قرار الجلسة (id_verifications[] أو poa_verifications[]). العنوان الذي تكون نتيجته partially_verified أو not_verified يُطلق التحذير ADDRESS_NOT_VERIFIED، وإجراؤه هو address_not_verified_action في إعدادات الخطوة (القيمة الافتراضية NO_ACTION، وهي تكتفي بتسجيل التحذير). التحقق الذي تكون نتيجته unavailable لا يطلق هذا التحذير ولا يغيّر التحقق أبدًا.

سلوك البيئة التجريبية

تتحقق مفاتيح البيئة التجريبية من الطلب، وتعيد دائمًا نتيجة verified حتمية تُكرر العنوان الذي أرسلته. ولا تستهلك أرصدة.

الفوترة

يكلّف كل استدعاء لـ Address Validation API مبلغ $0.10 لكل عنوان يُتحقق منه. النتيجة `unavailable` لا تُحتسب. وفي سير العمل تكلّف الإضافة $0.10 لكل عنوان تحققت منه الخطوة.

التفويضات

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

عنوان واحد: في سطر واحد (address) أو كحقول مهيكلة تحتوي على الأقل على address_line_1، ولا يمكن استخدام كليهما معاً مطلقاً.

country
string
مطلوب

رمز دولة العنوان وفق المعيار ISO 3166-1 alpha-2 أو alpha-3.

Maximum string length: 3
مثال:

"US"

address
string

العنوان بالكامل في سطر واحد.

Maximum string length: 500
مثال:

"Paseo de la Castellana 259, 28046 Madrid"

address_line_1
string

الشارع والرقم.

Maximum string length: 255
مثال:

"1600 Amphitheatre Pkwy"

address_line_2
string

شقة، جناح، طابق أو مبنى.

Maximum string length: 255
city
string

المدينة أو المنطقة.

Maximum string length: 128
مثال:

"Mountain View"

region
string

الولاية أو المقاطعة أو المنطقة.

Maximum string length: 128
مثال:

"CA"

postal_code
string
Maximum string length: 32
مثال:

"94043"

الاستجابة

اكتمل التحقق. اقرأ address_validation.status؛ يكون كود HTTP دائماً 200 للطلب المكتمل.

request_id
string<uuid>
مطلوب

معرّف هذا الطلب؛ اذكره لفريق الدعم. لم يتم إنشاء أي جلسة.

address_validation
object
مطلوب

نتيجة عملية تحقق واحدة من العنوان: ما إذا كان العنوان موجوداً، وشكله المعياري. يؤكد العنوان فقط؛ ولا يربط العنوان بشخص على الإطلاق.

created_at
string<date-time>
مطلوب
آخر تعديل في ٧ نوفمبر ٢٠٢٦