Skip to main content
GET
تنزيل الإيصال

نظرة عامة

يبثّ إيصال مُصدِر الفواتير لفاتورة مدفوعة. وهو endpoint دفع الفواتير الوحيد الذي لا يُرجع JSON عند النجاح — فمتن الاستجابة هو الملف الخام نفسه.لا توجد الإيصالات إلا للمعاملات التي تكون status فيها SUCCESS. وأي حالة أخرى — معاملة ما زالت جارية، أو فاشلة، أو مستردة، أو تخصّ شريكًا آخر — تُجيب بغلاف خطأ JSON المعتاد مع 404 NOT_FOUND.
receiptUrl في معاملة ناجحة هو هذا endpoint بالضبط. وهو لا يزال يحتاج إلى ترويسة X-Access-Token الخاصة بك، لذلك فهو ليس رابطًا يمكنك إعطاؤه لعميل أو تضمينه في بريد إلكتروني. نزّل البايتات، وخزّنها، وقدّمها من نظامك أنت.

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

string
مطلوب
معرّف المعاملة. سلسلة سداسية عشرية من 24 حرفًا بأحرف صغيرة، من الحصول على معاملة بالمعرّف أو من أي قائمة.

الاستجابة

عند النجاح يكون المتن هو الملف نفسه. اقرأ ترويسات الاستجابة لتعرف ما الذي تلقّيته.
header
مطلوب
نوع وسائط الملف: application/pdf أو image/png أو image/jpeg. وأي شيء لا نستطيع تحديده يُقدَّم على أنه application/octet-stream.تفرّع دائمًا بناءً على هذه الترويسة بدلًا من افتراض أنه PDF.
header
مطلوب
attachment; filename="..." — اسم الملف المقترح، بالامتداد المطابق لـ Content-Type.
header
مطلوب
حجم الملف بالبايت.
header
مطلوب
private, max-age=86400. الإيصال يخصّ شريكًا واحدًا؛ لا تخزّنه أبدًا في ذاكرة تخزين مؤقت مشتركة أو عامة.
header
مطلوب
nosniff.
header
مطلوب
معرّف الربط لهذا الطلب. لا يوجد متن JSON عند النجاح، لذا فإن هذه الترويسة هي المكان الوحيد الذي يظهر فيه — سجّله.

الأمثلة

يتحقق كل مثال من الحالة قبل كتابة أي شيء، ويأخذ امتداد الملف من الاستجابة بدلًا من افتراضه.

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

المتن ثنائي. وتبدو الترويسات هكذا:

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

تُرجَع الأخطاء بصيغة JSON، في الغلاف نفسه المستخدم مع كل endpoint آخر.
كان المفتاح غائبًا أو مرفوضًا.
ما العمل: تحقّق من المفتاح باستخدام التحقق من مفتاح API.
إما أن المعاملة ليست لك في هذه البيئة، وإما أنه لا إيصال لها.
لا يوجد الإيصال إلا بعد أن تصل عملية الدفع إلى SUCCESS. التنزيل بينما المعاملة PROCESSING يُرجع هذا، وكذلك معاملة FAILED أو REFUNDED — فلا إيصال لأيٍّ منهما لأنه لم تكتمل أي عملية دفع.ما العمل: اقرأ المعاملة أولًا، ولا تنزّل إلا عندما تكون status هي SUCCESS وتكون receiptUrl موجودة.
لم نتمكن من التحقق من مفتاحك في الوقت المناسب، أو أن الواجهة في صيانة مُخطّط لها.
ما العمل: التزم بترويسة Retry-After (5 ثوانٍ) وأعد المحاولة. تكرار التنزيل آمن.
تعذّرت قراءة الإيصال.
ما العمل: أعد المحاولة مرة واحدة، ثم تواصل مع الدعم مع ذكر requestId. عملية الدفع نفسها غير متأثرة — فالمعاملة لا تزال SUCCESS.

التنزيل في اللحظة الصحيحة

اجلب الإيصال فور وصول عملية الدفع إلى SUCCESS، في الخطوة نفسها التي تسجّل فيها النجاح لديك.
خزّن البايتات، لا عنوان URL. يتطلب receiptUrl مفتاح API الخاص بك، لذا فالرابط المخزَّن عديم الفائدة لعميلك وخطر على المشاركة.

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

نزّل مرة واحدة، وخزّن إلى الأبد

احتفظ بالإيصال مع سجل طلبك الخاص. فهو المستند الذي تُحسم به منازعة العميل.

اقرأ Content-Type

الإيصال ملف PDF أو صورة بحسب مُصدِر الفواتير. خذ الامتداد من الترويسة.

لا تكشف عنوان URL أبدًا

قدّم الإيصالات من نظامك أنت، خلف مصادقتك أنت.

اقرنه بـ operationId

الإيصال هو المستند؛ وoperationId هو المرجع. خزّن كليهما.

Endpoints ذات الصلة

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

حيث يظهر receiptUrl وoperationId

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

اعثر على كل ما دُفع في فترة ما

دفع فاتورة

عملية الدفع التي أنتجته

الإيصالات والتسوية

تخزين الإيصالات وتسويتها