> ## 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: ربط حساب بنكي أو تجديده

> تبدأ نقطة endpoint من Didit لإنشاء Bank Link تشغيلًا على الخادم، وتعيد الرابط المستضاف الذي يربط فيه الشخص حسابه البنكي.

تبدأ نقطة الـ endpoint المسماة Create a Bank Link من Didit تشغيلًا واحدًا لـ Bank Link على خادمك، لربط بنك أو تجديد اتصال، وتُرجع الرابط المستضاف `url`.
كل حقل له قيمة افتراضية، لذا أصغر طلب هو `{}` مع ما تريد إضافته.
احتفظ بالمعرّف `id` المُعاد مع مستخدمك، وتحقّق من النتيجة بنفسك عبر [الحصول على ربط بنكي](https://docs.didit.me/ar/standalone-apis/bank-link-get.md) أو عبر webhook للحدث `bank.link.completed`.
راجع [دليل البدء السريع](https://docs.didit.me/ar/core-technology/bank-verification/quickstart.md) و[Bank Link](https://docs.didit.me/ar/core-technology/bank-verification/bank-link.md).


## OpenAPI

````yaml ar/openapi-25.json POST /v3/bank/links/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: واجهة برمجة تطبيقات التحقق من الهوية. صادِق باستخدام الترويسة x-api-key.
servers:
  - url: https://verification.didit.me
security: []
tags:
  - name: Bank Data
    description: >-
      Bank Link والاتصالات والحسابات والأرصدة والمعاملات والمؤسسات والتغطية.
      بيانات البنك متاحة للتطبيقات التجريبية. ترد استدعاءات التطبيق الحي بـ
      `404` إلى أن يُعلن الوصول الحي. لا تُحتسب أي رسوم في البيئة التجريبية.
      يحتاج الاستدعاء الذي يتم بمفتاح API إلى مفتاح يتضمن إذن بيانات البنك
      (`bank-data`): القراءة للقراءات، والكتابة للعمليات التي تغيّر شيئاً. فحص
      الحساب هو الاستثناء: يحتاج إلى صلاحية الكتابة على الجلسات، أو الوصول
      الكامل، وليس إذن بيانات البنك. بيانات البنك غير مشمولة بالوصول الكامل:
      يُرفض مفتاح الوصول الكامل، ويرد الاستدعاء بـ `403 bank_data_access_denied`
      إلى أن تنشئ مفتاحاً يتضمن الإذن. ترفض بيانات البنك الخام (الحسابات
      والأرصدة والمعاملات وموجز التغييرات) أيضاً الطلب الذي لا يتضمن مفتاح API.


      تحمل كل حالات الرفض ضمن `/v3/bank/`، باستثناء رفض فحص الحساب، جسم JSON
      نفسه (`code`، `message`، `request_id`، `field`، `next_action`،
      `retry_after`). يرد مسار ليس عملية، أو معرّف ليس UUID، أو مورد فرعي غير
      معروف، بـ `404 not_found` لكل طريقة، ويرد أي خطأ غير متوقع بـ `500
      internal_error` مع `request_id`. حيثما لا تكون بيانات البنك متاحة، ترد كل
      عملية بـ `404` القياسي للمنصة، تماماً كما يرد المسار غير المعروف.
paths:
  /v3/bank/links/:
    post:
      tags:
        - Bank Data
      summary: إنشاء رابط بنكي
      description: >-
        ينشئ رابطاً بنكياً، وهو تشغيل واحد للمسار الذي يربط فيه الشخص حسابه
        البنكي، أو يجدد اتصالاً قائماً. أرسل الشخص إلى `url`. الرمز
        `client_token` مخصص للرابط البنكي المضمّن من Didit، وهو غير متاح بعد،
        لذا افتح `url` اليوم. الرابط المكتمل ينتج اتصالاً.


        أصغر طلب هو `{}` مع ما تريده. القيم الافتراضية: `mode` يساوي connect،
        و`access` يساوي one_time، و`data` يساوي الحسابات فقط، و`history_days`
        يساوي 90، و`ownership.compare` يساوي none، و`segment` يساوي any،
        و`duplicates` يساوي reuse، و`allow_one_time_fallback` يساوي false،
        وبالنسبة للوصول المستمر موافقة بالمدة التي يسمح بها البنك.


        تتضمن الاستجابة عرض السعر: السعر مثبّت على الرابط وتتم محاسبتك به كما
        عُرض. مفتاح API لا يصل أبداً إلى المتصفح أو التطبيق، بل يصلهما `url`
        فقط.


        تحقّق من النتيجة بنفسك عبر `get_link` أو عبر webhook الخاص بالحدث
        `bank.link.completed`، ولا تثق أبداً بمعرّف رابط يرسله المتصفح. السجل:
        أرسل `history_from` أو `history_days`، لا كليهما. حيث يسمح البنك، يستمر
        الوصول المستمر في العمل حتى تنتهي الموافقة، والتاريخ الفعلي موجود في كل
        اتصال.


        يحتاج إلى مفتاح API بإذن بيانات البنك (`bank-data`) بصلاحية الكتابة، لأن
        هذه العملية تُغيّر شيئاً. مفتاح بصلاحية كاملة لا يشمله، لذا امنحه صراحةً
        عند إنشاء المفتاح، وإلا أرجع الاستدعاء `403 bank_data_access_denied`.
      operationId: createBankLink
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BankLinkCreateRequest'
            example:
              mode: connect
              access: ongoing
              country: ESP
              segment: business
              data:
                - accounts
                - balances
                - transactions
              history_from: '2026-01-01'
              consent_days: 180
              ownership:
                compare: none
              end_user:
                reference: client-7731
                email: ana@example.com
              redirect_url: https://app.example.com/bank/return
              allowed_origins:
                - https://app.example.com
              language: es
              vendor_data: client-7731
      responses:
        '201':
          description: تم إنشاء الرابط.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankLink'
              examples:
                Ongoing business connection:
                  summary: الوصول المستمر لحساب تجاري في إسبانيا
                  value:
                    id: 0b9c4f1e-6a2d-4e8b-9f31-7c5d2e1a8b40
                    mode: connect
                    access: ongoing
                    status: created
                    url: https://verify.didit.me/bank/link/example-link-token
                    client_token: example-client-token
                    expires_at: '2026-11-21T13:00:00Z'
                    connection_id: null
                    check_id: null
                    reused: false
                    error: null
                    quote:
                      id: 7a3e9c52-1d84-4b06-8f2a-c5e0b9d17a43
                      lines:
                        - meter: bank_data_connection_month
                          unit: connection_month
                          price_usd: '0.9000'
                      fallback_lines: null
                      total_usd: '0.9000'
                      valid_until: '2026-11-21T13:00:00Z'
                      scopes:
                        - accounts
                        - balances
                        - transactions
                    vendor_data: client-7731
        '400':
          description: >-
            رُفض الطلب قبل أي فحص. يحدد `field` الحقل المطلوب تصحيحه: يُستخدم
            `invalid_request` لقيمة خارج نطاقها أو لتركيبة غير مسموح بها،
            وتُستخدم الرموز الأكثر تحديداً المعروضة هنا.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Bank cannot keep access open:
                  summary: البنك لا يستطيع إبقاء الوصول مفتوحاً
                  value:
                    code: ongoing_access_not_available
                    message: >-
                      This bank cannot keep access open. Use access one_time or
                      choose another bank.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: institution_id
                    next_action: create_link
                    retry_after: null
                History window ambiguous:
                  summary: نافذة السجل غامضة
                  value:
                    code: history_window_ambiguous
                    message: Send history_from or history_days, not both.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: history_from
                    next_action: null
                    retry_after: null
                Redirect URL not registered:
                  summary: عنوان إعادة التوجيه غير مسجل
                  value:
                    code: redirect_url_not_registered
                    message: >-
                      This redirect_url is not one of the return addresses
                      registered for your application. Addresses are matched
                      exactly (scheme, host, port, path and query); in sandbox a
                      plain http localhost address needs no registration. Send a
                      registered address, or leave redirect_url out (automatic
                      return to your page is then not promised).
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: redirect_url
                    next_action: null
                    retry_after: null
                Segment not available:
                  summary: القسم غير متاح
                  value:
                    code: segment_not_available
                    message: >-
                      This bank does not offer this kind of account through Bank
                      Link.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: segment
                    next_action: null
                    retry_after: null
                Window not available:
                  summary: نافذة غير متاحة
                  value:
                    code: window_not_available
                    message: This bank cannot deliver the requested history window.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: history_from
                    next_action: null
                    retry_after: null
                Invalid request:
                  summary: طلب غير صالح
                  value:
                    code: invalid_request
                    message: The request is not valid.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: expires_in
                    next_action: null
                    retry_after: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: الرصيد لا يغطي السعر المعروض. اشحن الرصيد، ثم أعد المحاولة.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Insufficient credits:
                  summary: رصيد غير كافٍ
                  value:
                    code: insufficient_credits
                    message: The balance cannot cover the quoted price.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: null
                    next_action: top_up_balance
                    retry_after: null
        '403':
          description: >-
            مرفوض: عقدك لا يتضمن سعرا لهذه الدولة، أو أن المفتاح يفتقر إلى إذن
            بيانات البنك.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                No contract rate:
                  summary: لا يوجد سعر تعاقدي
                  value:
                    code: contract_rate_missing
                    message: Your contract has no rate for bank data in this country.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: null
                    next_action: null
                    retry_after: null
                Bank data not allowed:
                  summary: بيانات البنك غير مسموح بها
                  value:
                    code: bank_data_access_denied
                    message: >-
                      Bank data calls need an API key that carries the Bank data
                      permission.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: null
                    next_action: enable_bank_data_access
                    retry_after: null
        '404':
          description: المورد غير موجود في هذا التطبيق وهذه البيئة.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Not found:
                  summary: غير موجود
                  value:
                    code: not_found
                    message: The resource does not exist.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: null
                    next_action: null
                    retry_after: null
        '429':
          $ref: '#/components/responses/RateLimitedWrite'
        '500':
          $ref: '#/components/responses/BankDataInternalError'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: |-
            curl -X POST 'https://verification.didit.me/v3/bank/links/' \
              -H 'x-api-key: YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              -d '{
                "mode": "connect",
                "access": "ongoing",
                "country": "ESP",
                "segment": "business",
                "data": [
                  "accounts",
                  "balances",
                  "transactions"
                ],
                "history_from": "2026-01-01",
                "consent_days": 180,
                "ownership": {
                  "compare": "none"
                },
                "end_user": {
                  "reference": "client-7731",
                  "email": "ana@example.com"
                },
                "redirect_url": "https://app.example.com/bank/return",
                "allowed_origins": [
                  "https://app.example.com"
                ],
                "language": "es",
                "vendor_data": "client-7731"
              }'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.bank.create_link(
                mode="connect",
                access="ongoing",
                country="ESP",
                segment="business",
                data=["accounts", "balances", "transactions"],
                history_from="2026-01-01",
                consent_days=180,
                ownership={
                    "compare": "none",
                },
                end_user={
                    "reference": "client-7731",
                    "email": "ana@example.com",
                },
                redirect_url="https://app.example.com/bank/return",
                allowed_origins=["https://app.example.com"],
                language="es",
                vendor_data="client-7731",
            )
            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.bank.createLink({
              mode: "connect",
              access: "ongoing",
              country: "ESP",
              segment: "business",
              data: ["accounts", "balances", "transactions"],
              history_from: "2026-01-01",
              consent_days: 180,
              ownership: {
                compare: "none",
              },
              end_user: {
                reference: "client-7731",
                email: "ana@example.com",
              },
              redirect_url: "https://app.example.com/bank/return",
              allowed_origins: ["https://app.example.com"],
              language: "es",
              vendor_data: "client-7731",
            });
            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Bank.CreateLink(ctx, didit.BankCreateLinkParams{\n\tBody: didit.BankLinkCreateRequest{\n\t\tMode:        didit.Some(didit.BankLinkCreateRequestMode(\"connect\")),\n\t\tAccess:      didit.Some(didit.BankLinkCreateRequestAccess(\"ongoing\")),\n\t\tCountry:     didit.String(\"ESP\"),\n\t\tSegment:     didit.Some(didit.BankLinkCreateRequestSegment(\"business\")),\n\t\tData:        didit.Some([]didit.BankLinkCreateRequestData{\"accounts\", \"balances\", \"transactions\"}),\n\t\tHistoryFrom: didit.String(\"2026-01-01\"),\n\t\tConsentDays: didit.Int(180),\n\t\tOwnership: didit.Some(didit.BankLinkOwnershipRequest{\n\t\t\tCompare: didit.Some(didit.BankLinkOwnershipRequestCompare(\"none\")),\n\t\t}),\n\t\tEndUser: didit.Some(didit.BankLinkEndUser{\n\t\t\tReference: didit.String(\"client-7731\"),\n\t\t\tEmail:     didit.String(\"ana@example.com\"),\n\t\t}),\n\t\tRedirectURL:    didit.String(\"https://app.example.com/bank/return\"),\n\t\tAllowedOrigins: didit.Some([]string{\"https://app.example.com\"}),\n\t\tLanguage:       didit.String(\"es\"),\n\t\tVendorData:     didit.String(\"client-7731\"),\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
        - lang: java
          label: Java
          source: >-
            import java.time.LocalDate;

            import java.util.List;

            import me.didit.Didit;

            import me.didit.types.BankLinkCreateRequest;

            import me.didit.types.BankLinkEndUser;

            import me.didit.types.BankLinkOwnershipRequest;


            // Reads DIDIT_API_KEY.

            Didit client = new Didit();


            var result =
            client.bank().createLink(BankLinkCreateRequest.builder()
                    .mode(BankLinkCreateRequest.Mode.of("connect"))
                    .access(BankLinkCreateRequest.Access.of("ongoing"))
                    .country("ESP")
                    .segment(BankLinkCreateRequest.Segment.of("business"))
                    .data(List.of(BankLinkCreateRequest.Data.of("accounts"), BankLinkCreateRequest.Data.of("balances"), BankLinkCreateRequest.Data.of("transactions")))
                    .historyFrom(LocalDate.parse("2026-01-01"))
                    .consentDays(180L)
                    .ownership(BankLinkOwnershipRequest.builder()
                            .compare(BankLinkOwnershipRequest.Compare.of("none"))
                            .build())
                    .endUser(BankLinkEndUser.builder()
                            .reference("client-7731")
                            .email("ana@example.com")
                            .build())
                    .redirectUrl("https://app.example.com/bank/return")
                    .allowedOrigins(List.of("https://app.example.com"))
                    .language("es")
                    .vendorData("client-7731")
                    .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->bank->createLink([
                'mode' => 'connect',
                'access' => 'ongoing',
                'country' => 'ESP',
                'segment' => 'business',
                'data' => ['accounts', 'balances', 'transactions'],
                'history_from' => '2026-01-01',
                'consent_days' => 180,
                'ownership' => [
                    'compare' => 'none',
                ],
                'end_user' => [
                    'reference' => 'client-7731',
                    'email' => 'ana@example.com',
                ],
                'redirect_url' => 'https://app.example.com/bank/return',
                'allowed_origins' => ['https://app.example.com'],
                'language' => 'es',
                'vendor_data' => 'client-7731',
            ]);
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

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

            result = didit.bank.create_link(
              mode: "connect",
              access: "ongoing",
              country: "ESP",
              segment: "business",
              data: ["accounts", "balances", "transactions"],
              history_from: "2026-01-01",
              consent_days: 180,
              ownership: {
                compare: "none",
              },
              end_user: {
                reference: "client-7731",
                email: "ana@example.com",
              },
              redirect_url: "https://app.example.com/bank/return",
              allowed_origins: ["https://app.example.com"],
              language: "es",
              vendor_data: "client-7731"
            )
            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.Bank.CreateLinkAsync(new
            BankLinkCreateRequest

            {
                Mode = new BankLinkCreateRequestMode("connect"),
                Access = new BankLinkCreateRequestAccess("ongoing"),
                Country = "ESP",
                Segment = new BankLinkCreateRequestSegment("business"),
                Data = new BankLinkCreateRequestData[] { "accounts", "balances", "transactions" },
                HistoryFrom = "2026-01-01",
                ConsentDays = 180,
                Ownership = new BankLinkOwnershipRequest
                {
                    Compare = new BankLinkOwnershipRequestCompare("none"),
                },
                EndUser = new BankLinkEndUser
                {
                    Reference = "client-7731",
                    Email = "ana@example.com",
                },
                RedirectUrl = "https://app.example.com/bank/return",
                AllowedOrigins = new string[] { "https://app.example.com" },
                Language = "es",
                VendorData = "client-7731",
            });

            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        مفتاح اختياري لأمان إعادة المحاولة تختاره لعملية واحدة، بحد أقصى 255
        حرفًا (يصلح UUID). الطلب المكرَّر بالمفتاح نفسه والـ endpoint والاستعلام
        والمحتوى يُجاب بالاستجابة الأولى نفسها، بالحالة والمحتوى نفسيهما، ولا
        يُنفَّذ ولا يُحتسب مرة ثانية. استخدام المفتاح نفسه مع endpoint أو
        استعلام أو محتوى مختلف يعيد `409` مع `idempotency_key_reused`، وبينما
        الطلب الأول ما زال قيد التنفيذ يعيد `409` مع
        `idempotency_key_in_progress` ومعه `Retry-After`. لا يُخزَّن الطلب
        الفاشل (أي `4xx` أو `5xx`)، لذا يمكنك إرساله مرة أخرى بالمفتاح نفسه.
        المفاتيح تخص تطبيقك، سواء استدعيت بمفتاح API أو بـ token الوصول. راجع
        [إعادة المحاولة
        وidempotency](/ar/integration/api-errors#إعادة-المحاولة-وidempotency).
      schema:
        type: string
        minLength: 1
        maxLength: 255
  schemas:
    BankLinkCreateRequest:
      type: object
      description: >-
        أنشئ رابطاً بنكياً. أصغر طلب هو `{}` مع ما تريده، ولكل حقل قيمة
        افتراضية.
      properties:
        mode:
          type: string
          enum:
            - connect
            - renew
          description: >-
            `connect` (الافتراضي) ينشئ اتصالًا جديدًا. `renew` يحتاج إلى
            `connection_id` ويعيد استخدام إعدادات ذلك الاتصال.
          default: connect
        connection_id:
          type: string
          description: 'الاتصال المراد تجديده. فقط مع `mode: renew`.'
          format: uuid
        access:
          type: string
          enum:
            - one_time
            - ongoing
          description: >-
            `one_time` (الافتراضي) يقرأ البيانات مرة واحدة. `ongoing` يُبقي
            الوصول مفتوحًا حتى تنتهي الموافقة أو يوقفها أحد. عند تحديد
            `institution_id`، يرد البنك الذي لا يستطيع إبقاء الوصول مفتوحًا
            بالخطأ `400 ongoing_access_not_available` قبل عرض أي شاشة. وبدونه،
            يعرض منتقي البنوك البنوك التي تستطيع ذلك فقط.
          default: one_time
        country:
          type: string
          description: >-
            اختياري. إن لم ترسله يختار الشخص من بين الدول التي فعّلها تطبيقك.
            يجب أن تكون دولة تخدمها Bank Link؛ أي دولة أخرى، بما فيها `ZZZ`،
            تُرجع `400 invalid_request` مع `field: country`. يبقى طلب بجسم فارغ
            صالحا.
          pattern: ^[A-Z]{3}$
        institution_id:
          type: string
          description: >-
            بنك اختياري يُحدد مسبقا من `list_institutions`، فيتجاوز منتقي
            البنوك.
          maxLength: 64
        segment:
          type: string
          enum:
            - personal
            - business
            - any
          description: >-
            يصفّي أداة الاختيار، ويحدد للبنك تسجيل الدخول الذي يُفتح عندما يفصل
            البنك بين تسجيلات الدخول. القيمة الافتراضية `any`.
          default: any
        data:
          type: array
          items:
            type: string
            enum:
              - accounts
              - balances
              - transactions
          description: >-
            ما الذي تقرؤه. يُضمَّن `accounts` دائمًا: الاسم والنوع والعملة
            والمعرّفات، واسم صاحب الحساب حيث يشاركه البنك. الافتراضي
            `["accounts"]`.
          default:
            - accounts
          maxItems: 3
        history_days:
          type: integer
          description: >-
            عدد أيام سجل المعاملات المطلوب، من 1 إلى 365، والافتراضي 90. قد
            يسلّم البنك أقل من ذلك: يبيّن كل حساب ما سلّمه في
            `history_coverage`. لا يمكن إرساله مع `history_from`.
          minimum: 1
          maximum: 365
          default: 90
        history_from:
          type: string
          description: >-
            تاريخ بداية السجل المطلوب، بدلاً من `history_days`. لا يمكن إرساله
            مع `history_days`: إرسال الاثنين معاً يُعيد `400
            history_window_ambiguous`. التاريخ الأقدم من 365 يوماً، أو التاريخ
            المستقبلي، يُعيد `400 window_not_available`.
          format: date
        extended_history:
          type: string
          enum:
            - standard
            - allow_extra_auth
          description: >-
            `allow_extra_auth` يتيح لبنك يطلب تأكيدًا إضافيًا واحدًا أن يفرج عن
            السجل الأقدم.
          default: standard
        consent_days:
          type: integer
          description: >-
            متاح للوصول المستمر فقط. عدد الأيام التي تطلب فيها من البنك إبقاء
            الوصول مفتوحا، يوم واحد أو أكثر. القيمة الافتراضية: أطول مدة يسمح
            بها البنك. يعرض الاتصال التاريخ الذي منحه البنك فعلا في
            `consent.expires_at`. مع `access: one_time` يُرجع `400
            invalid_request` مع `field: consent_days`.
          minimum: 1
          maximum: 32767
        ownership:
          $ref: '#/components/schemas/BankLinkOwnershipRequest'
        end_user:
          $ref: '#/components/schemas/BankLinkEndUser'
        redirect_url:
          type: string
          description: >-
            إلى أين ينتقل المتصفح في النهاية، مع `link_id` و`status` و`state`
            موقّع (للعرض فقط: الـ webhook و`get_link` هما المرجع الموثوق). في
            تطبيق البيئة التجريبية، يُسمح بعنوان `http` عادي يشير إلى
            `localhost` أو `127.0.0.1` أو `[::1]` (بأي منفذ ومسار، دون بيانات
            اعتماد ولا جزء تجزئة) دون تسجيل مسبق. أي عنوان آخر يُرجع `400
            redirect_url_not_registered`، إذ إن تسجيل عناوين أخرى غير متاح
            حاليًا. وبدون `redirect_url` يُنهي الشخص العملية في صفحة النتيجة
            الخاصة بـ Didit.
          format: uri
          maxLength: 2048
        allowed_origins:
          type: array
          items:
            type: string
            format: uri
          description: >-
            مقبول ولا يُستخدم اليوم: مخصص لـ Bank Link المدمج لدى Didit، وهو غير
            متاح بعد. مصادر HTTPS، بحد أقصى 50.
          maxItems: 50
        language:
          type: string
          description: رمز لغة اختياري مثل `es` أو `pt-BR`. وإلا فتُستخدم لغة المتصفح.
          pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})?$
          maxLength: 16
        vendor_data:
          type: string
          description: مرجعك الخاص، ويُعاد في الرابط والاتصال.
          maxLength: 255
        expires_in:
          type: integer
          description: >-
            مدة صلاحية الرابط بالثواني، من 300 إلى 86400. القيمة الافتراضية
            3600.
          minimum: 300
          maximum: 86400
          default: 3600
        duplicates:
          type: string
          enum:
            - reuse
            - allow
          description: >-
            `reuse` (الافتراضي) يُكمل الرابط الذي يشير إلى حسابات تشاركها بالفعل
            بوصفه تجديداً لذلك الاتصال. `allow` ينشئ اتصالاً ثانياً مستقلاً.
          default: reuse
        allow_one_time_fallback:
          type: boolean
          description: >-
            مع `ongoing`، يتيح للشخص المتابعة بقراءة لمرة واحدة لدى بنك لا
            يستطيع إبقاء الوصول مفتوحًا، بعد تأكيد الوصول المخفّض على شاشة البنك
            نفسها. يوضح العرض ما تكلفه هذه الخطوة. يُستخدم فقط مع `access:
            ongoing`: مع الوصول لمرة واحدة يرد بالخطأ `400 invalid_request` مع
            `field: allow_one_time_fallback`.
          default: false
        accept_reduced_grant:
          type: boolean
          description: >-
            عندما يمنح البنك أو الشخص أقل مما طلبته، يُكمَل الرابط ولا يُحتسب
            إلا على النطاقات الممنوحة. وفي غير ذلك ينتهي الرابط بالحالة `failed`
            مع `reduced_grant` دون احتساب أي رسوم.
          default: false
        sandbox:
          type: object
          description: >-
            للتطبيقات التجريبية فقط: يختار عميل Didit Test Bank. يُتجاهل في
            تطبيق في بيئة الإنتاج.
          properties:
            persona:
              type: string
              enum:
                - personal_basic
                - business_multi
                - long_history
                - pending
                - sparse_fields
                - no_ongoing
              description: >-
                عميل Test Bank: `personal_basic` (حساب جارٍ واحد، 60 حركة)،
                `business_multi` (ثلاثة حسابات تملكها شركة)، `long_history`
                (حساب واحد بعمر 400 يوم و1,400 حركة؛ تُرجع القراءة آخر 365
                يومًا، لذا اضبط `history_days` على 365)، `pending` (يتضمن
                المعاملات المعلّقة)، `sparse_fields` (بدون تاريخ القيمة، وبدون
                IBAN للطرف المقابل، وبدون مرجع المصرف) أو `no_ongoing` (مصرف
                يسمح بالوصول لمرة واحدة فقط: استخدم `allow_one_time_fallback`).
            switches:
              type: array
              items:
                type: string
                enum:
                  - partial_grant
                  - renewal_other_login
                  - expired_cursor
                  - webhook_twice
                  - midnight_booking
                  - blocked_popup
                  - bank_app_return
              description: 'مقبول ومخصص لمحاكي البيئة التجريبية: القيم لا تغيّر شيئاً اليوم.'
    BankLink:
      type: object
      description: >-
        تشغيل واحد لـ Bank Link لشخص واحد: ربط بنك، أو تجديد ربط. أكِّد الرابط
        بنفسك باستخدام `get_link`، ولا تثق أبداً بمعرّف يرسله المتصفح.
      properties:
        id:
          type: string
          description: معرّف الرابط.
          format: uuid
        mode:
          type: string
          enum:
            - connect
            - renew
        access:
          type: string
          enum:
            - one_time
            - ongoing
        status:
          type: string
          enum:
            - created
            - opened
            - connecting
            - completed
            - cancelled
            - expired
            - failed
          description: >-
            حالة الرابط. الحالات `completed` و`cancelled` و`expired` و`failed`
            نهائية.
        url:
          type: string
          description: >-
            صفحة التحقق المستضافة التي يُوجَّه إليها الشخص. تُعاد فقط عند إنشاء
            الرابط؛ وتكون `null` في القراءات اللاحقة لأن الرمز لا يُخزَّن.
          nullable: true
          format: uri
        client_token:
          type: string
          description: >-
            token الخاص بـ Bank Link المضمّن في Didit، وهو غير متاح بعد: افتح
            `url` حالياً. يُعاد عند إنشاء الرابط فقط، وتكون القيمة `null` في
            القراءات اللاحقة. له غرض واحد وصلاحية قصيرة، ولا يحمل أي بيانات
            شخصية. لا تسجّله في السجلات أبداً.
          nullable: true
        expires_at:
          type: string
          description: متى يتوقف الرابط غير المستخدَم عن العمل.
          format: date-time
        connection_id:
          type: string
          description: >-
            الاتصال الذي أنشأه هذا الرابط أو جدّده، بمجرد أن تصبح `status` بقيمة
            `completed`.
          format: uuid
          nullable: true
        check_id:
          type: string
          description: >-
            نتيجة الملكية لهذا الرابط، عندما يطلب `ownership.compare` بقيمة غير
            `none`.
          format: uuid
          nullable: true
        reused:
          type: boolean
          description: >-
            `true` عندما يكتمل الرابط بوصفه تجديداً لاتصال قائم، لأن الشخص يشارك
            بالفعل هذه الحسابات نفسها بالضبط (`duplicates: reuse`). لا تُفرض أي
            رسوم مرتين.
        error:
          allOf:
            - $ref: '#/components/schemas/BankLinkError'
          nullable: true
          description: >-
            سبب فشل الرابط، عندما تكون `status` هي `failed`. وإلا فالقيمة
            `null`.
        quote:
          $ref: '#/components/schemas/BankLinkQuote'
        vendor_data:
          type: string
          description: مرجعك من الطلب.
          nullable: true
      required:
        - id
        - mode
        - access
        - status
        - url
        - client_token
        - expires_at
        - connection_id
        - check_id
        - reused
        - error
        - quote
        - vendor_data
    BankDataError:
      type: object
      description: جسم الخطأ لكل عملية من عمليات بيانات البنك. جميع الحقول موجودة دائماً.
      properties:
        code:
          type: string
          enum:
            - ongoing_access_not_available
            - segment_not_available
            - window_not_available
            - history_window_ambiguous
            - redirect_url_not_registered
            - link_origin_not_allowed
            - bank_data_access_denied
            - connection_not_active
            - consent_expired
            - renewal_not_needed
            - renewal_window_expired
            - access_removed
            - refresh_limit_reached
            - cursor_expired
            - page_expired
            - invalid_cursor
            - page_token_mismatch
            - contract_rate_missing
            - insufficient_credits
            - invalid_request
            - not_found
            - internal_error
          description: >-
            رمز الخطأ بصيغة يمكن للآلة قراءتها. اعتمد على هذا الرمز في التفريع،
            ولا تعتمد على `message` أبداً.
        message:
          type: string
          description: شرح بلغة بسيطة للمطوّر. قد تتغير الصياغة؛ لا تحلّلها برمجياً.
        request_id:
          type: string
          description: معرّف هذا الطلب. اذكره عند التواصل مع الدعم.
        field:
          type: string
          description: >-
            حقل الطلب المطلوب تصحيحه، إذا كان الخطأ متعلقاً بحقل واحد. وإلا
            فتكون القيمة `null`.
          nullable: true
        next_action:
          type: string
          enum:
            - retry_later
            - renew_connection
            - create_link
            - restart_from_cursor
            - restart_read
            - top_up_balance
            - enable_bank_data_access
            - contact_support
            - null
          description: >-
            ما الذي ينبغي فعله تاليًا، حتى يتمكن العميل من التصرف دون تخمين.
            القيمة `null` عندما لا توجد خطوة تالية قياسية.
          nullable: true
        retry_after:
          type: integer
          description: >-
            عدد الثواني التي تنتظرها قبل إعادة المحاولة. يُضبط عند أخطاء حد
            المعدل والأخطاء المؤقتة، وإلا فهو `null`.
          nullable: true
      required:
        - code
        - message
        - request_id
        - field
        - next_action
        - retry_after
      example:
        code: ongoing_access_not_available
        message: >-
          This bank cannot keep access open. Use access one_time or choose
          another bank.
        request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
        field: institution_id
        next_action: create_link
        retry_after: null
    BankLinkOwnershipRequest:
      type: object
      description: مقارنة اختيارية لصاحب الحساب مع شخص أو شركة.
      properties:
        compare:
          type: string
          enum:
            - none
            - person
            - business
          description: >-
            ما يُقارَن به صاحب الحساب. القيمة `none` (الافتراضي) لا تُصدر حكمًا
            ولا تحتاج إلى مرجع. القيمة `person` تحتاج إلى `reference_identity`
            أو `session_id`. القيمة `business` تحتاج إلى `business` أو
            `business_session_id`. أرسل مرجعًا واحدًا فقط من النوع الذي تقارن
            به، ولا ترسل أي مرجع مع `none`.
          default: none
        match:
          type: string
          enum:
            - any_holder
            - all_holders
          description: >-
            هل يجب أن يتطابق مالك قانوني واحد أو كل المالكين القانونيين. لا
            يُحتسب الممثلون أبدًا.
          default: any_holder
        reference_identity:
          type: object
          description: >-
            قيم يقدمها المستدعي للمقارنة مع صاحب الحساب. لا يمكن إرسالها مع
            `session_id`.
          properties:
            full_name:
              type: string
              maxLength: 255
            date_of_birth:
              type: string
              format: date
            address:
              type: string
              maxLength: 500
            phone:
              type: string
              maxLength: 64
            email:
              type: string
              maxLength: 255
        session_id:
          type: string
          description: >-
            جلسة تحقق مكتملة من Didit للشخص المراد مقارنته. لا يمكن إرسالها مع
            `reference_identity`.
          format: uuid
        business:
          type: object
          description: الشركة المراد مقارنتها بصاحب الحساب.
          properties:
            legal_name:
              type: string
              maxLength: 255
            registration_id:
              type: string
              maxLength: 128
          required:
            - legal_name
        business_session_id:
          type: string
          description: >-
            عملية تحقق تجارية من Didit للمقارنة معها. لا يمكن إرسالها مع
            `business`.
          format: uuid
    BankLinkEndUser:
      type: object
      description: الشخص أو الشركة التي تربط الحساب.
      properties:
        reference:
          type: string
          description: >-
            معرّفك الخاص للشخص أو الشركة. يمكن البحث به باستخدام
            `end_user_reference`، ويُستخدم للتعرف على اتصال متكرر.
          maxLength: 255
        email:
          type: string
          description: >-
            اختياري. حين يتطلب مسار البنك عنوانا موثقا للشخص ولم ترسل عنوانا،
            يطلب Bank Link العنوان من الشخص. لا يُستخدم هذا الحقل للتسويق أبدا.
          format: email
          maxLength: 254
    BankLinkError:
      type: object
      description: سبب انتهاء الرابط بالحالة `failed`. لم يُنشر أي شيء ولم تُحتسب أي رسوم.
      properties:
        code:
          type: string
          enum:
            - duplicate_conflict
            - renewal_login_mismatch
            - reduced_grant
            - corporate_approval_not_supported
            - ongoing_access_not_available
            - bank_unavailable
            - bank_cancelled
            - consent_declined
            - read_limit
            - renewal_not_needed
            - renewal_window_expired
            - first_sync_failed
          description: >-
            سبب فشل الرابط. الرابط الفاشل ليس خطأ HTTP: يُقرأ الرابط بالحالة
            `status: failed` وبهذا الكائن. رابط التجديد الذي تغيّر فيه الاتصال
            في هذه الأثناء يُقرأ بالقيمة `renewal_not_needed` أو
            `renewal_window_expired`.
        message:
          type: string
          description: شرح بلغة بسيطة للمطوّر.
        conflicts_with:
          type: array
          nullable: true
          items:
            type: string
            format: uuid
          description: >-
            مع `duplicate_conflict`: معرّفات الاتصالات النشطة المتداخلة. جدّد
            أحدها، أو أنشئ الرابط مرة أخرى مع `duplicates: allow`.
      required:
        - code
        - message
        - conflicts_with
    BankLinkQuote:
      type: object
      description: >-
        سعر الرابط، ويُثبَّت عند إنشائه. يُحتسب الرسم وفق عرض السعر. لا تُحتسب
        أي رسوم عند عمليات القراءة.
      properties:
        id:
          type: string
          description: معرّف عرض السعر.
          format: uuid
        lines:
          type: array
          items:
            $ref: '#/components/schemas/BankLinkQuoteLine'
          description: بنود الرسوم التي يفرضها هذا الرابط، وفق النطاقات التي يطلبها.
        fallback_lines:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/BankLinkQuoteLine'
          description: >-
            تكلفة الخيار الاحتياطي لمرة واحدة، وتظهر فقط إذا أُنشئ الرابط بـ
            `allow_one_time_fallback`. تظهر في استجابة الإنشاء وتكون القيمة
            `null` في غير ذلك. قد تكلّف القراءة لمرة واحدة مع البيانات أكثر من
            الشهر الأول من الوصول المستمر.
        total_usd:
          type: string
          description: >-
            مجموع `lines` بالدولار الأمريكي. لا يرتفع المجموع أبداً، ويمكن أن
            ينخفض فقط: مع منحة مخفّضة، أو عندما يختار الشخص دولة ذات سعر أقل.
          pattern: ^-?\d+(\.\d+)?$
        valid_until:
          type: string
          description: >-
            يرتبط عرض السعر بالرابط ويبقى صالحاً طوال مدة صلاحيته، لذلك يساوي
            `expires_at`.
          format: date-time
        scopes:
          type: array
          items:
            type: string
            enum:
              - accounts
              - balances
              - transactions
          description: تحدد البيانات نطاق أسعار عرض السعر.
      required:
        - id
        - lines
        - fallback_lines
        - total_usd
        - valid_until
        - scopes
    RateLimitBudgetError:
      type: object
      description: >-
        تُرجع فقط عند رفض ميزانية وسيط تحديد المعدل. أخطاء 429 الأخرى، بما في
        ذلك تعارضات idempotency والحدود الخاصة بنقطة النهاية، لا تضمن هذه الحقول
        الوصفية.
      required:
        - detail
        - reference
        - limit
        - remaining
        - reset
        - window_seconds
      properties:
        detail:
          type: string
          description: رسالة رفض الميزانية الحالية المقروءة للإنسان.
        reference:
          type: string
          pattern: ^RL-[0-9a-f]{32}$
          description: >-
            مرجع الدعم المعتم: RL- متبوعة بـ 32 حرفًا سداسيًا عشريًا صغيرًا من
            UUID.
        limit:
          type: integer
          description: الميزانية للنطاق الذي تجاوز الحد؛ تساوي X-RateLimit-Limit.
        remaining:
          type: integer
          minimum: 0
          description: >-
            الميزانية المتبقية، محدودة بحيث لا تقل عن الصفر؛ تساوي
            X-RateLimit-Remaining.
        reset:
          type: integer
          format: int64
          description: >-
            وقت إعادة تعيين النافذة بالثواني منذ حقبة Unix، ويساوي
            X-RateLimit-Reset.
        window_seconds:
          type: integer
          description: >-
            مدة النافذة الثابتة بالثواني، وليست الفترة المتبقية للانتظار. يجب
            احترام Retry-After قبل إعادة المحاولة.
      example:
        detail: >-
          Write request rate limit exceeded. You can make up to 300 requests per
          minute.
        reference: RL-00000000000040008000000000000001
        limit: 300
        remaining: 0
        reset: 1794358860
        window_seconds: 60
    BankLinkQuoteLine:
      type: object
      description: بند مُسعَّر واحد في عرض السعر.
      properties:
        meter:
          type: string
          description: >-
            ما الذي يُحتسب عليه، على سبيل المثال `bank_data_connection_month`
            و`bank_verification`.
          example: bank_data_connection_month
        unit:
          type: string
          description: >-
            ما هي الوحدة الواحدة، على سبيل المثال `connection_month` أو
            `completed_sign_in`.
          example: connection_month
        price_usd:
          type: string
          description: >-
            سعر الوحدة الواحدة بالدولار الأمريكي، سلسلة عشرية بأربع خانات عشرية.
            المبالغ في الأمثلة توضيحية؛ يظهر سعر كل دولة في صفحة الأسعار.
          pattern: ^-?\d+(\.\d+)?$
          example: '0.9000'
      required:
        - meter
        - unit
        - price_usd
  responses:
    Unauthorized:
      description: غير مُصرَّح به
      content:
        application/json:
          examples:
            Invalid API Key:
              summary: مفتاح API غير صالح
              value:
                detail: Invalid API Key.
    RateLimitedWrite:
      description: >-
        تم تجاوز حد الكتابة المشترك البالغ 300 طلب في الدقيقة لكل مفتاح API.
        التزم بالقيمة في `Retry-After` قبل إعادة المحاولة.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitBudgetError'
          example:
            detail: >-
              Write request rate limit exceeded. You can make up to 300 requests
              per minute.
            reference: RL-00000000000040008000000000000001
            limit: 300
            remaining: 0
            reset: 1794358860
            window_seconds: 60
      headers:
        Retry-After:
          $ref: '#/components/headers/BudgetRetryAfter'
        X-RateLimit-Scope:
          $ref: '#/components/headers/BudgetXRateLimitScope'
        X-RateLimit-Limit:
          $ref: '#/components/headers/BudgetXRateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/BudgetXRateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/BudgetXRateLimitReset'
    BankDataInternalError:
      description: >-
        حدث خطأ من جهة Didit. أي خطأ غير متوقع تحت `/v3/bank/` يُعاد بصيغة خطأ
        Bank، وليس بصفحة HTML أبداً: أرفق `request_id` عند التواصل مع الدعم.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BankDataError'
          examples:
            Internal error:
              summary: خطأ غير متوقع
              value:
                code: internal_error
                message: >-
                  Something went wrong on our side. Quote the request_id to
                  support.
                request_id: 3f6a1c8e92b54d07a1e38c4b7f0d2e59
                field: null
                next_action: contact_support
                retry_after: null
  headers:
    BudgetRetryAfter:
      description: >-
        عدد الثواني للانتظار، مقرّباً إلى أعلى حتى بداية النافذة التالية. يظهر
        في حالات رفض ميزانية الوسيط.
      schema:
        type: integer
    BudgetXRateLimitScope:
      description: النطاق الذي تجاوز ميزانيته. يظهر في حالات رفض ميزانية الوسيط.
      schema:
        type: string
    BudgetXRateLimitLimit:
      description: >-
        الميزانية المخصصة للنطاق الذي تم تجاوزه؛ وتساوي حد جسم الطلب. تظهر في
        حالات الرفض الصادرة عن ميزانية البرمجية الوسيطة.
      schema:
        type: integer
    BudgetXRateLimitRemaining:
      description: >-
        الميزانية المتبقية، محدودة بحيث لا تقل عن الصفر؛ تساوي remaining في
        الجسم. تظهر في حالات رفض الميزانية من الوسيط.
      schema:
        type: integer
    BudgetXRateLimitReset:
      description: >-
        وقت إعادة التعيين بالثواني منذ حقبة Unix؛ يساوي قيمة reset في جسم
        الاستجابة. يظهر في حالات رفض ميزانية الوسيط.
      schema:
        type: integer
  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، ويتلقى المفتاح الذي لا
        يملك صلاحية كتابة الجلسات روابط الجلسات والرموز بقيمة null. راجع
        https://docs.didit.me/console/api-keys.

````

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