واجهة الشركاء — بِع على بوفيتو من نظامك الخاص#

واجهة الشركاء تُبقي كتالوج بائع بوفيتو ومخزونه وأسعاره وطلباته متزامنة مع النظام الذي يستخدمه أصلاً. أما قبول المدفوعات فهو عمل واجهة Checkout، وهي واجهة منفصلة.

كل المبالغ في هذه الواجهة أعداد صحيحة بالدينار العراقي، بلا كسور ولا وحدات صغرى: 25000 تعني 25,000 دينار. كل الأوقات بصيغة ISO 8601 بالتوقيت العالمي المنسّق (UTC).

ما تحتاج معرفته#

• بيئتان: تقبل بيئة Sandbox مفاتيح povito_sk_test_ فقط، وتقبل بيئة Live مفاتيح povito_sk_live_ فقط. المفتاح السليم الصيغة المُرسَل إلى البيئة الأخرى يُرفض بالرمز 401 api_key_wrong_environment. التفاصيل بالإنجليزية في المفاتيح والبيئات.
• حساب بائع في Sandbox: تُنشئ بوفيتو حسابات البائعين في Sandbox عند الطلب، فاطلبه من جهة اتصالك في بوفيتو. يبقى هذا الحساب بحالة pending_approval، فلا يظهر للمتسوقين شيء مما يزامنه تكاملك هناك.
• المفتاح يُنشأ ويُعدَّل ويُلغى من لوحة البائع تحت الإعدادات ← التكاملات، لا عبر هذه الواجهة، ويتطلب إنشاؤه صلاحية إدارة الفريق. حساب Sandbox يُصدر مفاتيح test، وحساب Live يُصدر مفاتيح live. يُعرض المفتاح كاملاً مرة واحدة فقط عند إنشائه، ولا تحفظ بوفيتو إلا بصمة HMAC لسرّه. يخص المفتاح حساب بائع واحداً ولا يصل إلى بيانات أي بائع آخر.
• الصلاحيات (catalog:read، catalog:write، inventory:write، orders:read) تُختار عند إنشاء المفتاح. أما webhooks:manage فمحجوزة ولا توجد لها نقاط نهاية بعد. امنح ما يحتاجه التكامل فقط.
• نقاط النهاية: GET /products، وGET /products/{sku}، وPOST /products/bulk (حتى 50 صفاً)، وPATCH /inventory/bulk (حتى 500 صف)، وPOST /inventory/adjustments (حتى 100 بند)، وGET /orders، وGET /orders/{id}، وGET /health بلا مفتاح.
• المنتجات الجديدة مسودات: ينشئ POST /products/bulk المنتجات بحالة draft ولا ينشر أي شيء. لا تُنشر المسودة إلا بعد إرسالها للموافقة من لوحة البائع وموافقة بوفيتو عليها. حالات المنتج هي draft وproposed وpublished وrejected.
• نتائج الدفعات لكل صف على حدة: الاستجابة 200 حتى لو رُفضت بعض الصفوف، فاقرأ results[] دائماً.
• ترويسة Idempotency-Key إلزامية على كل طلبات الكتابة، وإعادة المحاولة بها آمنة: تحفظ بوفيتو نتيجة الطلب الأول مدة 24 ساعة وتعيدها عند تكرار الطلب بالمفتاح نفسه والمحتوى نفسه، فلا تُعاد المزامنة ولا تتحرك الكمية مرتين.
• حد الطلبات: 60 طلباً كل 600 ثانية لكل مفتاح، بعدّاد مستقل لكل نقطة من نقطتي الدفعات.
• ابدأ في Sandbox بمفتاح test. وعند الانتقال إلى Live ابدأ بمفتاح للقراءة فقط، ثم أضف صلاحيات الكتابة تدريجياً.
• غير متاح بعد: إشعارات الويب هوك للطلبات؛ إرسال المنتجات للمراجعة عبر الواجهة؛ المنتجات متعددة الخيارات وتسعير كل خيار على حدة؛ السحب التزايدي للكتالوج؛ إجراءات الطلب (القبول والشحن والإلغاء تتم من لوحة البائع)؛ مزامنة المرتجعات. شروط استخدام واجهة الشركاء لم تُنشر بعد.

المرجع الكامل بكل الحقول والأمثلة متاح بالإنجليزية: Partner API، والمنتجات، والمخزون، والطلبات، والحدود والأخطاء.