للمطوّرين
طلب واحد، لكل الشركات.
أنشئ الشحنة مسودة، ثم أرسلها إلى الشركة التي تختارها بالطلب نفسه أيًّا كانت. وتصلك إشعارات موقّعة عند كل تغيّر.
الواجهة في مثال واحد
كل طلب يحمل مفتاح 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_…). تحقّق منه قبل أن تعمل به:
- احسب
HMAC-SHA256بالسرّ كاملًا (معwhsec_) مفتاحًا، على<t>.<body>: قيمةt، ثم نقطة، ثم جسم الطلب كما وصل. - اقبل الإشعار إن ساوى الناتج أي قيمة
v1. تكون قيمتان أثناء تغيير السرّ. - ارفض الإشعار إن كان
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…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 يُنشران هنا قريبًا. إلى ذلك الحين، راسلنا لتحصل عليهما.