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

# تقرير إثبات العنوان: الحقول المستخرجة

> حلل تقرير إثبات العنوان من Didit: العنوان المستخرج، نوع المستند، جهة الإصدار، التواريخ، درجات تطابق الاسم، وأدلة التلاعب والتحذيرات.

## نظرة عامة

يقبل التحقق من إثبات العنوان (POA) ملف PDF واحداً أو صورة واحدة (TIFF، JPG، JPEG، PNG، WEBP، ويمكن ضغطه اختيارياً بصيغة ZIP) بحجم يصل إلى 15 ميجابايت، ويجري تصنيفاً لنوع المستند، واستخراجاً قائماً على نماذج LLM، وتحليلاً جنائياً لملفات PDF/EXIF، ويعيد:

* **العنوان المستخرج** — بصيغته الخام والمُهيكلة على حد سواء (`street_1`، `city`، `region`، `postal_code`، وخط العرض/خط الطول).
* **بيانات وصفية للمستند** — حجم الملف، ونوع المحتوى، وتواريخ الإنشاء والتعديل، وتواريخ EXIF، ومعلومات التوقيع، وأي أدلة على التلاعب عبر الطبقات المتراكبة (overlay) من التحليل الجنائي لملف PDF.
* **درجات تطابق الاسم** مقارنة بمستند الهوية الذي تم التحقق منه ومقارنة بالتفاصيل المتوقعة المقدمة عند إنشاء الجلسة.
* **حقول إضافية متعلقة بالبنك** (رقم الحساب، IBAN، رمز الفرز، رقم التوجيه، SWIFT/BIC، والفرع) عندما يكون المستند كشف حساب بنكي.

![Didit proof of address report screenshot showing extracted address fields and document type](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/proof-of-address-report.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=099d1bd6cf0c215cc93c3a504b8aa9ee)

> [!NOTE]
>
> يتضمن استخراج إثبات العنوان (POA) قراءة النصوص غير المهيكلة، مما يضيف زمن استجابة يتراوح بين **5 إلى 15 ثانية** لكل مستند. ولا تنطلق أحداث webhook إلا عند اكتمال خطوة سير العمل بأكملها — لا تقم بإرسال طلبات متكررة (الاستطلاع) إلى endpoint القرار بمعدل أسرع من كل 5 ثوانٍ خلال هذه الفترة.

## أين يظهر في استجابات API

يعيد endpoint القرار إثبات العنوان (POA) كمصفوفة بصيغة الجمع **`poa_verifications[]`** في `GET /v3/session/{sessionId}/decision/`. يمثل كل إدخال تنفيذاً واحداً لعقدة POA في سير العمل الخاص بك؛ والجلسات التي تحتوي على عدة خطوات POA (مثل كشف حساب بنكي + فاتورة خدمات) تُنتج إدخالاً واحداً لكل عملية تنفيذ مع `node_id` الخاص به.

```text theme={null}
GET /v3/session/{sessionId}/decision/
  ──▶ { "poa_verifications": [ { node_id, status, document_type, poa_address, … }, … ] }
```

