الاستجابات والقواعد

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

تحتوي كل استجابة على data وrequestId وerror. عند النجاح يكون error بقيمة null، وعند الفشل تكون data بقيمة null ويتضمن error رمزاً رقمياً ورسالة. احتفظ بـrequestId للدعم دون تسجيل المفاتيح أو بيانات البطاقات.

{
  "data": { "status": "ok", "mode": "TEST" },
  "requestId": "partner-example-request",
  "error": null
}

المبالغ والأسعار

الأسعار والحركات المالية أعداد صحيحة بالهللة. سعر الشريك هو السعر النهائي الشامل للضريبة، دون رسوم الخدمة. يعيد الخادم احتساب السعر عند الشراء؛ التحقق من السعر ليس حجزاً ولا تثبيتاً له.

faceValue نص عشري وfaceValueCurrency عملة الفئة الأصلية. قد يكون كلاهما null عند غياب بيانات الفئة؛ لا تستنتجهما من السعر بالريال. يوضح PARTNER_PRICE وRETAIL_FALLBACK مصدر السعر.

الصفحات والتواريخ

تبدأ page من 1 وتقبل size من 1 إلى 100 (الافتراضي 20). تتضمن النتائج items وpagination بالحقول page وsize وtotal وtotalPages. يكون totalPages: 0 للقائمة الفارغة.

تستخدم الطوابع الزمنية ISO 8601. يشمل فلتر from وقته، ويستثني to وقته. يمكن استخدام أي منهما منفرداً؛ وعند تحديدهما معاً يجب أن يسبق from قيمة to وألا تتجاوز الفترة 366 يوماً. تغطي كشوف الحساب أشهراً مكتملة بتوقيت Asia/Riyadh؛ periodEndExclusive هو بداية الشهر التالي.

تعامل مع بيانات البطاقات بعناية

لا تتضمن قوائم الطلبات بيانات البطاقات. تعرضها استجابات الشراء والتفاصيل بعد اكتمال التنفيذ فقط. تحمل استجابات المال والطلبات والكشوف Cache-Control: no-store. سلّم بيانات البطاقة للمستلم المقصود، وأبقها خارج التحليلات والسجلات.