مرجع API التاجر

دليل REST API الكامل لربط التحقق من المدفوعات في إيصالات بخادمك. جهّز محافظ التحصيل وأجهزة المراقبة، وأنشئ طلبات الدفع، وأرفق مرجع المحفظة من المشتري، واحصل على التحقق لحظياً عبر Webhooks.

هل تستخدم مكتبة تطوير؟مكتبات المتصفح وFlutter وReact Native تشترك في هذه الواجهة. تصفّح صفحة المكتبات.

الرابط الأساسي

https://api.esaalat.com/api/v1/merchant

POST /token · GET/POST /wallets/ · GET/POST /devices/ · POST /intents/ · GET/PATCH /intents/{id}/

شاهد التعليمات جرّب صفحة الدفع

نظرة عامة

واجهة Merchant REST API هي الطريقة التي يربط بها خادمك خدمة إيصالات. تنشئ طلب دفع بالمبلغ المحدد وبالمحفظة التي تريد التحصيل إليها. عندما يدفع المشتري، تظهر له المحفظة مرجع العملية. ترفق هذا المرجع بالطلب، فتتحقق إيصالات من الدفعة وتُشعرك عبر Webhook موقّع.

ما تحتاجه قبل البدء

•بيانات اعتماد من لوحة التحكم ← مفاتيح API، وهي client_id و client_secret تُعرض مرة واحدة فقط.
•محفظة تحصيل واحدة على الأقل، على هاتف يبقى تطبيق إيصالات يعمل عليه. المحفظة التي لا يراقبها جهاز لا يمكنها التحقق من أي دفعة.
•رابط متاح على الإنترنت العام لاستقبال Webhooks. أي عنوان محلي أو خاص لا يمكن لإيصالات الوصول إليه.
•خطوة دفع يستطيع المشتري أن يكتب فيها مرجع العملية الذي تعرضه له محفظته.

كيف يعمل

1أنشئ طلب دفع بتحديد المحفظة والمبلغ المطلوب.
2وجّه المشتري إلى صفحة الدفع المستضافة (pay_url)، أو اعرض المحفظة والمبلغ بنفسك.
3يدفع المشتري، فتعرض المحفظة مرجع العملية.
4يدخل المشتري المرجع في صفحتك، فترفقه بالطلب.
5تطابق إيصالات الدفعة (المحفظة + المرجع + المبلغ بالضبط) وتؤكد الطلب.
6يصل Webhook الخاص بك، وهنا تُطلق الطلب.

ملخص الـ Endpoints

الطريقة	المسار
POST	`/token`
GET	`/providers/`
GET	`/wallets/`
POST	`/wallets/`
GET/PATCH/DELETE	`/wallets/{id}/`
GET	`/devices/`
POST	`/devices/`
GET/PATCH/DELETE	`/devices/{id}/`
POST	`/devices/{id}/registration-code/`
POST	`/devices/{id}/attach-wallets/`
POST	`/devices/{id}/detach-wallets/`
POST	`/intents/`
GET	`/intents/`
GET	`/intents/{id}/`
PATCH	`/intents/{id}/`

المصادقة

سجّل دخولك ببيانات الاعتماد للحصول على JWT صالح لساعة. تجد بيانات الاعتماد في لوحة التحكم ← مفاتيح API.

POST/api/v1/merchant/token

بيانات اعتماد العميل

الاسم	النوع	مطلوب	الوصف
`client_id`	`نص`	مطلوب	معرّف عام يمكن تضمينه بأمان في تطبيقك.
`client_secret`	`نص`	مطلوب	يُعرض مرة واحدة فقط عند الإنشاء ولا يمكن استرجاعه لاحقاً. جدّد المفتاح من لوحة التحكم إذا تسرب.

الحصول على Token

cURL

curl -sS -X POST https://api.esaalat.com/api/v1/merchant/token \
  -H "ESAALAT-CLIENT-ID: <client_id>" \
  -H "ESAALAT-CLIENT-SECRET: <client_secret>"

الرمز صالح لمدة ساعة واحدة. استبدله عند انتهائه. يمنحك الرمز الوصول إلى محافظ وطلبات حسابك فقط.

حد الطلبات: 10 طلبات في الدقيقة.

عرض مزوّدي المحافظ

اجلب قائمة مزوّدي المحافظ الذين يمكنك فتح محافظ تحصيل لديهم. مرّر قيمة أي صف كـ provider_id عند إضافة محفظة. لا يظهر مزوّد الاختبار المخصص في القائمة أبداً.

GET/api/v1/merchant/providers/

حقول الاستجابة

الاسم	النوع	مطلوب	الوصف
`value`	`UUID`	اختياري	معرّف المزوّد. مرّره كقيمة `provider_id` عند إنشاء محفظة.
`label`	`نص`	اختياري	الاسم المعروض للمزوّد.
`reference_type`	`نص`	اختياري	reference أو phone أو name: ما يطلبه المزوّد من الدافع في المحفظة المباشرة. محافظ نقاط الوصول تستخدم مرجع العملية دائماً.
`name_only_reference`	`منطقي`	اختياري	true عندما تُعرَّف التحويلات باسم المُرسل وحده، فلا يمكن التمييز بين مُرسلين متشابهين بالمبلغ نفسه.
`name_parts`	`مصفوفة أعداد صحيحة`	اختياري	لمزوّدي `NAME`: أجزاء اسم المُرسل المطلوبة، مثل [1, 2] = الاسم الأول والثاني.

cURL

curl -sS https://api.esaalat.com/api/v1/merchant/providers/ \
  -H "Authorization: Bearer <access_token>"

عرض المحافظ المتاحة

قبل إنشاء طلب، احصل على قائمة المحافظ التي يمكنك التحصيل إليها. تُعاد المحافظ التي المراقبة مفعّلة فيها فقط. محفظة الاختبار مستثناة إلا إذا طلبتها عبر ?include_test=1.

إدارة المحافظ: يمكن أيضاً إضافة المحافظ وتعديلها وحذفها عبر الواجهة البرمجية. يُعيد GET الافتراضي مصفوفة بسيطة بالمحافظ الجاهزة للتحصيل الآن، وأضف ?all=1 لقائمة الإدارة: كل محافظ الحساب مع ترقيم صفحات ووسم collectable لكل صف. ويقبل الشكلان ?label=<value> (مطابقة تامة للوسم)، و ?provider=<uuid>، و ?search=<نص> (الاسم ورقم الحساب والوسم)، و ?ordering=name|created_at|label (أضف شرطة قبل الحقل لعكس الترتيب).

GET/api/v1/merchant/wallets/

حقول الاستجابة

الاسم	النوع	مطلوب	الوصف
`id`	`UUID`	اختياري	معرّف المحفظة. مرّره كقيمة wallet عند إنشاء الطلب.
`name / account_number`	`نص`	اختياري	الاسم الذي يراه المشتري، ورقم الحساب الذي يحوّل إليه المال.
`label`	`نص حتى 120 حرفاً`	اختياري	وسم تجميع حرّ يضبطه نظامك على المحفظة (مثل اسم التاجر "متجر أكمي"). يكون فارغاً إن لم يُضبط، ويمكن استرجاع مجموعة واحدة عبر `?label=<value>`.
`sender_names`	`قائمة نصوص`	اختياري	أسماء المُرسِلين التي تصل منها تنبيهات مدفوعات هذه المحفظة. قد يرسل المزوّد من أكثر من اسم، ويراقب الجهاز كل الأسماء.
`currency`	`نص`	اختياري	عملة المحفظة (ريال `YER` حالياً).
`provider`	`كائن`	اختياري	بيانات مزوّد المحفظة: الاسم المعروض واللون ورابط الشعار.
`is_test`	`منطقي`	اختياري	true لمحفظة الاختبار المخصصة لحسابك (تُعاد فقط مع `?include_test=1`).
`collectable`	`منطقي`	اختياري	true عندما تستطيع المحفظة التحقق من دفعة الآن (مفعّلة ولها جهاز مراقبة يعمل). تظهر فقط في قائمة الإدارة `?all=1`.

