Skip to main content
GET
الحصول على معاملة بالمرجع

نظرة عامة

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

معلمات الاستعلام

string
مطلوب
المرجع الذي قدّمته عند إنشاء الاستكشاف. 100 حرف كحد أقصى.
string
اختياري. أحد القيم ADE أو SONELGAZ أو SEAAL أو AADL أو Algérie Télécom. يحصر البحث في ذلك المُصدِر.

الاستجابة

مطابقة لـ الحصول على معاملة بالمعرّف — كائن المعاملة الكامل، مغلَّفًا في الغلاف القياسي. راجع تلك الصفحة للاطلاع على مرجع الحقول حقلًا بحقل، وعلى الحقول التي تظهر في كل حالة.
boolean
مطلوب
true عند العثور على معاملة.
object
مطلوب
كائن المعاملة. مرجع الحقول الكامل →
object
مطلوب
string
مطلوب
معرّف الربط، يُرسَل أيضًا في ترويسة الاستجابة X-Request-Id.

الأمثلة

استجابة النجاح

استجابات الخطأ

كان ref مفقودًا أو أطول من اللازم، أو لم تكن partner قيمة معروفة.
ما العمل: أرسل ref كمعلمة استعلام، مُرمَّزة لعناوين URL، وبطول 100 حرف كحد أقصى.
كان المفتاح غائبًا أو مرفوضًا.
ما العمل: تحقّق من المفتاح باستخدام التحقق من مفتاح API.
لا توجد معاملة بذلك ref تخصّ حسابك في هذه البيئة.
ما العمل: بعد فشل عملية كتابة، يكون 404 هنا هو الدليل على أن الطلب لم يصل أبدًا — ومن الآمن إرساله مرة أخرى بـ ref نفسه. وتحقّق أيضًا من أنك تستخدم مفتاح البيئة التي أُنشئت فيها المعاملة.
لم نتمكن من التحقق من مفتاحك في الوقت المناسب، أو أن الواجهة في صيانة مُخطّط لها.
ما العمل: التزم بترويسة Retry-After (5 ثوانٍ) وأعد المحاولة. تكرار البحث آمن دائمًا.

الاسترداد من استجابة ضائعة

النمط نفسه للاستكشاف وللدفع: إذا فشلت عملية الكتابة بطريقة لا تستطيع تفسيرها، فاسأل عمّا يشير إليه ref قبل أن ترسل أي شيء مرة أخرى.
لا يكون 404 من هذا endpoint ذا معنى إلا عندما تسأل عن ref أرسلته بالتأكيد. لا تستخدمه أبدًا لتقرّر أن عملية دفع لم تحدث بينما الذي بحثت عنه هو ref الاستكشاف — فعملية الدفع تعيش على المعاملة نفسها التي يعيش عليها استكشافها، تحت ref الاستكشاف.

أفضل الممارسات

ابحث، لا تُعِد الإرسال

كل انتهاء مهلة وكل DUPLICATED_REF تُجاب هنا، لا بعملية كتابة ثانية.

مرّر الشريك

لا يكلّف شيئًا ويزيل أي التباس عندما توجد سلسلة ref نفسها لدى مُصدِرَي فواتير.

خزّن المرجع مع طلبك

ref لا تستطيع إعادة بنائه هو معاملة لا تستطيع استردادها.

استعلم بالمعرّف بمجرد حصولك عليه

استخدم هذا endpoint للاسترداد، ثم استعلم بـ transactionId — معلمة أقل يمكن أن تخطئ فيها.

Endpoints ذات الصلة

الحصول على معاملة بالمعرّف

كائن المعاملة الكامل

قائمة المعاملات

صفِّ السجل واستعرضه بالصفحات

استكشاف الفواتير

حيث يُنشأ ref

استقصاء الحالة

مُستقصٍ بمستوى الإنتاج