> ## 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.

# واجهة API للتحقق من العناوين وتوحيد صيغتها

> POST /v3/address-validation/ من Didit يتحقق من وجود العنوان ويعيد صيغته الموحدة مع الإحداثيات، بإدخال منظم أو سطر واحد، بسعر $0.10 لكل عنوان.

تؤكد واجهة 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 لكل عنوان تحققت منه الخطوة.


## OpenAPI

````yaml ar/openapi-25.json POST /v3/address-validation/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: API التحقق من الهوية. قم بالمصادقة باستخدام الرأس x-api-key.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/address-validation/:
    post:
      tags:
        - Standalone APIs
      summary: التحقق من عنوان
      description: >-
        تأكيد وجود العنوان والحصول عليه مُوحَّداً: خطوط التسليم ومكوناته
        وإحداثياته. يؤكد هذا العنوان فقط؛ ولا يربط العنوان بأي شخص مطلقاً.


        **الطلب.** أرسل العنوان في سطر واحد (`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` (تعذر إجراء التحقق). رمز حالة HTTP هو
        `200` لكل طلب مكتمل، بما في ذلك `unavailable`؛ أعد محاولة النتيجة
        `unavailable` لاحقاً.


        **الفوترة.** تبلغ تكلفة الاستدعاء المباشر $0.10 لكل عنوان تم التحقق منه.
        لا يتم فرض رسوم على النتيجة `unavailable`. لا يتم تخزين أي شيء باستثناء
        سجل الاستخدام: لا يتم إنشاء أي جلسة ويتم إرجاع النتيجة في هذه الاستجابة
        فقط.


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


        **المصادقة.** أرسل مفتاح API الخاص بتطبيقك في `x-api-key`. تُرجع بيانات
        الاعتماد المفقودة أو غير الصالحة الرمز `403` - لا تُرجع واجهة API هذه
        الرمز `401` مطلقاً.


        **حد المعدل.** ميزانية كتابة مشتركة تبلغ 300 طلب في الدقيقة لكل مفتاح
        API عبر endpoints الخاصة بـ POST/PATCH/DELETE (عمليات إنشاء المعاملات
        واستيعاب الأحداث لها ميزانية منفصلة تبلغ 600).
      operationId: post_v3_address_validation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddressValidationRequest'
            examples:
              Structured:
                summary: حقول العنوان المهيكل
                value:
                  address_line_1: 1600 Amphitheatre Pkwy
                  city: Mountain View
                  region: CA
                  postal_code: '94043'
                  country: US
              One line:
                summary: العنوان بالكامل في سطر واحد
                value:
                  address: Paseo de la Castellana 259, 28046 Madrid
                  country: ES
      responses:
        '200':
          description: >-
            اكتمل التحقق. اقرأ `address_validation.status`؛ يكون كود HTTP دائماً
            `200` للطلب المكتمل.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressValidationResponse'
              examples:
                Verified:
                  summary: عنوان حقيقي، مؤكَّد حتى مستوى المبنى
                  value:
                    request_id: 6f7d2c1e-1c5a-4a1e-9b8f-2a1f0f4b9c3d
                    address_validation:
                      status: verified
                      verification_level: premise
                      address:
                        address_line_1: 1600 Amphitheatre Pkwy
                        address_line_2: null
                        city: Mountain View
                        region: CA
                        postal_code: 94043-1351
                        country: US
                      formatted_address: 1600 Amphitheatre Pkwy, Mountain View CA 94043-1351
                      latitude: 37.422022
                      longitude: -122.08429
                    created_at: '2026-10-27T11:20:00.000000+00:00'
                Not verified:
                  summary: 'شارع مختلق: تطابقت المدينة فقط'
                  value:
                    request_id: 0b9e3f4a-6c2d-4e8b-a1f7-5d3c2b1a0e9f
                    address_validation:
                      status: not_verified
                      verification_level: locality
                      address:
                        address_line_1: Calle Inventada Que No Existe 99999 28046
                        address_line_2: null
                        city: Madrid
                        region: Madrid
                        postal_code: null
                        country: ES
                      formatted_address: >-
                        Calle Inventada Que No Existe 99999 28046, Madrid,
                        MADRID, SPAIN
                      latitude: 40.42603054
                      longitude: -3.68645331
                    created_at: '2026-10-27T11:21:00.000000+00:00'
                Unavailable:
                  summary: تعذر تشغيل التحقق؛ لم يتم احتساب رسوم
                  value:
                    request_id: 3c1b2a0f-9e8d-4c7b-b6a5-1f0e9d8c7b6a
                    address_validation:
                      status: unavailable
                      verification_level: null
                      address: null
                      formatted_address: null
                      latitude: null
                      longitude: null
                    created_at: '2026-10-27T11:22:00.000000+00:00'
        '400':
          $ref: '#/components/responses/AddressValidationValidationError'
        '403':
          $ref: '#/components/responses/AddressValidationPermissionDenied'
        '429':
          $ref: '#/components/responses/RateLimitedWrite'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: |-
            curl -X POST https://verification.didit.me/v3/address-validation/ \
              -H 'x-api-key: YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              -d '{
                "address_line_1": "1600 Amphitheatre Pkwy",
                "city": "Mountain View",
                "region": "CA",
                "postal_code": "94043",
                "country": "US"
              }'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.address_validation.validate(
                address_line_1="1600 Amphitheatre Pkwy",
                city="Mountain View",
                region="CA",
                postal_code="94043",
                country="US",
            )
            print(result)
        - lang: javascript
          label: Node.js
          source: |-
            import Didit from "@didit-protocol/sdk-node";

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

            const result = await didit.addressValidation.validate({
              address_line_1: "1600 Amphitheatre Pkwy",
              city: "Mountain View",
              region: "CA",
              postal_code: "94043",
              country: "US",
            });
            console.log(result);
        - lang: java
          label: Java
          source: >-
            import me.didit.Didit;

            import me.didit.types.AddressValidationRequest;


            // Reads DIDIT_API_KEY.

            Didit client = new Didit();


            var result =
            client.addressValidation().validate(AddressValidationRequest.builder()
                    .addressLine1("1600 Amphitheatre Pkwy")
                    .city("Mountain View")
                    .region("CA")
                    .postalCode("94043")
                    .country("US")
                    .build());
            System.out.println(result);
        - lang: php
          label: PHP
          source: |-
            <?php

            require 'vendor/autoload.php';

            use Didit\DiditClient;

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

            $result = $didit->addressValidation->validate([
                'address_line_1' => '1600 Amphitheatre Pkwy',
                'city' => 'Mountain View',
                'region' => 'CA',
                'postal_code' => '94043',
                'country' => 'US',
            ]);
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

            # Reads DIDIT_API_KEY.
            didit = Didit::Client.new

            result = didit.address_validation.validate(
              address_line_1: "1600 Amphitheatre Pkwy",
              city: "Mountain View",
              region: "CA",
              postal_code: "94043",
              country: "US"
            )
            puts result.to_h
        - lang: csharp
          label: .NET
          source: >-
            using System;

            using System.Text.Json;

            using Didit;


            // Reads DIDIT_API_KEY.

            using var client = new DiditClient();


            var result = await client.AddressValidation.ValidateAsync(new
            AddressValidationRequest

            {
                AddressLine1 = "1600 Amphitheatre Pkwy",
                City = "Mountain View",
                Region = "CA",
                PostalCode = "94043",
                Country = "US",
            });

            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    AddressValidationRequest:
      type: object
      required:
        - country
      description: >-
        عنوان واحد: في سطر واحد (`address`) أو كحقول مهيكلة تحتوي على الأقل على
        `address_line_1`، ولا يمكن استخدام كليهما معاً مطلقاً.
      properties:
        address:
          type: string
          maxLength: 500
          description: العنوان بالكامل في سطر واحد.
          example: Paseo de la Castellana 259, 28046 Madrid
        address_line_1:
          type: string
          maxLength: 255
          description: الشارع والرقم.
          example: 1600 Amphitheatre Pkwy
        address_line_2:
          type: string
          maxLength: 255
          description: شقة، جناح، طابق أو مبنى.
        city:
          type: string
          maxLength: 128
          description: المدينة أو المنطقة.
          example: Mountain View
        region:
          type: string
          maxLength: 128
          description: الولاية أو المقاطعة أو المنطقة.
          example: CA
        postal_code:
          type: string
          maxLength: 32
          example: '94043'
        country:
          type: string
          maxLength: 3
          description: رمز دولة العنوان وفق المعيار ISO 3166-1 alpha-2 أو alpha-3.
          example: US
    AddressValidationResponse:
      type: object
      required:
        - request_id
        - address_validation
        - created_at
      properties:
        request_id:
          type: string
          format: uuid
          description: معرّف هذا الطلب؛ اذكره لفريق الدعم. لم يتم إنشاء أي جلسة.
        address_validation:
          $ref: '#/components/schemas/AddressValidationResult'
        created_at:
          type: string
          format: date-time
    AddressValidationResult:
      type: object
      description: >-
        نتيجة عملية تحقق واحدة من العنوان: ما إذا كان العنوان موجوداً، وشكله
        المعياري. يؤكد العنوان فقط؛ ولا يربط العنوان بشخص على الإطلاق.
      required:
        - status
        - verification_level
        - address
        - formatted_address
        - latitude
        - longitude
      properties:
        status:
          type: string
          enum:
            - verified
            - partially_verified
            - not_verified
            - unavailable
          description: >-
            `verified`: تم تأكيد العنوان وصولاً إلى المبنى (أو الشقة أو صندوق
            البريد). `partially_verified`: تم تأكيده فقط حتى مستوى الشارع، أو
            إلى المستوى الأكثر دقة الذي تحتفظ به البيانات المرجعية البريدية لذلك
            المكان. `not_verified`: تطابقت المنطقة أو المدينة فقط، أو لم يتطابق
            أي شيء. `unavailable`: تعذر تشغيل التحقق (على سبيل المثال لم تستجب
            الخدمة المرجعية)؛ لا يتم احتساب أي رسوم عليه ولا يؤثر أبداً على
            عملية التحقق.
        verification_level:
          type: string
          nullable: true
          enum:
            - administrative_area
            - locality
            - thoroughfare
            - premise
            - delivery_point
            - null
          description: >-
            المستوى الأكثر دقة الذي طابقه العنوان. يكون `null` عندما لا يتطابق
            أي شيء أو عندما تكون `status` هي `unavailable`.
        address:
          type: object
          nullable: true
          description: العنوان الموحّد. يكون `null` عندما تكون `status` هي `unavailable`.
          properties:
            address_line_1:
              type: string
              nullable: true
              description: سطر التسليم الأول، مكتوباً بالطريقة التي تكتبها الدولة.
              example: 1600 Amphitheatre Pkwy
            address_line_2:
              type: string
              nullable: true
              description: سطر التسليم الثاني (شقة أو مبنى أو حي)، عندما يتضمن العنوان ذلك.
            city:
              type: string
              nullable: true
              example: Mountain View
            region:
              type: string
              nullable: true
              description: الولاية أو المقاطعة أو المنطقة.
              example: CA
            postal_code:
              type: string
              nullable: true
              example: 94043-1351
            country:
              type: string
              nullable: true
              description: رمز الدولة وفقاً لـ ISO 3166-1 alpha-2.
              example: US
        formatted_address:
          type: string
          nullable: true
          description: العنوان الموحّد في سطر واحد.
          example: 1600 Amphitheatre Pkwy, Mountain View CA 94043-1351
        latitude:
          type: number
          nullable: true
          example: 37.422022
        longitude:
          type: number
          nullable: true
          example: -122.08429
  responses:
    AddressValidationValidationError:
      description: >-
        نص الطلب غير صالح: `country` مفقود أو غير معروف، أو لا يوجد عنوان، أو تم
        توفير كل من `address` والحقول المنظمة معاً.
      content:
        application/json:
          examples:
            Unknown country:
              value:
                country:
                  - >-
                    Use an ISO 3166-1 alpha-2 or alpha-3 country code, e.g. 'US'
                    or 'USA'.
            No address:
              value:
                address:
                  - >-
                    Send the address: 'address' on one line, or the structured
                    fields with 'address_line_1'.
            Both shapes:
              value:
                address:
                  - >-
                    Send either 'address' or the structured fields
                    (address_line_1, ...), not both.
    AddressValidationPermissionDenied:
      description: >-
        مفتاح API مفقود أو غير صالح، أو يفتقر المفتاح المحدد النطاق إلى وصول
        الكتابة لـ `sessions`، أو لا تستطيع المؤسسة تغطية التحقق. لا تُرجع هذه
        API أبداً الرمز `401`.
      content:
        application/json:
          examples:
            Missing or invalid API key:
              value:
                detail: You do not have permission to perform this action.
            Not enough credits:
              value:
                detail: >-
                  You don't have enough credits to perform this request. Please
                  top up at https://business.didit.me
                code: insufficient_credits
    RateLimitedWrite:
      description: >-
        تم تجاوز حد الكتابة المشترك البالغ 300 طلب في الدقيقة لكل مفتاح API.
        التزم بالمدة المحددة في `Retry-After` قبل إعادة المحاولة.
      content:
        application/json:
          schema:
            type: object
            required:
              - detail
            properties:
              detail:
                type: string
          example:
            detail: >-
              Write request rate limit exceeded. You can make up to 300 requests
              per minute.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        مفتاح API الخاص بتطبيقك، من Developers -> API keys في Business Console.
        يمتلك المفتاح الأساسي وصولاً كاملاً. يمكن تحديد نطاق المفتاح المسمى: لا
        شيء، أو قراءة، أو كتابة لكل مورد، ومحدوداً ببعض مسارات العمل أو بالجلسات
        المقبولة، وبقائمة من عناوين IP، وبتاريخ انتهاء الصلاحية. يشير 401 إلى أن
        المفتاح غير صحيح أو ملغى أو منتهي الصلاحية؛ ويشير 403 إلى أنه لم يتم
        إرسال أي مفتاح، أو أن المفتاح ليس لديه حق الوصول إلى هذا المورد أو
        الإجراء، أو أن الطلب جاء من عنوان خارج قائمة عناوين IP الخاصة به؛ ويشير
        404 في مسار جلسة إلى أن الجلسة خارج مسارات العمل أو الحالات الخاصة
        بالمفتاح. يتلقى المفتاح الذي لا يمتلك حق الوصول إلى الوسائط عناوين URL
        للصور ومقاطع الفيديو وملفات PDF كـ null، ويتلقى المفتاح الذي لا يمتلك
        إذن كتابة للجلسات روابط الجلسة وtoken كـ null. راجع
        https://docs.didit.me/console/api-keys.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.