cURL

curl -sS https://api.esaalat.com/api/v1/merchant/wallets/ \
  -H "Authorization: Bearer <access_token>"

إضافة محفظة عبر `POST /wallets/`

الاسم	النوع	مطلوب	الوصف
`provider_id`	`UUID`	مطلوب	من `GET /providers`. لا يمكن اختيار مزوّد الاختبار المخصص.
`name`	`نص حتى 120 حرفاً`	مطلوب	اسم يظهر للتاجر، مثل "محفظة المتجر الرئيسية".
`account_number`	`نص حتى 120 حرفاً`	مطلوب	رقم الهاتف أو الحساب لدى المزوّد. يعود للتاجر ويجب أن يكون فريداً لكل مزوّد على حسابك.
`label`	`نص حتى 120 حرفاً`	اختياري	وسم تجميع حرّ اختياري، مثل اسم التاجر ("متجر أكمي"). يتيح لحساب واحد تجميع محافظ التحصيل الخاصة به واسترجاعها عبر `?label=<value>`، ويمكن تعديله لاحقاً بـ `PATCH`.
`is_access_point`	`منطقي`	اختياري	true (الافتراضي) = التحويلات تحمل مرجع عملية. false = محفظة مباشرة: رقم هاتف الدافع (أو اسمه حسب المزوّد) هو المرجع.
`daily_limit / monthly_limit`	`قيمة عشرية`	اختياري	حدود استلام معلوماتية اختيارية تُعرض في لوحة التحكم.

cURL — POST /wallets/

curl -sS -X POST https://api.esaalat.com/api/v1/merchant/wallets/ \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_id": "3f0a4b1e-0000-4000-8000-000000000002",
    "name": "Kuraimi - Main",
    "account_number": "777777777",
    "label": "Acme Store",
    "is_access_point": true
  }'

تُنشأ المحفظة على حسابك وتُحتسب من حصة المحافظ في خطتك (الأجهزة × عدد المزوّدين).

PATCH يغيّر الاسم والوسم والملاحظات. حقل is_active للقراءة فقط عبر الواجهة البرمجية: إيقاف المحفظة هو خطوة دورة الحياة التي تحرّر رقم الحساب وتفصل أجهزتها، لذلك الإزالة تكون بـ DELETE.

عند استدعاء DELETE /wallets/{id}/ تُؤرشف المحفظة ذات سجل المدفوعات (200 مع {"deactivated": true, "id"}) ويتحرر رقم حسابها لإعادة إضافته لاحقاً، أما المحفظة بلا سجل فتُحذف نهائياً (204).

أجهزة المراقبة

جهاز المراقبة هو هاتف الأندرويد الذي يراقب رسائل مدفوعات المحفظة ويبلّغ إيصالات عنها. المحفظة بلا جهاز يعمل فيه التنبيه لا يمكنها التحقق من أي دفعة أبداً، لذلك تُسجَّل المحافظ والأجهزة معاً. عند إنشاء جهاز يُعاد رمز تسجيل يُعرض هذه المرة الوحيدة فقط، ولأن النظام يخزّن بصمته فقط لا يمكن استرجاعه بعدها، فيدخّله شخص في تطبيق إيصالات على الهاتف الحامل لشريحة المحفظة.

POST/api/v1/merchant/devices/

إنشاء جهاز عبر `POST /devices/`

الاسم	النوع	مطلوب	الوصف
`name`	`نص حتى 120 حرفاً`	مطلوب	اسم يظهر للتاجر، مثل "هاتف المتجر".
`wallet_ids`	`مصفوفة UUID`	مطلوب	المحافظ التي يراقبها الجهاز. محفظة واحدة على الأقل، وكل المعرّفات يجب أن تعود لحسابك.

cURL

curl -sS -X POST https://api.esaalat.com/api/v1/merchant/devices/ \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Shop phone 1",
    "wallet_ids": ["b48249d2-9b34-4414-b20e-ffd8dfedaf89"]
  }'

الجهاز المُنشأ

الاسم	النوع	مطلوب	الوصف
`registration_code`	`نص`	اختياري	رمز تسجيل يعمل لمرة واحدة، ويُعرض مرة واحدة فقط، فانسخه فوراً.
`expires_in_minutes`	`عدد صحيح`	اختياري	ينتهي الرمز بعد 30 دقيقة. null = رمز بلا انتهاء (أجهزة خاصة موسومة في لوحة الإدارة).
`wallets`	`مصفوفة كائنات`	اختياري	المحافظ التي يراقبها الجهاز، ولكل واحدة معرّفها واسمها ووسمها ورقم حسابها وبيانات مزوّدها.

مسارات الأجهزة

•GET /devices/ — أجهزتك مع ترقيم صفحات. ?wallet=<uuid> يقيّد النتائج بأجهزة محفظة واحدة.
•GET /devices/{id}/ — جهاز واحد: الاسم، المحافظ، is_active، monitoring_enabled، last_seen_at.
•PATCH /devices/{id}/ — إعادة تسمية الجهاز: {"name": "الاسم الجديد"}.
•DELETE /devices/{id}/ — إزالة الجهاز (204). يتوقف رمز تطبيقه عن العمل ويُحفظ سجل المدفوعات.
•POST /devices/{id}/registration-code/ — إصدار رمز جديد لمرة واحدة (إعادة تسجيل الهاتف). الإصدار الجديد يُبطل رمز الجهاز الحالي، فيجب على الهاتف المرتبط سابقاً الربط من جديد.
•POST /devices/{id}/attach-wallets/ — إرفاق محافظ إضافية: {"wallet_ids": [...]}. لا يُصدر رمزاً جديداً. تُطبَّق حصة الخطة.
•POST /devices/{id}/detach-wallets/ — فصل محافظ: {"wallet_ids": [...]}. لا يمكن فصل آخر محفظة، فأزل الجهاز بدلاً من ذلك.

ملاحظات

•رمز التسجيل يُعرض مرة واحدة ولا يمكن استرجاعه لاحقاً، فالخيار الوحيد هو إعادة إصداره، وهو ما يُبطل رمز الجهاز الحالي.
•يجب أن يبقى للجهاز محفظة واحدة على الأقل حتى يستطيع المصادقة؛ فصل آخر محفظة مرفوض.
•إنشاء الأجهزة يُحتسب من حد الأجهزة في خطتك، وحصة المحافظ = الأجهزة × عدد المزوّدين.
•لا يمكن إرفاق محفظة الاختبار المخصصة بجهاز عبر الواجهة البرمجية.
•قيمتا monitoring_enabled و last_seen_at يأتيان من الهاتف نفسه، فلا يوجد في الـ API ما يُفعّل المراقبة عن بُعد؛ يفعّلها الشخص من التطبيق.

إنشاء طلب دفع

POST/api/v1/merchant/intents/

الـ Body