الشكل الموضح أدناه يطابق المخطط القياسي — انظر [نماذج البيانات](https://docs.didit.me/ar/reference/data-models.md#إثبات-العنوان).

## المخطط

انظر [إثبات العنوان في مرجع نماذج البيانات](https://docs.didit.me/ar/reference/data-models.md#إثبات-العنوان) للاطلاع على المخطط القياسي.

```typescript theme={null}
interface POAV3 {
  status: 'Not Finished' | 'Approved' | 'Declined' | 'In Review';
  node_id: string | null;

  issuing_state: string | null;         // ISO 3166-1 alpha-3
  document_type:                        // never null — falls back to 'UNKNOWN'
    | 'UTILITY_BILL'
    | 'BANK_STATEMENT'
    | 'GOVERNMENT_ISSUED_DOCUMENT'
    | 'OTHER_POA_DOCUMENT'
    | 'UNKNOWN';
  document_subtype: string;             // e.g. 'ELECTRICITY_BILL', 'ACCOUNT_STATEMENT';
                                        // never null — falls back to 'UNKNOWN'
  issuer: string | null;
  issue_date: string | null;            // YYYY-MM-DD
  expiration_date: string | null;       // YYYY-MM-DD when present

  // Extracted address
  poa_address: string | null;           // raw, single-line
  poa_formatted_address: string | null; // geocoded/formatted
  poa_parsed_address: {
    address_type?: string;
    street_1?: string;
    street_2?: string;
    city?: string;
    region?: string;
    postal_code?: string;
    country?: string;                   // ISO 3166-1 alpha-2
    raw_results?: object;
    document_location?: { latitude: number; longitude: number };
  } | null;

  document_file: string | null;         // presigned URL, expires after ~4 hours
  document_language: string | null;     // ISO 639-1, e.g. 'en'
  name_on_document: string | null;

  // Expected details (when supplied at session creation)
  expected_details_address: string | null;
  expected_details_formatted_address: string | null;
  expected_details_parsed_address: object | null;

  // Match scores (float, 0-100)
  name_match_score_expected_details: number | null;
  name_match_score_id_verification: number | null;

  // PDF + image forensics
  document_metadata: {
    file_size: number | null;
    content_type: string | null;
    creation_date: string | null;
    modified_date: string | null;
    creator: string | null;
    producer: string | null;
    software: string | null;
    encryption: string | null;
    is_signed: boolean | null;
    is_tampered: boolean | null;
    signature_info: object | null;
    exif_original_date: string | null;
    exif_digitized_date: string | null;
    processed_by_known_editor: boolean | string | null;
    has_different_creation_mod_date: boolean | null;
    overlay_manipulation: {
      detected: boolean;
      analyzed: boolean;
      signals: string[];                // 'duplicate_font_subset', 'glyph_fragmentation'
      duplicate_font_subsets: object[];
      fragmented_fonts: object[];
      manipulated_regions: {
        page: number;
        x: number;
        y: number;
        width: number;
        height: number;
        page_width: number;
        page_height: number;
      }[];
    } | null;                           // null for non-PDF uploads or when not analyzed
  } | null;

  // Bank-related and custom fields
  extra_fields: {
    bank_account_number: string | null;
    bank_iban: string | null;
    bank_sort_code: string | null;
    bank_routing_number: string | null;
    bank_swift_bic: string | null;
    bank_branch_name: string | null;
    bank_branch_address: string | null;
    document_phone_number: string | null;
    additional_names: string[];
    [customField: string]: unknown;
  };

  extra_files: string[];                // presigned URLs for additional uploaded files

  // QR codes and barcodes
  detected_codes: {
    type: string;                       // 'QR_CODE', 'CODE_128', 'EAN_13', 'DATA_MATRIX', 'PDF_417', …
    page_number: number;                // 1-based
    position: [number, number][] | null;
    x: number | null;
    y: number | null;
    width: number | null;
    height: number | null;
    page_width: number;
    page_height: number;
    raw_payload: string;                // base64, empty string when unavailable
    parsed_payload: unknown | null;      // null when located but undecodable
  }[];

  warnings: Warning[];                  // see Data Models — Warning object
}
```

كل إدخال في `warnings[]` هو [كائن تحذير](https://docs.didit.me/ar/reference/data-models.md#كائن-التحذير): `{ feature, risk, additional_data, log_type, short_description, long_description, node_id }`، مع كون `feature` دائماً `"PROOF_OF_ADDRESS"` لهذا التقرير.

## قيم الحالة

تستخدم `status` تعداد الحالة على مستوى الميزة (`FeatureStatusChoices`).

| القيمة | المعنى |
| - | - |
| `Not Finished` | لم تكتمل عقدة POA بعد لهذه الجلسة (الحالة الافتراضية). |
| `Approved` | تم تحليل المستند بنجاح ولم يؤدِ أي تحذير إلى رفض أو مراجعة. |
| `In Review` | تم ضبط تحذير واحد قابل للتهيئة على الأقل على **المراجعة** في سير العمل الخاص بك (مع عدم وجود أي رفض). |
| `Declined` | انطلق تحذير رفض قطعي (`MISSING_ADDRESS_INFORMATION`، `POA_DOCUMENT_EXPIRED`، `INVALID_DOCUMENT_TYPE`، `UNABLE_TO_VALIDATE_DOCUMENT_AGE`)، أو تم ضبط تحذير قابل للتهيئة على **رفض** في سير العمل الخاص بك. |

يمكن لقواعد الحالة المخصصة التي تم تكوينها على عقدة سير العمل تعديل الحالة المحسوبة بشكل أكبر؛ وتتحد القواعد وفقاً لأسبقية مرفوضة > قيد المراجعة > مقبولة. انظر [تحذيرات إثبات العنوان](https://docs.didit.me/ar/core-technology/proof-of-address/warnings-proof-of-address.md) للاطلاع على مخطط ربط المخاطر بالإجراءات بالكامل، بما في ذلك سلوك إعادة المحاولة الخاص بسير العمل فقط لـ `FUTURE_ISSUE_DATE`.

## أدلة التلاعب بالتراكب في ملفات PDF

عندما يكون المستند المُرسَل ملف PDF، قد يحتوي `document_metadata.overlay_manipulation` على أدلة جنائية رقمية تشير إلى تراكبات نصية مشتبه بها:

* `detected`: `true` عندما يعثر الفحص على أدلة على التلاعب.
* `analyzed`: `true` عندما أمكن تحليل ملف PDF على الإطلاق.
* `analysis_incomplete`: يظهر بالقيمة `true` فقط عندما يتعذر فحص الملف بالكامل. تحتفظ الأجزاء التي أمكن فحصها بالنتائج التي توصل إليها الفحص حيثما أمكن، ويُصدر النظام للمستند `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT`.
* `signals`: الفحوصات التي أطلقت إشارات (`duplicate_font_subset`، `glyph_fragmentation`).
* `manipulated_regions`: مستطيلات بإحداثيات الصفحة تحيط بالنص المشتبه في تعديله. يستخدم كل مستطيل فضاء إحداثيات صفحة PDF (`x`، `y`، `width`، `height`، `page_width`، `page_height`) حتى يتمكن المراجِعون من تمييز المنطقة المتأثرة في معاينة PDF.

يكون الحقل `null` عندما لا يكون المستند ملف PDF، أو عندما يتعذر تحليل ملف PDF. وعندما تكون القيمة `detected=true`، يُصدر النظام أيضاً تحذير `SUSPECTED_DOCUMENT_MANIPULATION` تعكس قيمة الحقل `additional_data` فيه الإشارات والمستطيلات المذكورة أعلاه، ما لم تتوفر إشارة أقوى، وهي التعديل بعد التوقيع الرقمي أو `is_tampered=true`، فتكون لها الأولوية. في هذه الحالة يصف `additional_data` التلاعب بالتوقيع بدلاً من ذلك.

## رموز QR والرموز الشريطية

يتضمن كل تقرير POA حقل `detected_codes`، مغطياً كل صفحة تمت معالجتها. يحتوي كل عنصر على:

| الحقل | الوصف |
| - | - |
| `type` | نوع الترميز المكتشف، مثل `QR_CODE`، `CODE_128`، `EAN_13`، `DATA_MATRIX`، أو `PDF_417` |
| `page_number` | رقم الصفحة بدءاً من 1 |
| `position` | المضلع المكتشف بوحدات بكسل الصفحة المعروضة، أو `null` عند عدم توفر موقع موثوق |
| `x`، `y`، `width`، `height` | المربع المحيط بوحدات بكسل الصفحة المعروضة، أو `null` عند عدم توفر موقع موثوق |
| `page_width`، `page_height` | أبعاد الصفحة المعروضة المستخدمة في الإحداثيات |
| `parsed_payload` | السلسلة النصية المفكوكة أو القيمة المهيكلة، أو `null` عندما يمكن تحديد موقع الرمز فقط |
| `raw_payload` | payload وحدة فك التشفير الخام كسلسلة base64 عند توفرها؛ وإلا تكون سلسلة نصية فارغة |

يكون `detected_codes` مصفوفة فارغة عندما لا يتم العثور على أي رمز مدعوم. ولا تقوم Didit أبداً بتخمين payload: قد تُعاد الرموز التالفة أو غير القابلة للقراءة مع موقعها و`parsed_payload: null`، بينما لا تؤدي حالات الفشل في اكتشاف الرمز إلى فشل التحقق من إثبات العنوان (POA).

## أمثلة

### مقبولة — كشف حساب بنكي

```json theme={null}
{
  "poa_verifications": [
    {
      "status": "Approved",
      "node_id": "feature_poa_1",
      "issuing_state": "USA",
      "document_type": "BANK_STATEMENT",
      "document_subtype": "ACCOUNT_STATEMENT",
      "issuer": "National Bank",
      "issue_date": "2026-04-15",
      "expiration_date": null,
      "document_language": "en",
      "name_on_document": "John A. Smith",
      "poa_address": "123 Main St, Apartment 4B, New York, NY 10001",
      "poa_formatted_address": "123 Main St, Apartment 4B, New York, NY 10001, USA",
      "poa_parsed_address": {
        "address_type": "Street",
        "street_1": "123 Main St",
        "street_2": "Apartment 4B",
        "city": "New York",
        "region": "NY",
        "postal_code": "10001",
        "country": "US",
        "document_location": { "latitude": 40.7128, "longitude": -74.0060 }
      },
      "document_file": "https://<media-host>/.../poa.pdf?X-Amz-Expires=14400",
      "document_metadata": {
        "file_size": 246810,
        "content_type": "application/pdf",
        "creation_date": "2026-04-15",
        "modified_date": "2026-04-15",
        "creator": "PDFKit",
        "producer": "Quartz",
        "software": null,
        "encryption": null,
        "is_signed": false,
        "is_tampered": false,
        "signature_info": null,
        "exif_original_date": null,
        "exif_digitized_date": null,
        "processed_by_known_editor": false,
        "has_different_creation_mod_date": false,
        "overlay_manipulation": null
      },
      "name_match_score_expected_details": 100,
      "name_match_score_id_verification": 98,
      "expected_details_address": null,
      "expected_details_formatted_address": null,
      "expected_details_parsed_address": null,
      "extra_fields": {
        "bank_account_number": "****1234",
        "bank_iban": null,
        "bank_sort_code": null,
        "bank_routing_number": "021000089",
        "bank_swift_bic": "NABNUS33",
        "bank_branch_name": "Manhattan Midtown",
        "bank_branch_address": "111 Wall St, New York, NY",
        "document_phone_number": null,
        "additional_names": []
      },
      "extra_files": [],
      "detected_codes": [
        {
          "type": "QR_CODE",
          "page_number": 1,
          "position": [[820, 1120], [1002, 1120], [1002, 1302], [820, 1302]],
          "x": 820,
          "y": 1120,
          "width": 182,
          "height": 182,
          "page_width": 1190,
          "page_height": 1684,
          "raw_payload": "aHR0cHM6Ly9uYXRpb25hbGJhbmsuZXhhbXBsZS9zdG10Lzk5ODE=",
          "parsed_payload": "https://nationalbank.example/stmt/9981"
        },
        {
          "type": "CODE_128",
          "page_number": 1,
          "position": [[112, 1480], [560, 1480], [560, 1540], [112, 1540]],
          "x": 112,
          "y": 1480,
          "width": 448,
          "height": 60,
          "page_width": 1190,
          "page_height": 1684,
          "raw_payload": "MDAxMjM0NTY3ODk=",
          "parsed_payload": "001234567 89"
        }
      ],
      "warnings": []
    }
  ]
}
```

### مرفوضة — التلاعب باستخدام الطبقات المتراكبة + عدم تطابق الاسم

```json theme={null}
{
  "poa_verifications": [
    {
      "status": "Declined",
      "node_id": "feature_poa_1",
      "issuing_state": "GBR",
      "document_type": "UTILITY_BILL",
      "document_subtype": "ELECTRICITY_BILL",
      "issuer": "BritishEnergy",
      "issue_date": "2026-03-10",
      "expiration_date": null,
      "document_language": "en",
      "name_on_document": "JOHN B SMYTH",
      "poa_address": "44 King's Road, London, SW3 4UD",
      "poa_formatted_address": "44 King's Road, London, SW3 4UD, United Kingdom",
      "poa_parsed_address": {
        "street_1": "44 King's Road",
        "city": "London",
        "postal_code": "SW3 4UD",
        "country": "GB",
        "document_location": { "latitude": 51.4880, "longitude": -0.1690 }
      },
      "document_file": "https://<media-host>/.../poa.pdf?X-Amz-Expires=14400",
      "document_metadata": {
        "file_size": 412910,
        "content_type": "application/pdf",
        "creation_date": "2026-03-10",
        "modified_date": "2026-05-12",
        "creator": "Adobe Acrobat Pro",
        "producer": "Adobe PDF Library",
        "software": "Adobe Acrobat",
        "encryption": null,
        "is_signed": false,
        "is_tampered": false,
        "signature_info": null,
        "exif_original_date": null,
        "exif_digitized_date": null,
        "processed_by_known_editor": false,
        "has_different_creation_mod_date": true,
        "overlay_manipulation": {
          "detected": true,
          "analyzed": true,
          "signals": ["duplicate_font_subset", "glyph_fragmentation"],
          "duplicate_font_subsets": [{ "page": 1, "base_font": "Helvetica" }],
          "fragmented_fonts": [],
          "manipulated_regions": [
            { "page": 1, "x": 102.4, "y": 318.1, "width": 187.0, "height": 18.0, "page_width": 595, "page_height": 842 }
          ]
        }
      },
      "name_match_score_expected_details": 62,
      "name_match_score_id_verification": 60,
      "expected_details_address": null,
      "expected_details_formatted_address": null,
      "expected_details_parsed_address": null,
      "extra_fields": {
        "bank_account_number": null, "bank_iban": null, "bank_sort_code": null,
        "bank_routing_number": null, "bank_swift_bic": null,
        "bank_branch_name": null, "bank_branch_address": null,
        "document_phone_number": null, "additional_names": []
      },
      "extra_files": [],
      "detected_codes": [],
      "warnings": [
        {
          "feature": "PROOF_OF_ADDRESS",
          "risk": "SUSPECTED_DOCUMENT_MANIPULATION",
          "additional_data": {
            "reason": "Overlay-text manipulation detected: same base font embedded with multiple subset prefixes on 1 page(s).",
            "detection_method": "overlay_text_manipulation",
            "signals": ["duplicate_font_subset", "glyph_fragmentation"],
            "duplicate_font_subsets": [{ "page": 1, "base_font": "Helvetica" }],
            "fragmented_fonts": [],
            "manipulated_regions": [
              { "page": 1, "x": 102.4, "y": 318.1, "width": 187.0, "height": 18.0, "page_width": 595, "page_height": 842 }
            ]
          },
          "log_type": "error",
          "short_description": "Suspected document manipulation",
          "long_description": "The system detected signs of potential document manipulation or editing.",
          "node_id": "feature_poa_1"
        },
        {
          "feature": "PROOF_OF_ADDRESS",
          "risk": "NAME_MISMATCH_ID_VERIFICATION",
          "additional_data": {
            "poa_name": "JOHN B SMYTH",
            "kyc_name": "John A. Smith",
            "match_score": 60
          },
          "log_type": "warning",
          "short_description": "Name mismatch with ID verification",
          "long_description": "The full name on the document does not match the name from the user's verified identity documents.",
          "node_id": "feature_poa_1"
        }
      ]
    }
  ]
}
```

## مواضيع ذات صلة

* [تحذيرات إثبات العنوان](https://docs.didit.me/ar/core-technology/proof-of-address/warnings-proof-of-address.md) — كل رمز تحذير يمكن أن يصدره إثبات العنوان (POA)
* [نظرة عامة على إثبات العنوان](https://docs.didit.me/ar/core-technology/proof-of-address/overview.md) — أنواع المستندات المقبولة وقواعد التحقق
* [نماذج البيانات — إثبات العنوان](https://docs.didit.me/ar/reference/data-models.md#إثبات-العنوان) — المخطط القياسي
* [Webhooks](https://docs.didit.me/ar/integration/webhooks.md) — يحمل الحدث `status.updated` بيانات إثبات العنوان (POA)

> [!NOTE]
>
> كل من `document_file` و`extra_files[]` عبارة عن روابط URL موقعة مسبقاً تنتهي صلاحيتها بعد حوالي 4 ساعات. أعد استدعاء endpoint القرار لتحديث روابط URL. قم بتخزين حالة التحقق وحقول العنوان المستخرجة فقط في جانبك — وقلل من بيانات المستندات المحتفظ بها إلى أدنى حد.


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