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

# SDK الخادم: Python وNode.js وGo وJava وPHP وRuby وNET.

> استدعِ واجهات Didit البرمجية من الخادم عبر SDK رسمي مُنمَّط. مصفوفة التثبيت، والإعدادات، والأخطاء، وإعادة المحاولة، والإصدارات، وسياسة الدعم.

حزم SDK للخادم هي المكتبات الرسمية من Didit لخادم التطبيق لديك. تستدعي كل حزمة endpoints الخادم في [مرجع API](https://docs.didit.me/ar/api-reference/overview.md) بطلبات واستجابات محددة الأنواع، وتتحقق من webhook التي ترسلها إليك Didit، وتتحقق من الرموز الخاصة بـ[Didit Authentication](https://docs.didit.me/ar/authentication/overview.md). لا يتضمن أي إصدار 1.0.1 الـendpointين الخاصين بـGoogle Wallet بعد: [بدء التحقق عبر Google Wallet](https://docs.didit.me/ar/api-reference/digital-id-wallets/google-wallet.md) و[إرسال استجابة المحفظة](https://docs.didit.me/ar/standalone-apis/digital-id-wallet-response.md). تتضمن حزم Python وNode.js وJava وPHP وRuby و.NET كل endpoints الخادم الأخرى. تفتقر حزمة Go 1.0.1 إلى تسع endpoints أخرى، معظمها نقاط نهاية Travel Rule: راجع [نقاط النهاية غير الموجودة في حزمة Go بعد](https://docs.didit.me/ar/integration/server-sdks/go.md#endpoints-غير-المتوفرة-في-go-sdk-بعد).

استخدم الحزم حيثما يحتوي كودك على مفتاح API من Didit: إنشاء جلسات التحقق، وقراءة القرارات، واستدعاء واجهات APIs المستقلة، وإدارة المستخدمين والشركات وسير العمل والحالات، وفحص المعاملات والمحافظ، وTravel Rule. في المتصفح أو تطبيق الجوال، استخدم بدلاً منها حزم [web](https://docs.didit.me/ar/integration/web-sdks/overview.md) و[native](https://docs.didit.me/ar/integration/native-sdks/overview.md): فهي تعرض مسار التحقق على مستخدمك، ولا تحتفظ بمفتاح API أبداً.

تعرض صفحات endpoints الخادم في [مرجع API](https://docs.didit.me/ar/api-reference/overview.md)، بما فيها صفحات خدمة [Database Validation](https://docs.didit.me/ar/standalone-apis/database-validation.md)، عينة كود لكل حزمة SDK للخادم بجانب طلب cURL. تُعرض العينة بعد أن يتضمن أحدث إصدار من الحزمة الـendpoint وكل حقل ترسله العينة: يحصل كل endpoint أو حقل أُضيف إلى API على عينته مع الإصدار التالي من كل حزمة SDK. لا يتضمن أي إصدار 1.0.1 حقول الطلب الـ16 لخدمة Database Validation التي أُضيفت بعد إصداره، أي إصدار 1.0.1، مثل `vin` أو `bank_account_number`، لذلك لا تعرض صفحات الخدمة التي ترسلها سوى cURL.

## التثبيت

```bash Python theme={null}
pip install didit-sdk
```

```bash Node.js theme={null}
npm install @didit-protocol/sdk-node
```

```bash Go theme={null}
go get github.com/didit-protocol/sdk-go
```

```kotlin Java theme={null}
implementation("me.didit:didit-java:1.0.1")
```

```bash PHP theme={null}
composer require didit-protocol/sdk-php guzzlehttp/guzzle
```

```bash Ruby theme={null}
gem install didit-sdk
```

```bash .NET theme={null}
dotnet add package Didit
```

| اللغة | الحزمة | المصدر | الحد الأدنى لبيئة التشغيل |
| - | - | - | - |
| [Python](https://docs.didit.me/ar/integration/server-sdks/python.md) | [PyPI `didit-sdk`](https://pypi.org/project/didit-sdk/) | [sdk-python](https://github.com/didit-protocol/sdk-python) | Python 3.10 |
| [Node.js و TypeScript](https://docs.didit.me/ar/integration/server-sdks/node.md) | [npm `@didit-protocol/sdk-node`](https://www.npmjs.com/package/@didit-protocol/sdk-node) | [sdk-node](https://github.com/didit-protocol/sdk-node) | Node.js 18 وBun وDeno وبيئات Edge التي تدعم `fetch` |
| [Go](https://docs.didit.me/ar/integration/server-sdks/go.md) | [وحدة Go `github.com/didit-protocol/sdk-go`](https://pkg.go.dev/github.com/didit-protocol/sdk-go) | [sdk-go](https://github.com/didit-protocol/sdk-go) | Go 1.22 |
| [Java و Kotlin](https://docs.didit.me/ar/integration/server-sdks/java.md) | [Maven Central `me.didit:didit-java`](https://central.sonatype.com/artifact/me.didit/didit-java) | [sdk-java](https://github.com/didit-protocol/sdk-java) | Java 11 |
| [PHP](https://docs.didit.me/ar/integration/server-sdks/php.md) | [Packagist `didit-protocol/sdk-php`](https://packagist.org/packages/didit-protocol/sdk-php) | [sdk-php](https://github.com/didit-protocol/sdk-php) | PHP 8.1 |
| [Ruby](https://docs.didit.me/ar/integration/server-sdks/ruby.md) | [RubyGems `didit-sdk`](https://rubygems.org/gems/didit-sdk) | [sdk-ruby](https://github.com/didit-protocol/sdk-ruby) | Ruby 3.1 |
| [C# و .NET](https://docs.didit.me/ar/integration/server-sdks/dotnet.md) | [NuGet `Didit`](https://www.nuget.org/packages/Didit) | [sdk-dotnet](https://github.com/didit-protocol/sdk-dotnet) | .NET 8 أو .NET Standard 2.0 |

## الإعداد

تقرأ كل حزمة SDK متغيرات البيئة نفسها، لذلك يكون العميل الذي تنشئه دون أي خيارات جاهزاً للاستخدام. لا تملك بيئات Edge متغيرات بيئة للعملية: في هذه البيئات مرّر مفتاح API إلى عميل Node.js بوصفه خياراً.

| المتغير | الاستخدام |
| - | - |
| `DIDIT_API_KEY` | كل استدعاء يستخدم مفتاح API. أنشئ المفتاح في لوحة التحكم ضمن [مفاتيح API](https://docs.didit.me/ar/console/api-keys.md). |
| `DIDIT_ORGANIZATION_ID`, `DIDIT_APPLICATION_ID` | العمليات ضمن `/v3/organization/{organization_id}/application/{application_id}/` (الحالات، والشبكات، والتقارير التنظيمية، وقوالب التقارير، وبعض أدوات المستخدمين والشركات). تملأ الحزمة معرّفي المسار من العميل، فلا تمرّرهما في كل استدعاء. بدونهما تفشل هذه الاستدعاءات قبل إرسال أي طلب. |
| `DIDIT_LOG=debug` | يسجّل الطريقة والمسار والحالة والمدة ومعرّف الطلب لكل طلب. لا تُسجَّل أجسام الطلبات أو الاستجابات ولا الرؤوس أبداً. |

كل ما يمكنك ضبطه عبر متغيرات البيئة يمكنك تمريره إلى العميل أيضاً، إلى جانب عنوان URL الأساسي والمهلة وإعادة المحاولة والرؤوس الافتراضية وعميل HTTP الخاص بك. أنشئ عميلاً واحداً لكل عملية وشاركه، فهو يحتفظ بمجموعة اتصالات، ويمكن استخدامه بأمان من عدة خيوط أو مهام في وقت واحد.

تستدعي طرق `account` ([التسجيل البرمجي](https://docs.didit.me/ar/integration/programmatic-registration.md): التسجيل وتسجيل الدخول والمؤسسات والتطبيقات) العنوان `https://apx.didit.me/auth/v2` ولا ترسل مفتاح API أبداً. سجّل الدخول عبر `account.login`، ثم مرّر رمز الوصول المُعاد إلى العميل بوصفه رمز الحساب.

## ما تفعله كل حزمة SDK

* **الموارد والطرق.** تتبع الاستدعاءات موارد الواجهة: `client.<resource>.<method>(...)`، مثل `sessions.create` أو `sessions.retrieve_decision` أو `transactions.create`، بصيغة الأحرف الخاصة بكل لغة. معرّفات المسار وسيطات موضعية، وجسم الطلب والاستعلام مجموعة واحدة من الحقول المسمّاة. تستخدم Python وNode.js وPHP وRuby أسماء الحقول الخاصة بالواجهة (`workflow_id`)، أما Go وJava و.NET فتستخدم صيغة لغتها (`WorkflowID` و`workflowId` و`WorkflowId`).
* **القوائم.** تتنقل طرق القوائم عبر كل النتائج نيابةً عنك (باستخدام `limit` و`offset` في الخلفية)، وتعرض كذلك كل صفحة مع `count` و`next` و`previous` و`results`. في Ruby، تمرّ `auto_paging_each` على كل الصفحات، وتقابل `total_count` و`next_url` و`previous_url` للصفحة الحقول `count` و`next` و`previous` في الواجهة.
* **الملفات.** تقبل عمليات الرفع (صور المستندات وصور السيلفي وإثبات العنوان والاستيراد) مساراً أو بايتات أو تدفقاً. أما عمليات التنزيل (ملفات PDF للجلسات والتقارير) فتعيد بايتات أو تدفقاً، ولا تعيد JSON محللاً أبداً.
* **التوافق المستقبلي.** يُحتفظ بأي حقل استجابة أو قيمة تعداد لا تعرفها نسخة الحزمة بعد، ويبقى قابلاً للقراءة، ولا يُعامَل كخطأ، فلا تكسر إضافة في واجهة برمجة التطبيقات تكاملاً منشوراً.
* **webhook.** يتحقق `webhooks.verify` من الرأسين `X-Signature-V2` و`X-Signature` ومن الطابع الزمني لعملية التسليم باستخدام سر webhook الخاص بك، ويعيد حدثاً مُنمَّطاً. يقبل قائمة أسرار أثناء تدوير أحدها. راجع [webhook](https://docs.didit.me/ar/integration/webhooks.md) لمخطط التوقيع.
* **المصادقة.** تتحقق مساعدة `Authentication` من رموز الوصول ورموز الهوية التي يوقّعها مُصدر Authentication لديك، وتستدعي endpoints الرموز والجلسات والتحقق المعزز الخاصة به. ولا تستخدم مفتاح API أبداً.

## الأخطاء وإعادة المحاولات والمهلات

| الخطأ | متى يحدث |
| - | - |
| `APIConnectionError`، `APITimeoutError` | لم تصل أي استجابة |
| `APIStatusError` | أي استجابة أخرى غير 2xx، مع الحالة والمحتوى المُحلَّل والرؤوس ومعرّف الطلب |
| `BadRequestError` 400، `AuthenticationError` 401، `PermissionDeniedError` 403، `NotFoundError` 404، `ConflictError` 409، `UnprocessableEntityError` 422، `RateLimitError` 429، `InternalServerError` 5xx | فئات فرعية من `APIStatusError` |
| `WebhookVerificationError` | فشل التحقق من تسليم webhook؛ ويوضح `reason` السبب |
| `ConfigurationError` | مفتاح API أو token الحساب أو معرّف المؤسسة أو معرّف التطبيق مفقود |

ترث جميع الأخطاء من `DiditError`. في Go، تُنفِّذ كل الأخطاء الواجهة `didit.Error` وكلٌّ منها من نوع مؤشر، مثل `*didit.NotFoundError`. تُسمّي Java وPHP و.NET الأخطاء بلاحقة `Exception` المعتادة لديها، وتكتب `API` على شكل `Api`: `DiditException` و`ApiStatusException` و`NotFoundException`.

تُعيد حزم SDK محاولة الطلب الفاشل حتى مرتين، مع تأخير متزايد أُسّياً يبدأ من 0.5 ثانية (عشوائية كاملة، بحد أقصى 8 ثوانٍ) مع مراعاة `Retry-After`. تُعاد محاولة طلبات `GET` و`HEAD` و`PUT` و`DELETE` عند أخطاء الاتصال وانتهاء المهلة و408 و429 و5xx. لا تُعاد محاولة طلبات `POST` و`PATCH` إلا عند 429 أو عندما يفشل الاتصال قبل إرسال الطلب، حتى لا تُنشئ إعادة المحاولة جلسة أو معاملة ثانية أبدًا. المهلة الافتراضية هي 60 ثانية. وتعرض كل استجابة أيضًا حالة HTTP الخام والرؤوس ومعرّف الطلب. راجع [تحديد المعدل](https://docs.didit.me/ar/integration/rate-limiting.md) للاطلاع على الحدود التي تقف وراء 429.

## الإصدارات والدعم

* تتبع حزم SDK الإصدار الدلالي (Semantic Versioning)، مع قاعدة واحدة لتغييرات API. التغيير الذي يعكس واجهة Didit API يُصدر كإصدار فرعي، حتى عندما قد يكسر الكود ذي الأنواع (حقل تغيّر نوعه، أو حقل يمكن أن يصبح فارغًا الآن، أو نقطة نهاية أو حقل أو قيمة تعداد أُزيلت). فواجهة API تتصرف بهذه الطريقة بالفعل مع كل المستدعين، لذا لا يكون إصدار أقدم من الحزمة أكثر أمانًا. وتدرج ملاحظات الإصدار هذه التغييرات تحت عنوان "تغييرات API قد تكسر الكود ذي الأنواع".
* لا يُستخدم الإصدار الرئيسي إلا لتغيير في تصميم الحزمة نفسه: إعادة تسمية طريقة أو مورد أو إزالته بينما تحتفظ API به، أو تغيير في إعدادات العميل أو الأخطاء أو إعادة المحاولات أو الترقيم أو سلوك التحقق من webhook، أو إسقاط إصدار بيئة التشغيل. عندما تغادر نقطة نهاية واجهة API أو تُعاد تسمية طريقتها، تبقى الطريقة القديمة لإصدار فرعي واحد على الأقل، وتُوسَم بأنها مُهمَلة، حتى يستمر كودك في البناء بينما تنتقل إلى الجديدة. تحتفظ كل لغة برقم إصدار خاص بها: Node.js وPHP وRuby على 2.x والباقي على 1.x، لأن هذه اللغات الثلاث أصدرت تغيير API كإصدار رئيسي قبل تطبيق هذه القاعدة.
* تُولَّد حزم SDK من عقد API المنشور ([`openapi-25.json`](https://docs.didit.me/openapi-25.json) و[`openapi-auth.json`](https://docs.didit.me/openapi-auth.json))، وتُفحص طرق [Didit Authentication](https://docs.didit.me/ar/authentication/overview.md) الخاصة بها مقابل [`openapi-authentication.json`](https://docs.didit.me/openapi-authentication.json). وتفحص الثلاثة كل يوم، لذا تصل نقطة نهاية أو حقل جديد ضمن إصدار منتظم لجميع حزم SDK السبع.
* تدعم كل حزمة الحد الأدنى من بيئة التشغيل الوارد في الجدول وكل إصدار أحدث منه. وتعمل اختباراتها على الحد الأدنى وعلى كل إصدار أحدث، أو على كل إصدار دعم طويل الأمد (LTS) بالنسبة إلى Node.js وJava.
* يسرد ملف `CHANGELOG.md` في كل مستودع التغييرات في كل إصدار.
* أبلغ عن مشكلة أمنية بشكل خاص عبر التنبيهات الأمنية في مستودع حزمة SDK، أو عبر [support@didit.me](mailto:support@didit.me).


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