الاسم	النوع	مطلوب	الوصف
`wallet`	`UUID`	مطلوب	محفظة من حسابك مفعّلة فيها المراقبة. المحافظ التي المراقبة مفعّلة فيها فقط هي التي تستقبل المدفوعات.
`amount`	`قيمة عشرية`	اختياري	إجمالي المبلغ المطلوب تحصيله، مثل `"1234.56"`. مطلوب إذا لم تُرسل items.
`items`	`مصفوفة عناصر`	اختياري	بنود الطلب، ويُحتسب الإجمالي منها. مطلوبة إذا لم يُرسل amount. وإذا أُرسل كلاهما فسيُتجاهل amount.
`currency`	`نص`	اختياري	يدعم ريال `YER` فقط. يُفترض عملة المحفظة ويجب أن تطابقها.
`external_order_id`	`نص حتى 128 حرفاً`	اختياري	مرجع طلبك على نظامك، ويُعاد في كل استجابة، ويصل في حدث `payment.verified` باسم `order_id` فتطابق الدفعة مع طلبك دون أي استعلام.
`notes`	`نص حتى 500 حرف`	اختياري	ملاحظة حرة تُحفظ مع الطلب.

شكل عنصر items: price قيمة عشرية مطلوبة؛ quantity عدد صحيح ≥ 1 وقيمته الافتراضية 1.

قواعد التحقق

•يجب إرسال items أو amount.
•يجب أن تكون المحفظة من حسابك.
•يجب أن تكون المراقبة مفعّلة في المحفظة.
•يجب أن تطابق currency عملة المحفظة.
•يجب أن يكون المبلغ موجباً.
•تُطبَّق حصة الطلبات الشهرية المؤكدة لخطتك.
•ينتهي الطلب بعد ساعة واحدة، ويُعاد expires_at.

cURL

curl -sS -X POST https://api.esaalat.com/api/v1/merchant/intents/ \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -H "ESAALAT-IDEMPOTENCY-KEY: a1b2c3d4-0000-4000-8000-000000000001" \
  -d '{
    "wallet": "b48249d2-9b34-4414-b20e-ffd8dfedaf89",
    "amount": "1234.56",
    "currency": "YER",
    "external_order_id": "order-12345",
    "notes": "Optional note to the merchant"
  }'

Body

{
  "wallet": "b48249d2-9b34-4414-b20e-ffd8dfedaf89",
  "amount": "1234.56",
  "currency": "YER",
  "external_order_id": "order-12345",
  "notes": "Optional note to the merchant"
}

مدخل items[]

{
  "name": "Product name",        // required, ≤100 chars
  "description": "Optional",     // ≤500 chars
  "price": "1500.00",            // decimal string, required
  "quantity": 1                  // integer ≥ 1, default 1
}

منع التكرار (Idempotency): أرسل هيدر ESAALAT-IDEMPOTENCY-KEY بقيمة UUID عند الإنشاء لمنع تكرار الحجز عند إعادة المحاولة. إعادة إرسال نفس الطلب آمنة.

إرفاق مرجع المشتري

PATCH/api/v1/merchant/intents/{id}/

الـ Body

الاسم	النوع	مطلوب	الوصف
`reference`	`نص حتى 128 حرفاً`	مطلوب	مرجع عملية المحفظة، مع إزالة المسافات البيضاء.

cURL

curl -sS -X PATCH https://api.esaalat.com/api/v1/merchant/intents/<intent_id>/ \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"reference": "12345678"}'

Body

{
  "reference": "12345678"
}

ملاحظات

•الطلبات المعلّقة (PENDING) فقط هي التي تقبل مرجعاً. الطلبات المؤكدة والمنتهية والملغاة وذات المبلغ الخاطئ نهائية (400).
•إعادة الإرفاق أثناء الانتظار تستبدل المرجع السابق ببساطة.
•إذا سبق أن وصلت رسالة المحفظة إلى إيصالات قبل إرفاقك المرجع، فقد تجد الطلب مؤكداً (VERIFIED) في الاستجابة.
•إعادة استخدام مرجع يعود لطلب آخر على نفس المحفظة مقبولة لكنها مُعلَّمة (duplicate_reference: true) حتى لا يُحجز الطلب مرتين دون قصد.

عرض الطلبات وتصفيتها

اعرض طلباتك من الأحدث إلى الأقدم، ومقيدة دائماً بحسابك. 20 طلباً في الصفحة افتراضياً؛ ويمكن التحكم بالترقيم عبر ?page_size= (الحد الأقصى 100) و ?page=.

GET/api/v1/merchant/intents/

Query Parameters

الاسم	النوع	مطلوب	الوصف
`status`	`قائمة مفصولة بفواصل`	اختياري	`PENDING`, `VERIFIED`, `EXPIRED`, `CANCELLED`, `WRONG_AMOUNT`. مثال: `?status=VERIFIED,WRONG_AMOUNT`. قيمة غير صالحة → `400`.
`code`	`نص`	اختياري	رقم الدفع بالضبط، مثال: `?code=P7K4X92`
`reference`	`نص`	اختياري	مرجع المحفظة بالضبط، مثال: `?reference=12345678`
`external_order_id`	`نص`	اختياري	مرجع طلبك على نظامك (مطابقة تامة)، كما أرسلته عند الإنشاء.
`wallet`	`UUID`	اختياري	تقييد النتائج بمحفظة واحدة.
`created_after`	`ISO 8601`	اختياري	يشمل التواريخ من هذه اللحظة (>=).
`created_before`	`ISO 8601`	اختياري	يشمل التواريخ حتى هذه اللحظة (<=).
`search`	`نص`	اختياري	نص حر يطابق reference أو code أو `external_order_id`.
`ordering`	`نص`	اختياري	`created_at`، `verified_at`، `payable_amount`، `status`. أضف `-` قبل الحقل لعكس الترتيب.

cURL

curl -sS "https://api.esaalat.com/api/v1/merchant/intents/?status=VERIFIED&created_after=2026-09-09T00:00:00Z&page_size=100" \
  -H "Authorization: Bearer <access_token>"

استرجاع طلب واحد

احصل على الحالة الحالية وتفاصيل طلب واحد. أي طلب من حساب آخر يعيد 404.

GET/api/v1/merchant/intents/{id}/

الحقول الأساسية

الاسم	النوع	مطلوب	الوصف
`status`	`نص`	اختياري	مصدر الحقيقة لديك: إحدى الحالات المذكورة أدناه.
`paid_amount`	`قيمة عشرية`	اختياري	يُعيّن فقط عندما تكون الحالة `WRONG_AMOUNT`، ويوضّح المبلغ الذي أرسله المشتري فعلياً.
`matched_event`	`كائن`	اختياري	حدث الدفع المطابق الذي أكّد الطلب (مرجعه ومبلغه ومرسله).
`device`	`كائن`	اختياري	الجهاز الذي أبلغ عن الدفعة. يبقى المعرّف ثابتاً حتى عند تجديد رمز الجهاز.
`manual_override / collected_manually`	`منطقي`	اختياري	true عندما يحصّل التاجر الدفعة يدوياً من قائمة غير المطابقة.

cURL

curl -sS https://api.esaalat.com/api/v1/merchant/intents/<intent_id>/ \
  -H "Authorization: Bearer <access_token>"

200 OK

