القواعد العامة

ذات صلة: المصادقة · المنتجات والطلبات · البداية

#الطلبات

• العنوان الأساسي: https://b2b.cardv.net/api/v1 (Live) أو https://sandbox.cardv.net/api/v1 (Sandbox).
• المسارات لا تنتهي بشرطة مائلة. استخدم /api/v1/orders وليس /api/v1/orders/.
• أرسل محتوى JSON بترميز UTF-8 مع Content-Type: application/json.
• أرسل المبالغ كنصوص، مثل "9.2500"، لتتجنب أخطاء التقريب.
• حدّد قيمة واضحة لـ User-Agent، مثل AcmeShop-CardV/1.4.

#المبالغ والوقت

• المبلغ نص بأربع خانات عشرية، مثل "merchant_price": "9.2500".
• اقرأه بنوع عددي عشري دقيق (decimal)، ولا تستخدم أبدًا الأعداد ذات الفاصلة العائمة (float).
• تدفع بعملة محفظتك (default_currency في GET/account، وهي حاليًا USD).
• face_currency هي العملة المطبوعة على البطاقة، وقد تختلف عن عملة محفظتك.
• اعتمد دائمًا على merchant_price لحساب تكلفتك. أما حقول مثل price_label فهي للعرض فقط.
• كل الأوقات بتوقيت UTC وبصيغة ISO 8601، مثل 2026-09-29T08:15:30.123456Z.
• استخدم محللًا حقيقيًا لصيغة ISO 8601، لأن عدد الخانات العشرية في الثواني قد يختلف.
• قيمة X-Timestamp المستخدمة في التوقيع هي وقت Unix بالثواني.

#الأرقام التعريفية

• احفظ الأرقام التعريفية كنصوص، ولا تحاول تفكيكها، فقد يزداد طولها.
• للطلبات أيضًا حقل رقمي اسمه id. لا تستخدمه، واستخدم order_id.
• في رقم طلبك استخدم هذه الأحرف فقط: A–Z a–z 0–9 - _ ..

#تقسيم النتائج إلى صفحات

نقطة النهاية الوحيدة المقسّمة إلى صفحات هي GET/skus. أرسل limit وoffset:

GET /api/v1/skus?limit=100&offset=200

{"count": 1234, "limit": 100, "results": ["..."], "filter_options": {}}

• القيمة الافتراضية لـ limit هي 100، والحد الأقصى 500. أي قيمة أكبر تُخفَّض إلى 500.
• count هو إجمالي النتائج المطابقة. واصل الطلب حتى تصل offset إلى count.
• إذا كانت limit أو offset سالبة أو ليست رقمًا، تحصل على HTTP 400.
• قيمة تصفية غير معروفة تُرجع قائمة فارغة، لا خطأ.

#حد الطلبات

• الحد الافتراضي 60 طلبًا في الدقيقة لحسابك بالكامل. تتشاركه كل مفاتيحك ومستخدمي البوابة. وقد تحدد فئة حسابك رقمًا مختلفًا.

• تبدأ الدقيقة عند الثانية :00 بحسب الساعة. والطلبات المرفوضة تُحتسب أيضًا.

• عند تجاوز الحد تحصل على HTTP 429 وترويسة Retry-After (عدد الثواني التي تنتظرها):

  JSONCopy

  {"detail": "Merchant API rate limit exceeded. Expected available in 23 seconds."}

• لتبقى ضمن الحد: احفظ قائمة المنتجات مؤقتًا، واستخدم Webhook بدل الاستعلام المتكرر السريع، وانتظر مدة أطول قليلًا بعد كل رد 429.

#الأخطاء

تحقق دائمًا من رمز حالة HTTP أولًا، ثم اقرأ محتوى JSON. المفتاح الموجود في المحتوى هو ما يخبرك بسبب الخطأ. لا تعتمد على نص الرسالة.

أخطاء المصادقة والصلاحيات وعدم العثور وحد الطلبات تستخدم المفتاح detail:

{"detail": "Order not found."}

أخطاء الطلب وعرض السعر تذكر اسم الحقل:

{"balance": "Insufficient available balance."}

إذا كان أحد بنود الطلب غير سليم، يظهر الخطأ لكل بند في الموضع نفسه الذي يحتله في items:

{"items": [{}, {"quantity": ["Ensure this value is greater than or equal to 1."]}]}

بعض الأخطاء لا تأتي بصيغة JSON:

• HTTP 403 مع نص عادي مثل error code: 1010 مصدره طبقة الشبكة الخارجية لدى CardV. طلبك لم يصل إلى CardV أصلًا. أرسل إلى CardV عنوان IP لخادمك وقيمة User-Agent.
• المسار غير المعروف (404) أو خطأ الوسيط (5xx) قد يُرجع صفحة HTML.

عند تسجيل الأخطاء، لا تسجّل أبدًا مفاتيح API أو التواقيع أو الأكواد.

#رموز حالة HTTP

في POST/orders، أعد المحاولة بالمحتوى نفسه ورقم الطلب نفسه فقط. راجع إعادة المحاولة بأمان.

#الردود

• brand_logo_url وimage_url روابط كاملة لصور تستضيفها CardV، أو "". وهي روابط عامة يمكن حفظها مؤقتًا.
• حقلا الطلب invoice_url وdelivery_file_url مساران مثل /orders/O-00001234/invoice، أو "" إذا لم يتوفر شيء بعد. وهما خاصان بالبوابة: مع مفتاح API يُرجعان HTTP 403. افتح الفواتير وملفات الأكواد بصيغة CSV من البوابة.

#التوافق

• تجاهل الحقول التي لا تعرفها. تضيف CardV حقولًا جديدة دون إصدار جديد من API.
• قد تظهر قيم جديدة للحالات. اعتبر أي حالة غير معروفة "لم يكتمل بعد".
• لا تعتمد على ترتيب المفاتيح في JSON ولا على صياغة الرسائل.