تخطَّ إلى المحتوى
ShipFlow
للمطوّرين

طلب واحد، لكل الشركات.

أنشئ الشحنة مسودة، ثم أرسلها إلى الشركة التي تختارها بالطلب نفسه أيًّا كانت. وتصلك إشعارات موقّعة عند كل تغيّر.

الواجهة في مثال واحد

كل طلب يحمل مفتاح API في ترويسة Authorization. الإرسال إلى الشركة يحتاج Idempotency-Key، فإعادة الطلب نفسه لا تنشئ الشحنة مرتين.

  • الرد 202 فورًا، ومعه عملية الإنشاء. حالتها (state) تحمل النتيجة: requested ثم succeeded أو failed.
  • تابع النتيجة بإشعار webhook، أو اطلب العملية نفسها.
  • أي حقل غير معروف في الطلب يُرفض، وتجاهل أي حقل جديد في الرد.
POST /v1/shipments/{id}/submit
Authorization: Bearer sfk_…
Idempotency-Key: order-1042-submit
Content-Type: application/json

{"carrier": {"code": "smsa", "service": "standard"}}

202 Accepted
{"shipment":  {"id": "…", "reference": "ORDER-1042", "status": "draft", …},
 "operation": {"id": "…", "kind": "create", "state": "requested", …}}

الإشعارات وتوقيعها

كل إشعار طلب POST إلى عنوانك، موقّع بسرّ نقطة الاستقبال (whsec_…). تحقّق منه قبل أن تعمل به:

  1. احسب HMAC-SHA256 بالسرّ كاملًا (مع whsec_) مفتاحًا، على <t>.<body>: قيمة t، ثم نقطة، ثم جسم الطلب كما وصل.
  2. اقبل الإشعار إن ساوى الناتج أي قيمة v1. تكون قيمتان أثناء تغيير السرّ.
  3. ارفض الإشعار إن كان t أقدم من 5 دقائق.
  • المعرّف id واحد في كل إعادة للحدث نفسه، فاستبعد المكرر به.
  • الأحداث لا تصل بترتيب. تجاهل حدثًا رقم shipment.version فيه أقل مما طبّقته.
  • أي رد 2xx نجاح. غير ذلك يُعاد بعد دقيقة، ثم 5 دقائق، ثم 30، وتتباعد المحاولات حتى 3 أيام.
POST https://your-store.example/webhooks
Content-Type: application/json
ShipFlow-Event-Id: 0196…
ShipFlow-Event-Type: shipment.status_changed
ShipFlow-Signature: t=1763287200,v1=5f1c…
مثال للتحقق في Node.js
import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(secret, header, rawBody) {
  const parts = header.split(',').map((p) => p.split('='));
  const t = parts.find(([k]) => k === 't')?.[1];
  if (!t || Date.now() / 1000 - Number(t) > 300) return false;
  const want = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest();
  return parts.some(([k, v]) => {
    if (k !== 'v1') return false;
    const got = Buffer.from(v, 'hex');
    return got.length === want.length && timingSafeEqual(got, want);
  });
}

المرجع الكامل

التوثيق الكامل للواجهة ومواصفة OpenAPI يُنشران هنا قريبًا. إلى ذلك الحين، راسلنا لتحصل عليهما.

تواصل معنا