{
  "id": "dd157a06-a065-475d-8723-d98a61698aa0",
  "code": "P7K4X92",
  "external_order_id": "order-12345",
  "reference": "12345678",
  "status": "VERIFIED",
  "base_amount": "1234.56",
  "payable_amount": "1234.56",
  "paid_amount": null,
  "currency": "YER",
  "items": [
    {
      "name": "Product name",
      "description": "",
      "price": "1234.56",
      "quantity": 1,
      "total_price": "1234.56"
    }
  ],
  "notes": "",
  "wallet": {
    "id": "b48249d2-9b34-4414-b20e-ffd8dfedaf89",
    "name": "Kuraimi - Main",
    "label": "Acme Store",
    "sender_names": ["Kuraimi", "Kuraimi Bank"],
    "is_test": false,
    "sim_slot": "SIM 1",
    "account_number": "777777777"
  },
  "provider": {
    "id": "3f0a4b1e-0000-4000-8000-000000000002",
    "name": "KURAIMI",
    "display_name": "Kuraimi",
    "theme_color": "#0b8f4c",
    "logo_url": "https://<cdn>/kuraimi_256.png",
    "provider_status": "ACTIVE"
  },
  "expires_at": "2026-09-09T14:30:00+03:00",
  "created_at": "2026-09-09T13:30:00.123456+03:00",
  "verified_at": "2026-09-09T13:41:22.654321+03:00",
  "manual_override": false,
  "collected_manually": false,
  "matched_event": {
    "id": "32fd9972-71fd-4b87-82ce-501061ab7c5d",
    "amount": "1234.56",
    "sender": "777777777",
    "reference": "12345678",
    "created_at": "2026-09-09T13:41:21+03:00"
  },
  "device": {
    "id": "5a1f6c3d-0000-4000-8000-000000000004",
    "name": "Shop phone 1"
  },
  "subscription": null
}

حالات الطلب

الاسم	الوصف	Terminal
`PENDING`	أُنشئ الطلب بانتظار دفعة المشتري والمرجع.	—
`VERIFIED`	تم اكتشاف الدفعة ومطابقتها (المحفظة + المرجع + المبلغ بالضبط).	Terminal
`WRONG_AMOUNT`	طابق المرجع لكن المبلغ المدفوع يختلف عن المبلغ المطلوب. يسجّل `paid_amount` ما وصل، ولا يُؤكد الطلب تلقائياً، فعلى المشتري التواصل معك.	Terminal
`EXPIRED`	انتهت مهلة الساعة دون تحقق.	Terminal
`CANCELLED`	أُلغي من قبل التاجر (لوحة التحكم).	Terminal

Webhooks

تُعد Webhooks القناة الأساسية للتحقق؛ استخدم مسارات العرض والاسترجاع للمراجعة اللاحقة. اضبط الـ endpoints من لوحة التحكم ← Webhooks، ويمكن تقييدها بمحفظة معينة.

التحقق من التوقيع

يحمل كل طلب هيدر X-Esaalat-Signature بالصيغة t=<unix-ts>,v1=<hex>. قيمة v1 هي HMAC-SHA256 لـ "{ts}.{raw_body}" باستخدام سر الـ endpoint لديك. تجد السر في لوحة التحكم ← Webhooks، ويُعرض مرة واحدة عند إضافة الـ endpoint فانسخه حينها، و«توليد سر جديد» يستبدله بسر آخر. قارن دائماً بـ hmac.compare_digest، ويمكنك رفض الطلبات الأقدم من ~5 دقائق كحماية من إعادة التشغيل.

verify_signature.py

import hashlib, hmac

