تنزيل الإيصال
دفع الفواتير
تنزيل الإيصال
نزّل إثبات الدفع لمعاملة ناجحة
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 آخر.401 — رمز وصول مفقود أو غير صالح
401 — رمز وصول مفقود أو غير صالح
404 — لا يوجد إيصال متاح
404 — لا يوجد إيصال متاح
إما أن المعاملة ليست لك في هذه البيئة، وإما أنه لا إيصال لها.لا يوجد الإيصال إلا بعد أن تصل عملية الدفع إلى
SUCCESS. التنزيل بينما المعاملة PROCESSING يُرجع هذا، وكذلك معاملة FAILED أو REFUNDED — فلا إيصال لأيٍّ منهما لأنه لم تكتمل أي عملية دفع.ما العمل: اقرأ المعاملة أولًا، ولا تنزّل إلا عندما تكون status هي SUCCESS وتكون receiptUrl موجودة.503 — المصادقة أو الخدمة غير متاحة
503 — المصادقة أو الخدمة غير متاحة
لم نتمكن من التحقق من مفتاحك في الوقت المناسب، أو أن الواجهة في صيانة مُخطّط لها.ما العمل: التزم بترويسة
Retry-After (5 ثوانٍ) وأعد المحاولة. تكرار التنزيل آمن.500 — خطأ داخلي
500 — خطأ داخلي
تعذّرت قراءة الإيصال.ما العمل: أعد المحاولة مرة واحدة، ثم تواصل مع الدعم مع ذكر
requestId. عملية الدفع نفسها غير متأثرة — فالمعاملة لا تزال SUCCESS.التنزيل في اللحظة الصحيحة
اجلب الإيصال فور وصول عملية الدفع إلىSUCCESS، في الخطوة نفسها التي تسجّل فيها النجاح لديك.أفضل الممارسات
نزّل مرة واحدة، وخزّن إلى الأبد
احتفظ بالإيصال مع سجل طلبك الخاص. فهو المستند الذي تُحسم به منازعة العميل.
اقرأ Content-Type
الإيصال ملف PDF أو صورة بحسب مُصدِر الفواتير. خذ الامتداد من الترويسة.
لا تكشف عنوان URL أبدًا
قدّم الإيصالات من نظامك أنت، خلف مصادقتك أنت.
اقرنه بـ operationId
الإيصال هو المستند؛ و
operationId هو المرجع. خزّن كليهما.Endpoints ذات الصلة
الحصول على معاملة بالمعرّف
حيث يظهر
receiptUrl وoperationIdقائمة المعاملات
اعثر على كل ما دُفع في فترة ما
دفع فاتورة
عملية الدفع التي أنتجته
الإيصالات والتسوية
تخزين الإيصالات وتسويتها

