جئت من زنبيل؟ زنبيل إكسبريس هي ذراع الشحن لزنبيل: الطرود التي تشتريها، والطرود التي ترسلها بنفسك، بالتطبيق نفسه. العودة إلى زنبيل ←
الرئيسية / للأعمال / للمطوّرين

Connect API

كل ما يحتاجه مبرمجك لربط متجرك أو نظامك بشبكة زنبيل إكسبريس: REST وJSON عبر HTTPS، بيئة تجريبية تتقدّم فيها الشحنات تلقائياً، وWebhooks لكل تغيّر في الحالة.

اطلب مفتاحاً تجريبياً أو بالبريد
العنوان الأساسيhttps://express.zanbbel.com/api/cargo/connect/v1
المصادقةAuthorization: Bearer cargo_sk_… — مفتاح تجريبي ثم مفتاح إنتاج
النمطREST + JSON عبر HTTPS، الحقول snake_case، الأوقات ISO 8601
منع التكرارترويسة Idempotency-Key على إنشاء الشحنة؛ الطلب المكرّر يعيد الشحنة نفسها
الدفعاتحتى 100 شحنة في طلب واحد عبر /shipments/bulk
حدّ الاستدعاء600 طلب في الدقيقة لكل مفتاح
Webhooksسرّ خاص بك قابل للتدوير، و7 محاولات بتراجع متزايد (دقيقة، 5، 15، ساعة، 6 ساعات، يوم) قبل التوقف
البيئة التجريبيةشحنات وهمية تتقدّم تلقائياً من الإنشاء حتى التسليم، فيُختبر الربط كاملاً
المسارات

ما تستطيع فعله

المسارماذا يفعل
GET /whoamiيعرّف المفتاح: المتجر، البيئة، والصلاحيات.
GET /coverageالمدن والمحافظات التي نخدمها، مع معرّفات city_id.
GET /coverage/checkهل نصل إلى هذا العنوان أو هذه المدينة؟
POST /ratesسعر الشحن لمسار ووزن معيّنين قبل إنشاء الشحنة، ليعرضه متجرك عند الدفع.
POST /address/validateتدقيق العنوان قبل الإنشاء.
POST /shipmentsإنشاء شحنة؛ تعيد رقم التتبّع ورابطه ومبلغ التحصيل عند الاستلام.
POST /shipments/bulkحتى 100 شحنة دفعة واحدة، كلٌّ بمفتاح تكرار خاص بها.
GET /shipments/{id}الحالة الحالية وسجلّ المراحل.
POST /shipments/{id}/cancelإلغاء شحنة لم تُستلم بعد.
GET /shipments/{id}/podإثبات التسليم: الصورة والتوقيع واسم المستلم ووقت التسليم.
POST /webhooksتسجيل عنوان يصله كل تغيّر في الحالة.
GET /webhooksعناوينك المسجّلة وحالتها.
POST /webhooks/{id}/rotate-secretتدوير سرّ التوقيع.
مثال

شحنة بتحصيل عند الاستلام

POST https://express.zanbbel.com/api/cargo/connect/v1/shipments Authorization: Bearer cargo_sk_… Idempotency-Key: ORDER-12345 Content-Type: application/json { "merchant_reference": "ORDER-12345", "recipient": { "name": "…", "phone": "+9639…", "city_id": 9187, "address": "…" }, "parcel": { "description": "…", "weight_kg": 1.2 }, "cod": { "amount": 250000, "currency": "SYP" } } → 201 { "id": "…", "tracking_number": "ZEX-2026-…", "tracking_url": "https://express.zanbbel.com/t/ZEX-2026-…", "status": "created" }

أسماء الحقول الكاملة وأكواد الأخطاء في التوثيق الذي نرسله مع المفتاح التجريبي (عربي وإنجليزي، مع ملف OpenAPI ومجموعة Postman).

من البداية إلى الإنتاج

ثلاث خطوات

اطلب مفتاحاً تجريبياً

على واتساب أو البريد باسم المتجر ورقم المسؤول التقني. يصلك المفتاح مع التوثيق.

اربط في البيئة التجريبية

أنشئ شحنات، سجّل Webhook، وراقب الحالات تتقدّم تلقائياً حتى التسليم.

انتقل إلى الإنتاج

نفعّل مفتاح الإنتاج، وتنطلق أول شحنة حقيقية.

For developers

REST + JSON over HTTPS at /api/cargo/connect/v1, Bearer cargo_sk_… keys (sandbox, then production), Idempotency-Key on shipment creation, up to 100 shipments per bulk call, 600 requests per minute per key, and webhooks with a rotatable secret and 7 delivery attempts with exponential backoff. Rates, coverage, address validation, proof of delivery and cancellation are all endpoints. Ask for a sandbox key on WhatsApp or at support@zanbbel.com; the full reference (Arabic + English, OpenAPI, Postman) comes with it.