def verify_signature(secret: str, body: bytes, signature: str) -> bool:
    ts, v1 = (p.split("=", 1)[1] for p in signature.split(","))
    digest = hmac.new(
        secret.encode(), f"{ts}.{body.decode()}".encode(), hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(digest, v1)

رابط الـ Endpoint

•يجب أن يكون الوصول إليه ممكناً من الإنترنت العام عبر HTTP(S). عناوين localhost والشبكات المحلية وأي رابط تطوير بلا نفق لا يستقبل شيئاً.
•يجب أن يعيد 2xx في غضون 6 ثوانٍ. أي استجابة أخرى تُحسب فشلاً وتبدأ جدول إعادة المحاولة.
•سر الـ endpoint تجده في لوحة التحكم ← Webhooks، ويُعرض مرة واحدة عند إضافته. استخدمه للتحقق من التوقيع.
•تُجدول الإرسالات لحظة وصول الدفعة. الدفعات التي جرت قبل إضافة الـ endpoint لا تُرسل متأخرة أبداً، فلا يوجد استرجاع لاحق.
•تفعيل «إشعار بالمدفوعات غير المطابقة» يرسل أيضاً payment.unmatched إلى ذلك الـ endpoint. الإضافة لا تمسّ بقية الأحداث.

الأحداث

WEBHOOKpayment.verified

الحدث الرئيسي: تم التحقق من الدفعة، تلقائياً أو يدوياً. يحمل الحقل order_id قيمة external_order_id التي أرسلتها مع الطلب، ويكون فارغاً إن لم ترسلها، فيربط الحدث الدفعة بطلبك مباشرة.

بيانات الحدث

{
  "event": "payment.verified",
  "payment_id": "P7K4X92",
  "intent_id": "dd157a06-a065-475d-8723-d98a61698aa0",
  "order_id": "order-12345",
  "reference": "12345678",
  "base_amount": "1234.56",
  "amount": "1234.56",
  "currency": "YER",
  "status": "VERIFIED",
  "verified_at": "2026-09-09T13:41:22+03:00",
  "manual_override": false
}

WEBHOOKpayment.unmatched (اختياري)

وصل مبلغ إلى محفظة حقيقية دون أن يطالب به أي طلب. يُرسل فقط إذا فعّلت الـ endpoint هذا الخيار صراحةً. لا يُطلق أبداً لمحفظة الاختبار. ولا يوجد order_id في هذا الحدث، فطلب لم تنشئه لا يحمل مرجعك.

بيانات الحدث

{
  "event": "payment.unmatched",
  "event_id": "32fd9972-71fd-4b87-82ce-501061ab7c5d",
  "reference": "12345678",
  "amount": "1234.56",
  "currency": "YER",
  "wallet": "Kuraimi - Main",
  "received_at": "2026-09-09T13:41:21+03:00",
  "is_test": false
}

WEBHOOKpayment.received (لمحفظة الاختبار فقط)

يُطلق عند أي دفعة تصل إلى محفظة الاختبار، حتى بدون إنشاء طلب. يتيح لك اختبار التكامل بالكامل عبر محفظة الاختبار. ولا يحمل هذا الحدث order_id أيضاً، فقد لا يكون للدفعة طلب من الأساس.

بيانات الحدث

{
  "event": "payment.received",
  "event_id": "32fd9972-71fd-4b87-82ce-501061ab7c5d",
  "reference": "12345678",
  "amount": "1234.56",
  "currency": "YER",
  "resolution": "UNMATCHED",
  "received_at": "2026-09-09T13:41:21+03:00",
  "is_test": true
}

ضمانات التسليم

•إعادة المحاولة عند الفشل: بعد 5 دقائق ثم 30 دقيقة ثم ساعتين ثم 12 ساعة ثم 24 ساعة، وبعدها تتوقف إيصالات عن المحاولة.
•الـ endpoints المعطّلة لا تستقبل أي شيء.
•الـ endpoints المقيدة بمحفظة تستقبل أحداثها فقط؛ وغير المقيدة تستقبل كل أحداث الحساب.
•قد تتكرر عمليات التسليم (مثل محاولة وصلت فعلاً)، اجعل معالجك يتحمّل التكرار عبر intent_id / event_id.
•استجب بـ 2xx للتأكيد؛ أي استجابة أخرى تُجدول إعادة المحاولة التالية.

حدود الطلبات

تُقيَّد الطلبات لكل بيانات اعتماد على حدة. عند تجاوز الحد تستلم 429 مع هيدر Retry-After. تعامل معها بسلاسة.

المسار	الحد اللحظي	الحد اليومي
`POST /token`	10/دقيقة	500/يوم
`POST /intents/, GET/PATCH /intents/{id}/`	240/دقيقة (~4 طلبات/ثانية)	50,000/يوم
`GET /intents/ (قائمة)`	60/دقيقة	50,000/يوم
`GET /providers/، GET/POST /wallets/، GET/PATCH/DELETE /wallets/{id}/`	240/دقيقة (~4 طلبات/ثانية)	50,000/يوم
`GET/POST /devices/، GET/PATCH/DELETE /devices/{id}/، POST /devices/{id}/…`	240/دقيقة (~4 طلبات/ثانية)	50,000/يوم

الأخطاء

يتبع كل خطأ صيغة موحّدة:

صيغة الخطأ

{
  "type": "validation_error",
  "errors": [
    { "code": "required", "detail": "This field is required.", "attr": "wallet" }
  ]
}

رموز حالة HTTP

الاسم	الوصف
`400`	محتوى غير صالح، محفظة غير معروفة، عامل تصفية غير صحيح، مراقبة غير مفعّلة في المحفظة، مرجع على طلب غير معلّق، أو تجاوز الحصة.
`401`	رمز `Bearer` مفقود أو غير صالح أو منتهي.
`403`	استخدام رمز لوحة التحكم (مستخدم) على مسارات التاجر. يلزم رمز بيانات الاعتماد.
`404`	معرّف طلب غير معروف (أو طلب من حساب آخر).
`429`	تم تجاوز حد الطلبات. احترم هيدر `Retry-After`.
`500`	حدث خطأ داخلي. أبلغنا عنه.

لأفضل تجربة، استخدم النسخة الإنجليزية

مرجع API التاجر

هل تستخدم مكتبة تطوير؟مكتبات المتصفح وFlutter وReact Native تشترك في هذه الواجهة. تصفّح صفحة المكتبات.

الرابط الأساسي

https://api.esaalat.com/api/v1/merchant

POST /token · GET/POST /wallets/ · GET/POST /devices/ · POST /intents/ · GET/PATCH /intents/{id}/

شاهد التعليمات جرّب صفحة الدفع

نظرة عامة

ما تحتاجه قبل البدء

•بيانات اعتماد من لوحة التحكم ← مفاتيح API، وهي client_id و client_secret تُعرض مرة واحدة فقط.
•محفظة تحصيل واحدة على الأقل، على هاتف يبقى تطبيق إيصالات يعمل عليه. المحفظة التي لا يراقبها جهاز لا يمكنها التحقق من أي دفعة.
•رابط متاح على الإنترنت العام لاستقبال Webhooks. أي عنوان محلي أو خاص لا يمكن لإيصالات الوصول إليه.
•خطوة دفع يستطيع المشتري أن يكتب فيها مرجع العملية الذي تعرضه له محفظته.

كيف يعمل

1أنشئ طلب دفع بتحديد المحفظة والمبلغ المطلوب.
2وجّه المشتري إلى صفحة الدفع المستضافة (pay_url)، أو اعرض المحفظة والمبلغ بنفسك.
3يدفع المشتري، فتعرض المحفظة مرجع العملية.
4يدخل المشتري المرجع في صفحتك، فترفقه بالطلب.
5تطابق إيصالات الدفعة (المحفظة + المرجع + المبلغ بالضبط) وتؤكد الطلب.
6يصل Webhook الخاص بك، وهنا تُطلق الطلب.

ملخص الـ Endpoints

الطريقة	المسار
POST	`/token`
GET	`/providers/`
GET	`/wallets/`
POST	`/wallets/`
GET/PATCH/DELETE	`/wallets/{id}/`
GET	`/devices/`
POST	`/devices/`
GET/PATCH/DELETE	`/devices/{id}/`
POST	`/devices/{id}/registration-code/`
POST	`/devices/{id}/attach-wallets/`
POST	`/devices/{id}/detach-wallets/`
POST	`/intents/`
GET	`/intents/`
GET	`/intents/{id}/`
PATCH	`/intents/{id}/`

المصادقة

سجّل دخولك ببيانات الاعتماد للحصول على JWT صالح لساعة. تجد بيانات الاعتماد في لوحة التحكم ← مفاتيح API.

POST/api/v1/merchant/token

بيانات اعتماد العميل

الاسم	النوع	مطلوب	الوصف
`client_id`	`نص`	مطلوب	معرّف عام يمكن تضمينه بأمان في تطبيقك.
`client_secret`	`نص`	مطلوب	يُعرض مرة واحدة فقط عند الإنشاء ولا يمكن استرجاعه لاحقاً. جدّد المفتاح من لوحة التحكم إذا تسرب.

الحصول على Token

cURL

curl -sS -X POST https://api.esaalat.com/api/v1/merchant/token \
  -H "ESAALAT-CLIENT-ID: <client_id>" \
  -H "ESAALAT-CLIENT-SECRET: <client_secret>"

الرمز صالح لمدة ساعة واحدة. استبدله عند انتهائه. يمنحك الرمز الوصول إلى محافظ وطلبات حسابك فقط.

حد الطلبات: 10 طلبات في الدقيقة.

عرض مزوّدي المحافظ

GET/api/v1/merchant/providers/

حقول الاستجابة

الاسم	النوع	مطلوب	الوصف
`value`	`UUID`	اختياري	معرّف المزوّد. مرّره كقيمة `provider_id` عند إنشاء محفظة.
`label`	`نص`	اختياري	الاسم المعروض للمزوّد.
`reference_type`	`نص`	اختياري	reference أو phone أو name: ما يطلبه المزوّد من الدافع في المحفظة المباشرة. محافظ نقاط الوصول تستخدم مرجع العملية دائماً.
`name_only_reference`	`منطقي`	اختياري	true عندما تُعرَّف التحويلات باسم المُرسل وحده، فلا يمكن التمييز بين مُرسلين متشابهين بالمبلغ نفسه.
`name_parts`	`مصفوفة أعداد صحيحة`	اختياري	لمزوّدي `NAME`: أجزاء اسم المُرسل المطلوبة، مثل [1, 2] = الاسم الأول والثاني.

cURL

curl -sS https://api.esaalat.com/api/v1/merchant/providers/ \
  -H "Authorization: Bearer <access_token>"

عرض المحافظ المتاحة

GET/api/v1/merchant/wallets/

حقول الاستجابة

الاسم	النوع	مطلوب	الوصف
`id`	`UUID`	اختياري	معرّف المحفظة. مرّره كقيمة wallet عند إنشاء الطلب.
`name / account_number`	`نص`	اختياري	الاسم الذي يراه المشتري، ورقم الحساب الذي يحوّل إليه المال.
`label`	`نص حتى 120 حرفاً`	اختياري	وسم تجميع حرّ يضبطه نظامك على المحفظة (مثل اسم التاجر "متجر أكمي"). يكون فارغاً إن لم يُضبط، ويمكن استرجاع مجموعة واحدة عبر `?label=<value>`.
`sender_names`	`قائمة نصوص`	اختياري	أسماء المُرسِلين التي تصل منها تنبيهات مدفوعات هذه المحفظة. قد يرسل المزوّد من أكثر من اسم، ويراقب الجهاز كل الأسماء.
`currency`	`نص`	اختياري	عملة المحفظة (ريال `YER` حالياً).
`provider`	`كائن`	اختياري	بيانات مزوّد المحفظة: الاسم المعروض واللون ورابط الشعار.
`is_test`	`منطقي`	اختياري	true لمحفظة الاختبار المخصصة لحسابك (تُعاد فقط مع `?include_test=1`).
`collectable`	`منطقي`	اختياري	true عندما تستطيع المحفظة التحقق من دفعة الآن (مفعّلة ولها جهاز مراقبة يعمل). تظهر فقط في قائمة الإدارة `?all=1`.

cURL

curl -sS https://api.esaalat.com/api/v1/merchant/wallets/ \
  -H "Authorization: Bearer <access_token>"

إضافة محفظة عبر `POST /wallets/`

الاسم	النوع	مطلوب	الوصف
`provider_id`	`UUID`	مطلوب	من `GET /providers`. لا يمكن اختيار مزوّد الاختبار المخصص.
`name`	`نص حتى 120 حرفاً`	مطلوب	اسم يظهر للتاجر، مثل "محفظة المتجر الرئيسية".
`account_number`	`نص حتى 120 حرفاً`	مطلوب	رقم الهاتف أو الحساب لدى المزوّد. يعود للتاجر ويجب أن يكون فريداً لكل مزوّد على حسابك.
`label`	`نص حتى 120 حرفاً`	اختياري	وسم تجميع حرّ اختياري، مثل اسم التاجر ("متجر أكمي"). يتيح لحساب واحد تجميع محافظ التحصيل الخاصة به واسترجاعها عبر `?label=<value>`، ويمكن تعديله لاحقاً بـ `PATCH`.
`is_access_point`	`منطقي`	اختياري	true (الافتراضي) = التحويلات تحمل مرجع عملية. false = محفظة مباشرة: رقم هاتف الدافع (أو اسمه حسب المزوّد) هو المرجع.
`daily_limit / monthly_limit`	`قيمة عشرية`	اختياري	حدود استلام معلوماتية اختيارية تُعرض في لوحة التحكم.

cURL — POST /wallets/

curl -sS -X POST https://api.esaalat.com/api/v1/merchant/wallets/ \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_id": "3f0a4b1e-0000-4000-8000-000000000002",
    "name": "Kuraimi - Main",
    "account_number": "777777777",
    "label": "Acme Store",
    "is_access_point": true
  }'

