شعار NinjaBuyالأعمال
تواصل مع المبيعات
Orders API2026-11إصدار تجريبي

الشحنات

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

يُطلَق order.shipped عند إنشاء شحنة، مع بيانات تتبّعها.

نقاط النهاية

كائن Shipment

idstring
يبدأ بـ shp_.
order, fulfillment_orderstring
ما يحمله.
lanestring
saver أو fast.
carrier, tracking_number, tracking_urlstring
التتبّع، جاهز لعميلك.
weight_ginteger
وزن الطرد حين غلّفناه.
shipping_chargedmoney
الشحن ورسوم المناولة والضريبة للطرد الموزون، بـ CN¥: ما دفعه رصيدك.
pushed_to_channelboolean
هل لدى المتجر الذي جاء منه الطلب التتبّع. ثم يرسله Shopify بالبريد إلى عميلك.
statusstring
in_transit أو out_for_delivery أو delivered أو exception (معلّق، مُعاد، مفقود).
shipped_at, delivered_atstring|null
متى غادرنا، ومتى تقول شركة الشحن إنه وصل.
shipment
{
  "id": "shp_5r8w",
  "order": "ord_3n7q",
  "fulfillment_order": "fo_7k2m",
  "lane": "saver",
  "carrier": "YunExpress",
  "tracking_number": "YT2630812345678",
  "tracking_url": "https://t.17track.net/en#nums=YT2630812345678",
  "weight_g": 176,
  "shipping_charged": { "amount": "134.52", "currency": "CNY" },
  "pushed_to_channel": true,
  "status": "in_transit",
  "shipped_at": "2026-11-03T06:00:00Z",
  "delivered_at": null
}

عرض الشحنات

GET/v1/shipments

الأحدث أولًا. صفِّ حسب الحالة لتجد ما يحتاج إليك.

النطاقorders:read

معاملات الاستعلام

statusstring
اختياري.
orderstring
اختياري. معرّف طلب.
shipped_sincestring
اختياري. وقت.
limit, cursor
Pagination
curl "https://www.ninjabuy.com/api/v1/shipments?status=exception" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"
Response 200
HTTP/2 200 OK

{
  "data": [
    {
      "id": "shp_5q1d",
      "order": "ord_3m2b",
      "tracking_number": "YT2630811190042",
      "status": "exception"
    }
  ],
  "has_more": false,
  "cursor": null
}

جلب شحنة

GET/v1/shipments/{id}

طرد واحد، مع تتبّعه.

النطاقorders:read

معاملات المسار

idstringمطلوب
معرّف الشحنة.

الأخطاء

الحالةالنوعمتى
404not-foundلا توجد شحنة كهذه في هذا الحساب.
curl "https://www.ninjabuy.com/api/v1/shipments/shp_5r8w" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"
Response 200
HTTP/2 200 OK

{
  "id": "shp_5r8w",
  "order": "ord_3n7q",
  "fulfillment_order": "fo_7k2m",
  "lane": "saver",
  "carrier": "YunExpress",
  "tracking_number": "YT2630812345678",
  "tracking_url": "https://t.17track.net/en#nums=YT2630812345678",
  "weight_g": 176,
  "shipping_charged": { "amount": "134.52", "currency": "CNY" },
  "pushed_to_channel": true,
  "status": "in_transit",
  "shipped_at": "2026-11-03T06:00:00Z",
  "delivered_at": null
}

جلب أحداث التتبّع

GET/v1/shipments/{id}/tracking

عمليات المسح من شركة الشحن، الأقدم أولًا، بالإنجليزية.

النطاقorders:read

معاملات المسار

idstringمطلوب
معرّف الشحنة.

الأخطاء

الحالةالنوعمتى
404not-foundلا توجد شحنة كهذه في هذا الحساب.
curl "https://www.ninjabuy.com/api/v1/shipments/shp_5r8w/tracking" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"
Response 200
HTTP/2 200 OK

{
  "shipment": "shp_5r8w",
  "status": "in_transit",
  "events": [
    {
      "at": "2026-11-03T06:00:00Z",
      "where": "Shenzhen, CN",
      "status": "in_transit",
      "description": "Left the NinjaBuy warehouse"
    },
    {
      "at": "2026-11-05T22:10:00Z",
      "where": "Shenzhen, CN",
      "status": "in_transit",
      "description": "Departed the origin country"
    },
    {
      "at": "2026-11-09T19:40:00Z",
      "where": "Los Angeles, US",
      "status": "in_transit",
      "description": "Arrived in the destination country"
    }
  ]
}