دليل التكامل للمبرمجين

تتكامل منصة BlueZone مع مزودي الدفع وشركات الشحن عبر طبقة Adapter مستقلة لكل مزود. يكفي أن يوفّر مزود الخدمة واجهة API تحقق الحد الأدنى الموضح هنا، وبعدها نبني الـ Adapter ونختبره ونعتمده.

خطوات الانضمام

• قدّم طلب الانضمام من نموذج «انضم للتكامل» مع رابط التوثيق.
• نراجع التوثيق ونتواصل معك فنيًا خلال أيام عمل قليلة.
• تزوّدنا ببيئة تجريبية (Sandbox) ومفاتيح اختبار.
• نبني الـ Adapter ونجري اختبارات القبول المذكورة أدناه.
• بعد النجاح نعتمدك ونعرض اسمك وشعارك في صفحة «شركاؤنا».

المتطلبات العامة

• HTTPS (TLS 1.2 أو أحدث) و JSON في الطلبات والردود.
• مصادقة بمفتاح API في الترويسة: Authorization: Bearer <API_KEY>.
• بيئة Sandbox منفصلة عن الإنتاج.
• رموز حالة HTTP واضحة وأخطاء بصيغة JSON فيها code و message.
• دعم Idempotency: ترويسة Idempotency-Key لمنع تكرار العملية.

أولًا: بوابات الدفع

1) إنشاء عملية دفع

POST /v1/payments
{
  "reference": "MK-1024",
  "amount": 150.000,
  "currency": "KWD",
  "customer": { "name": "اسم العميل", "email": "a@b.com", "phone": "+96551234567" },
  "language": "ar",
  "callback_url": "https://example.com/pay/return",
  "webhook_url": "https://example.com/pay/webhook"
}

الرد المطلوب:

{ "id": "pay_8f2c", "status": "pending", "payment_url": "https://gateway.com/pay/pay_8f2c" }

نحوّل العميل إلى payment_url لإتمام الدفع.

2) الاستعلام عن الحالة

GET /v1/payments/{id}
{ "id": "pay_8f2c", "status": "paid", "reference": "MK-1024", "amount": 150.000, "currency": "KWD", "method": "knet", "paid_at": "2026-10-14T18:20:00Z" }

الحالات المدعومة: pending و paid و failed و cancelled و refunded.

3) Webhook

عند تغير الحالة نرسل POST إلى webhook_url بنفس جسم الاستعلام، وتوقّعه بترويسة X-Signature وهي HMAC-SHA256 لجسم الطلب بسر مشترك. نتحقق من التوقيع ونرد بـ 200.

4) الاسترجاع (اختياري)

POST /v1/payments/{id}/refunds
{ "amount": 150.000, "reason": "customer_request" }

ثانيًا: شركات الشحن

1) حساب الأسعار

POST /v1/rates
{ "from": { "country": "KW", "city": "Kuwait City" }, "to": { "country": "KW", "area": "Salmiya" }, "weight_kg": 1.2, "cod": 25.000 }

الرد: قائمة خدمات بالسعر والمدة المتوقعة.

2) إنشاء شحنة

POST /v1/shipments
{
  "reference": "ORD-5531",
  "service": "express",
  "sender": { "name": "المتجر", "phone": "+965...", "address": "..." },
  "recipient": { "name": "العميل", "phone": "+965...", "address": "...", "area": "السالمية" },
  "parcels": [ { "weight_kg": 1.2 } ],
  "cod_amount": 25.000
}

الرد: { "id": "shp_123", "tracking_number": "KW123456", "label_url": "https://.../label.pdf" }

3) التتبع

GET /v1/shipments/{id}/tracking
{ "status": "out_for_delivery", "events": [ { "status": "picked_up", "at": "...", "note": "..." } ] }

الحالات: created و picked_up و in_transit و out_for_delivery و delivered و failed و returned و cancelled.

4) الإلغاء وWebhook

POST /v1/shipments/{id}/cancel لإلغاء الشحنة قبل الاستلام. وWebhook لتحديث الحالات بنفس توقيع X-Signature.

اختبارات القبول

• نجاح وفشل وإلغاء الدفع، وتطابق المبلغ والعملة.
• وصول Webhook صحيح التوقيع، ورفض التوقيع الخاطئ.
• عدم تكرار العملية عند إعادة الطلب بنفس Idempotency-Key.
• إنشاء شحنة وتتبعها وإلغاؤها وتحديث حالتها عبر Webhook.
• زمن استجابة معقول وتوثيق واضح للأخطاء.

التواصل الفني

بعد تقديم طلبك سيتواصل معك فريقنا الفني على البريد الذي كتبته في النموذج.