تُنشأ المحفظة على حسابك وتُحتسب من حصة المحافظ في خطتك (الأجهزة × عدد المزوّدين).

أجهزة المراقبة

POST/api/v1/merchant/devices/

إنشاء جهاز عبر `POST /devices/`

الاسم	النوع	مطلوب	الوصف
`name`	`نص حتى 120 حرفاً`	مطلوب	اسم يظهر للتاجر، مثل "هاتف المتجر".
`wallet_ids`	`مصفوفة UUID`	مطلوب	المحافظ التي يراقبها الجهاز. محفظة واحدة على الأقل، وكل المعرّفات يجب أن تعود لحسابك.

cURL

curl -sS -X POST https://api.esaalat.com/api/v1/merchant/devices/ \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Shop phone 1",
    "wallet_ids": ["b48249d2-9b34-4414-b20e-ffd8dfedaf89"]
  }'

الجهاز المُنشأ

الاسم	النوع	مطلوب	الوصف
`registration_code`	`نص`	اختياري	رمز تسجيل يعمل لمرة واحدة، ويُعرض مرة واحدة فقط، فانسخه فوراً.
`expires_in_minutes`	`عدد صحيح`	اختياري	ينتهي الرمز بعد 30 دقيقة. null = رمز بلا انتهاء (أجهزة خاصة موسومة في لوحة الإدارة).
`wallets`	`مصفوفة كائنات`	اختياري	المحافظ التي يراقبها الجهاز، ولكل واحدة معرّفها واسمها ووسمها ورقم حسابها وبيانات مزوّدها.

مسارات الأجهزة

•GET /devices/ — أجهزتك مع ترقيم صفحات. ?wallet=<uuid> يقيّد النتائج بأجهزة محفظة واحدة.
•GET /devices/{id}/ — جهاز واحد: الاسم، المحافظ، is_active، monitoring_enabled، last_seen_at.
•PATCH /devices/{id}/ — إعادة تسمية الجهاز: {"name": "الاسم الجديد"}.
•DELETE /devices/{id}/ — إزالة الجهاز (204). يتوقف رمز تطبيقه عن العمل ويُحفظ سجل المدفوعات.
•POST /devices/{id}/registration-code/ — إصدار رمز جديد لمرة واحدة (إعادة تسجيل الهاتف). الإصدار الجديد يُبطل رمز الجهاز الحالي، فيجب على الهاتف المرتبط سابقاً الربط من جديد.
•POST /devices/{id}/attach-wallets/ — إرفاق محافظ إضافية: {"wallet_ids": [...]}. لا يُصدر رمزاً جديداً. تُطبَّق حصة الخطة.
•POST /devices/{id}/detach-wallets/ — فصل محافظ: {"wallet_ids": [...]}. لا يمكن فصل آخر محفظة، فأزل الجهاز بدلاً من ذلك.

ملاحظات

•رمز التسجيل يُعرض مرة واحدة ولا يمكن استرجاعه لاحقاً، فالخيار الوحيد هو إعادة إصداره، وهو ما يُبطل رمز الجهاز الحالي.
•يجب أن يبقى للجهاز محفظة واحدة على الأقل حتى يستطيع المصادقة؛ فصل آخر محفظة مرفوض.
•إنشاء الأجهزة يُحتسب من حد الأجهزة في خطتك، وحصة المحافظ = الأجهزة × عدد المزوّدين.
•لا يمكن إرفاق محفظة الاختبار المخصصة بجهاز عبر الواجهة البرمجية.
•قيمتا monitoring_enabled و last_seen_at يأتيان من الهاتف نفسه، فلا يوجد في الـ API ما يُفعّل المراقبة عن بُعد؛ يفعّلها الشخص من التطبيق.

إنشاء طلب دفع

POST/api/v1/merchant/intents/

الـ Body

الاسم	النوع	مطلوب	الوصف
`wallet`	`UUID`	مطلوب	محفظة من حسابك مفعّلة فيها المراقبة. المحافظ التي المراقبة مفعّلة فيها فقط هي التي تستقبل المدفوعات.
`amount`	`قيمة عشرية`	اختياري	إجمالي المبلغ المطلوب تحصيله، مثل `"1234.56"`. مطلوب إذا لم تُرسل items.
`items`	`مصفوفة عناصر`	اختياري	بنود الطلب، ويُحتسب الإجمالي منها. مطلوبة إذا لم يُرسل amount. وإذا أُرسل كلاهما فسيُتجاهل amount.
`currency`	`نص`	اختياري	يدعم ريال `YER` فقط. يُفترض عملة المحفظة ويجب أن تطابقها.
`external_order_id`	`نص حتى 128 حرفاً`	اختياري	مرجع طلبك على نظامك، ويُعاد في كل استجابة، ويصل في حدث `payment.verified` باسم `order_id` فتطابق الدفعة مع طلبك دون أي استعلام.
`notes`	`نص حتى 500 حرف`	اختياري	ملاحظة حرة تُحفظ مع الطلب.

شكل عنصر items: price قيمة عشرية مطلوبة؛ quantity عدد صحيح ≥ 1 وقيمته الافتراضية 1.

قواعد التحقق

•يجب إرسال items أو amount.
•يجب أن تكون المحفظة من حسابك.
•يجب أن تكون المراقبة مفعّلة في المحفظة.
•يجب أن تطابق currency عملة المحفظة.
•يجب أن يكون المبلغ موجباً.
•تُطبَّق حصة الطلبات الشهرية المؤكدة لخطتك.
•ينتهي الطلب بعد ساعة واحدة، ويُعاد expires_at.

cURL

curl -sS -X POST https://api.esaalat.com/api/v1/merchant/intents/ \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -H "ESAALAT-IDEMPOTENCY-KEY: a1b2c3d4-0000-4000-8000-000000000001" \
  -d '{
    "wallet": "b48249d2-9b34-4414-b20e-ffd8dfedaf89",
    "amount": "1234.56",
    "currency": "YER",
    "external_order_id": "order-12345",
    "notes": "Optional note to the merchant"
  }'

Body

{
  "wallet": "b48249d2-9b34-4414-b20e-ffd8dfedaf89",
  "amount": "1234.56",
  "currency": "YER",
  "external_order_id": "order-12345",
  "notes": "Optional note to the merchant"
}

مدخل items[]

{
  "name": "Product name",        // required, ≤100 chars
  "description": "Optional",     // ≤500 chars
  "price": "1500.00",            // decimal string, required
  "quantity": 1                  // integer ≥ 1, default 1
}

إرفاق مرجع المشتري

PATCH/api/v1/merchant/intents/{id}/

الـ Body

الاسم	النوع	مطلوب	الوصف
`reference`	`نص حتى 128 حرفاً`	مطلوب	مرجع عملية المحفظة، مع إزالة المسافات البيضاء.

cURL

curl -sS -X PATCH https://api.esaalat.com/api/v1/merchant/intents/<intent_id>/ \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"reference": "12345678"}'

Body

{
  "reference": "12345678"
}

ملاحظات

•الطلبات المعلّقة (PENDING) فقط هي التي تقبل مرجعاً. الطلبات المؤكدة والمنتهية والملغاة وذات المبلغ الخاطئ نهائية (400).
•إعادة الإرفاق أثناء الانتظار تستبدل المرجع السابق ببساطة.
•إذا سبق أن وصلت رسالة المحفظة إلى إيصالات قبل إرفاقك المرجع، فقد تجد الطلب مؤكداً (VERIFIED) في الاستجابة.
•إعادة استخدام مرجع يعود لطلب آخر على نفس المحفظة مقبولة لكنها مُعلَّمة (duplicate_reference: true) حتى لا يُحجز الطلب مرتين دون قصد.

عرض الطلبات وتصفيتها

GET/api/v1/merchant/intents/

Query Parameters

الاسم	النوع	مطلوب	الوصف
`status`	`قائمة مفصولة بفواصل`	اختياري	`PENDING`, `VERIFIED`, `EXPIRED`, `CANCELLED`, `WRONG_AMOUNT`. مثال: `?status=VERIFIED,WRONG_AMOUNT`. قيمة غير صالحة → `400`.
`code`	`نص`	اختياري	رقم الدفع بالضبط، مثال: `?code=P7K4X92`
`reference`	`نص`	اختياري	مرجع المحفظة بالضبط، مثال: `?reference=12345678`
`external_order_id`	`نص`	اختياري	مرجع طلبك على نظامك (مطابقة تامة)، كما أرسلته عند الإنشاء.
`wallet`	`UUID`	اختياري	تقييد النتائج بمحفظة واحدة.
`created_after`	`ISO 8601`	اختياري	يشمل التواريخ من هذه اللحظة (>=).
`created_before`	`ISO 8601`	اختياري	يشمل التواريخ حتى هذه اللحظة (<=).
`search`	`نص`	اختياري	نص حر يطابق reference أو code أو `external_order_id`.
`ordering`	`نص`	اختياري	`created_at`، `verified_at`، `payable_amount`، `status`. أضف `-` قبل الحقل لعكس الترتيب.

cURL

curl -sS "https://api.esaalat.com/api/v1/merchant/intents/?status=VERIFIED&created_after=2026-09-09T00:00:00Z&page_size=100" \
  -H "Authorization: Bearer <access_token>"

استرجاع طلب واحد

احصل على الحالة الحالية وتفاصيل طلب واحد. أي طلب من حساب آخر يعيد 404.

GET/api/v1/merchant/intents/{id}/

الحقول الأساسية

الاسم	النوع	مطلوب	الوصف
`status`	`نص`	اختياري	مصدر الحقيقة لديك: إحدى الحالات المذكورة أدناه.
`paid_amount`	`قيمة عشرية`	اختياري	يُعيّن فقط عندما تكون الحالة `WRONG_AMOUNT`، ويوضّح المبلغ الذي أرسله المشتري فعلياً.
`matched_event`	`كائن`	اختياري	حدث الدفع المطابق الذي أكّد الطلب (مرجعه ومبلغه ومرسله).
`device`	`كائن`	اختياري	الجهاز الذي أبلغ عن الدفعة. يبقى المعرّف ثابتاً حتى عند تجديد رمز الجهاز.
`manual_override / collected_manually`	`منطقي`	اختياري	true عندما يحصّل التاجر الدفعة يدوياً من قائمة غير المطابقة.

cURL

curl -sS https://api.esaalat.com/api/v1/merchant/intents/<intent_id>/ \
  -H "Authorization: Bearer <access_token>"

200 OK

{
  "id": "dd157a06-a065-475d-8723-d98a61698aa0",
  "code": "P7K4X92",
  "external_order_id": "order-12345",
  "reference": "12345678",
  "status": "VERIFIED",
  "base_amount": "1234.56",
  "payable_amount": "1234.56",
  "paid_amount": null,
  "currency": "YER",
  "items": [
    {
      "name": "Product name",
      "description": "",
      "price": "1234.56",
      "quantity": 1,
      "total_price": "1234.56"
    }
  ],
  "notes": "",
  "wallet": {
    "id": "b48249d2-9b34-4414-b20e-ffd8dfedaf89",
    "name": "Kuraimi - Main",
    "label": "Acme Store",
    "sender_names": ["Kuraimi", "Kuraimi Bank"],
    "is_test": false,
    "sim_slot": "SIM 1",
    "account_number": "777777777"
  },
  "provider": {
    "id": "3f0a4b1e-0000-4000-8000-000000000002",
    "name": "KURAIMI",
    "display_name": "Kuraimi",
    "theme_color": "#0b8f4c",
    "logo_url": "https://<cdn>/kuraimi_256.png",
    "provider_status": "ACTIVE"
  },
  "expires_at": "2026-09-09T14:30:00+03:00",
  "created_at": "2026-09-09T13:30:00.123456+03:00",
  "verified_at": "2026-09-09T13:41:22.654321+03:00",
  "manual_override": false,
  "collected_manually": false,
  "matched_event": {
    "id": "32fd9972-71fd-4b87-82ce-501061ab7c5d",
    "amount": "1234.56",
    "sender": "777777777",
    "reference": "12345678",
    "created_at": "2026-09-09T13:41:21+03:00"
  },
  "device": {
    "id": "5a1f6c3d-0000-4000-8000-000000000004",
    "name": "Shop phone 1"
  },
  "subscription": null
}

حالات الطلب

الاسم	الوصف	Terminal
`PENDING`	أُنشئ الطلب بانتظار دفعة المشتري والمرجع.	—
`VERIFIED`	تم اكتشاف الدفعة ومطابقتها (المحفظة + المرجع + المبلغ بالضبط).	Terminal
`WRONG_AMOUNT`	طابق المرجع لكن المبلغ المدفوع يختلف عن المبلغ المطلوب. يسجّل `paid_amount` ما وصل، ولا يُؤكد الطلب تلقائياً، فعلى المشتري التواصل معك.	Terminal
`EXPIRED`	انتهت مهلة الساعة دون تحقق.	Terminal
`CANCELLED`	أُلغي من قبل التاجر (لوحة التحكم).	Terminal

Webhooks

التحقق من التوقيع

verify_signature.py

import hashlib, hmac

def verify_signature(secret: str, body: bytes, signature: str) -> bool:
    ts, v1 = (p.split("=", 1)[1] for p in signature.split(","))
    digest = hmac.new(
        secret.encode(), f"{ts}.{body.decode()}".encode(), hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(digest, v1)

رابط الـ Endpoint

•يجب أن يكون الوصول إليه ممكناً من الإنترنت العام عبر HTTP(S). عناوين localhost والشبكات المحلية وأي رابط تطوير بلا نفق لا يستقبل شيئاً.
•يجب أن يعيد 2xx في غضون 6 ثوانٍ. أي استجابة أخرى تُحسب فشلاً وتبدأ جدول إعادة المحاولة.
•سر الـ endpoint تجده في لوحة التحكم ← Webhooks، ويُعرض مرة واحدة عند إضافته. استخدمه للتحقق من التوقيع.
•تُجدول الإرسالات لحظة وصول الدفعة. الدفعات التي جرت قبل إضافة الـ endpoint لا تُرسل متأخرة أبداً، فلا يوجد استرجاع لاحق.
•تفعيل «إشعار بالمدفوعات غير المطابقة» يرسل أيضاً payment.unmatched إلى ذلك الـ endpoint. الإضافة لا تمسّ بقية الأحداث.

الأحداث

WEBHOOKpayment.verified

بيانات الحدث

{
  "event": "payment.verified",
  "payment_id": "P7K4X92",
  "intent_id": "dd157a06-a065-475d-8723-d98a61698aa0",
  "order_id": "order-12345",
  "reference": "12345678",
  "base_amount": "1234.56",
  "amount": "1234.56",
  "currency": "YER",
  "status": "VERIFIED",
  "verified_at": "2026-09-09T13:41:22+03:00",
  "manual_override": false
}

WEBHOOKpayment.unmatched (اختياري)

بيانات الحدث

{
  "event": "payment.unmatched",
  "event_id": "32fd9972-71fd-4b87-82ce-501061ab7c5d",
  "reference": "12345678",
  "amount": "1234.56",
  "currency": "YER",
  "wallet": "Kuraimi - Main",
  "received_at": "2026-09-09T13:41:21+03:00",
  "is_test": false
}

WEBHOOKpayment.received (لمحفظة الاختبار فقط)

بيانات الحدث

{
  "event": "payment.received",
  "event_id": "32fd9972-71fd-4b87-82ce-501061ab7c5d",
  "reference": "12345678",
  "amount": "1234.56",
  "currency": "YER",
  "resolution": "UNMATCHED",
  "received_at": "2026-09-09T13:41:21+03:00",
  "is_test": true
}

ضمانات التسليم

•إعادة المحاولة عند الفشل: بعد 5 دقائق ثم 30 دقيقة ثم ساعتين ثم 12 ساعة ثم 24 ساعة، وبعدها تتوقف إيصالات عن المحاولة.
•الـ endpoints المعطّلة لا تستقبل أي شيء.
•الـ endpoints المقيدة بمحفظة تستقبل أحداثها فقط؛ وغير المقيدة تستقبل كل أحداث الحساب.
•قد تتكرر عمليات التسليم (مثل محاولة وصلت فعلاً)، اجعل معالجك يتحمّل التكرار عبر intent_id / event_id.
•استجب بـ 2xx للتأكيد؛ أي استجابة أخرى تُجدول إعادة المحاولة التالية.

حدود الطلبات

تُقيَّد الطلبات لكل بيانات اعتماد على حدة. عند تجاوز الحد تستلم 429 مع هيدر Retry-After. تعامل معها بسلاسة.

المسار	الحد اللحظي	الحد اليومي
`POST /token`	10/دقيقة	500/يوم
`POST /intents/, GET/PATCH /intents/{id}/`	240/دقيقة (~4 طلبات/ثانية)	50,000/يوم
`GET /intents/ (قائمة)`	60/دقيقة	50,000/يوم
`GET /providers/، GET/POST /wallets/، GET/PATCH/DELETE /wallets/{id}/`	240/دقيقة (~4 طلبات/ثانية)	50,000/يوم
`GET/POST /devices/، GET/PATCH/DELETE /devices/{id}/، POST /devices/{id}/…`	240/دقيقة (~4 طلبات/ثانية)	50,000/يوم

الأخطاء

يتبع كل خطأ صيغة موحّدة:

صيغة الخطأ

{
  "type": "validation_error",
  "errors": [
    { "code": "required", "detail": "This field is required.", "attr": "wallet" }
  ]
}

رموز حالة HTTP

الاسم	الوصف
`400`	محتوى غير صالح، محفظة غير معروفة، عامل تصفية غير صحيح، مراقبة غير مفعّلة في المحفظة، مرجع على طلب غير معلّق، أو تجاوز الحصة.
`401`	رمز `Bearer` مفقود أو غير صالح أو منتهي.
`403`	استخدام رمز لوحة التحكم (مستخدم) على مسارات التاجر. يلزم رمز بيانات الاعتماد.
`404`	معرّف طلب غير معروف (أو طلب من حساب آخر).
`429`	تم تجاوز حد الطلبات. احترم هيدر `Retry-After`.
`500`	حدث خطأ داخلي. أبلغنا عنه.

مرجع API التاجر

نظرة عامة

ما تحتاجه قبل البدء

كيف يعمل

ملخص الـ Endpoints

المصادقة

بيانات اعتماد العميل

الحصول على Token

عرض مزوّدي المحافظ

حقول الاستجابة

عرض المحافظ المتاحة

حقول الاستجابة

إضافة محفظة عبر POST /wallets/

أجهزة المراقبة

إنشاء جهاز عبر POST /devices/

الجهاز المُنشأ

مسارات الأجهزة

ملاحظات

إنشاء طلب دفع

الـ Body

قواعد التحقق

إرفاق مرجع المشتري

الـ Body

ملاحظات

عرض الطلبات وتصفيتها

Query Parameters

استرجاع طلب واحد

الحقول الأساسية

حالات الطلب

Webhooks

التحقق من التوقيع

رابط الـ Endpoint

الأحداث

ضمانات التسليم

حدود الطلبات

الأخطاء

صيغة الخطأ

رموز حالة HTTP

مرجع API التاجر

نظرة عامة

ما تحتاجه قبل البدء

كيف يعمل

ملخص الـ Endpoints

المصادقة

بيانات اعتماد العميل

الحصول على Token

عرض مزوّدي المحافظ

حقول الاستجابة

عرض المحافظ المتاحة

حقول الاستجابة

إضافة محفظة عبر POST /wallets/

أجهزة المراقبة

إنشاء جهاز عبر POST /devices/

الجهاز المُنشأ

مسارات الأجهزة

ملاحظات

إنشاء طلب دفع

الـ Body

قواعد التحقق

إرفاق مرجع المشتري

الـ Body

ملاحظات

عرض الطلبات وتصفيتها

Query Parameters

استرجاع طلب واحد

الحقول الأساسية

حالات الطلب

Webhooks

التحقق من التوقيع

رابط الـ Endpoint

الأحداث

ضمانات التسليم

حدود الطلبات

الأخطاء

صيغة الخطأ

رموز حالة HTTP

إضافة محفظة عبر `POST /wallets/`

إنشاء جهاز عبر `POST /devices/`

إضافة محفظة عبر `POST /wallets/`

إنشاء جهاز عبر `POST /devices/`