Orders API2026-11إصدار تجريبي

الطلبات

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

تابع الطلب عبر webhooks بدل الاستعلام المتكرر: أحداث الطلب تُطلق مع كل مرحلة. والطرد نفسه أمر تنفيذ، ثم شحنة.

نقاط النهاية

POST/v1/ordersإنشاء طلب
GET/v1/ordersعرض الطلبات
GET/v1/orders/{id}جلب طلب
POST/v1/orders/{id}/cancelإلغاء طلب

كائن Order

idstring: يبدأ بـ ord_.
external_idstring: رقم طلب متجرك. فريد في حسابك.
sourcestring: api، أو shopify للطلبات التي أرسلها إلينا متجرك على Shopify.
statusstring: حالة أقل البنود تقدّمًا؛ راجع الحالات أدناه.
payment_statusstring: awaiting_payment أو paid أو partially_refunded أو refunded.
lanestring: saver أو fast.
lines[]array: المتغيّر، والكمية، والقطع المشتراة لكل قطعة، والحالة، وصور المستودع بعد الفحص، وreason عند الرفض.
ship_toobject: اسم عميلك وعنوانه وهاتفه وبريده الإلكتروني.
packagingstring|null: علبتك أو مغلّفك البريدي ذو العلامة التجارية؛ الافتراضي لديك حين يكون null.
chargesobject: التكلفة بـ CN¥: الشراء (البضاعة ورسوم الاستلام والضريبة) والطرد (الشحن ورسوم المناولة والضريبة). الطرد تقدير من أوزانك حتى نزنه.
amount_duemoney|null: ما يجب أن يغطيه رصيدك بعد، أثناء awaiting_payment.
fulfillment_orders[]array: الطرود التي يغادر فيها.

order

{
  "id": "ord_3n7q",
  "external_id": "1012",
  "source": "shopify",
  "status": "checked",
  "payment_status": "paid",
  "lane": "saver",
  "lines": [
    {
      "id": "lin_9a2c",
      "variant": "var_41hz",
      "sku": "5187209554",
      "title": "Heavyweight Washed Hoodie, Black / M",
      "quantity": 1,
      "units": 1,
      "status": "checked",
      "photos": [
        "https://media.ninjabuy.com/qc/ord_3n7q/1.webp",
        "https://media.ninjabuy.com/qc/ord_3n7q/2.webp"
      ],
      "reason": null
    }
  ],
  "ship_to": {
    "name": "Sam Rivera",
    "line1": "500 Congress Ave",
    "line2": null,
    "city": "Austin",
    "region": "TX",
    "postal_code": "78701",
    "country": "US",
    "phone": "+15125550142",
    "email": "sam@example.com"
  },
  "packaging": "pkg_acme_mailer",
  "charges": {
    "procurement": {
      "goods": { "amount": "38.00", "currency": "CNY" },
      "intake_fee": { "amount": "12.00", "currency": "CNY" },
      "tax": { "amount": "7.00", "currency": "CNY" },
      "total": { "amount": "57.00", "currency": "CNY" }
    },
    "parcel": {
      "lane": "saver",
      "shipping": { "amount": "68.00", "currency": "CNY" },
      "handling_fee": { "amount": "50.00", "currency": "CNY" },
      "tax": { "amount": "16.52", "currency": "CNY" },
      "total": { "amount": "134.52", "currency": "CNY" },
      "estimate": true
    },
    "total": { "amount": "191.52", "currency": "CNY" }
  },
  "amount_due": null,
  "fulfillment_orders": ["fo_7k2m"],
  "created_at": "2026-11-01T09:14:02Z",
  "updated_at": "2026-11-02T03:20:11Z"
}

أرسل إلينا أحد طلبات متجرك. كل بند متغيّر حفظته، أو رابط صفحة منتج وSKU نشتريه كما هو. يُدفع الطلب من رصيدك فورًا؛ والطلب الذي لا يغطيه رصيدك يُنشأ رغم ذلك، بحالة awaiting_payment مع amount_due، ويتابع تلقائيًا حين تشحن رصيدك.

الطلبات من متجرك على Shopify تصل إلينا دون هذا الاستدعاء. استخدمه لـ WooCommerce وWix وموقعك الخاص، أو أي شيء آخر يبيع.

النطاقorders:write

النص

external_idstringمطلوب: رقم طلبك. يُرفض أي طلب ثانٍ بالرقم نفسه.
lines[]arrayمطلوب: variant وquantity، أو url وsku وquantity. وunits (اختياري) يشتري هذا العدد لكل قطعة، للعبوات.
ship_toobjectمطلوب: name وline1 وline2 وcity وregion وpostal_code وcountry (حرفان) وphone وemail.
lanestring: saver أو fast. القيمة saver إن لم تُحدَّد.
packagingstring: اختياري. معرّف تغليف؛ الافتراضي لديك إن لم يُحدَّد.
notestring: اختياري. لفريق مستودعنا، حتى 500 حرف.

الأخطاء

الحالة	النوع	متى
400	bad-body	حقل مفقود أو خاطئ، ويشير إليه errors[].
409	duplicate-order	external_id طلب موجود أصلًا، ويذكره order.
422	unprocessable	متغيّر أحد البنود نفد، أو تعذّرت قراءة رابطه.
422	not-shippable	لا يوجد سعر منشور يصل إلى ship_to.country على ذلك الخط.

curl -X POST "https://www.ninjabuy.com/api/v1/orders" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "1012",
    "lines": [{ "variant": "var_41hz", "quantity": 1 }],
    "ship_to": {
      "name": "Sam Rivera",
      "line1": "500 Congress Ave",
      "city": "Austin",
      "region": "TX",
      "postal_code": "78701",
      "country": "US",
      "phone": "+15125550142",
      "email": "sam@example.com"
    },
    "lane": "saver"
  }'

Response 201

HTTP/2 201 Created

{
  "id": "ord_3n7q",
  "external_id": "1012",
  "source": "api",
  "status": "buying",
  "payment_status": "paid",
  "lane": "saver",
  "lines": [
    {
      "id": "lin_9a2c",
      "variant": "var_41hz",
      "sku": "5187209554",
      "title": "Heavyweight Washed Hoodie, Black / M",
      "quantity": 1,
      "units": 1,
      "status": "buying",
      "photos": [],
      "reason": null
    }
  ],
  "ship_to": {
    "name": "Sam Rivera",
    "line1": "500 Congress Ave",
    "line2": null,
    "city": "Austin",
    "region": "TX",
    "postal_code": "78701",
    "country": "US",
    "phone": "+15125550142",
    "email": "sam@example.com"
  },
  "packaging": "pkg_acme_mailer",
  "charges": {
    "procurement": {
      "goods": { "amount": "38.00", "currency": "CNY" },
      "intake_fee": { "amount": "12.00", "currency": "CNY" },
      "tax": { "amount": "7.00", "currency": "CNY" },
      "total": { "amount": "57.00", "currency": "CNY" }
    },
    "parcel": {
      "lane": "saver",
      "shipping": { "amount": "68.00", "currency": "CNY" },
      "handling_fee": { "amount": "50.00", "currency": "CNY" },
      "tax": { "amount": "16.52", "currency": "CNY" },
      "total": { "amount": "134.52", "currency": "CNY" },
      "estimate": true
    },
    "total": { "amount": "191.52", "currency": "CNY" }
  },
  "amount_due": null,
  "fulfillment_orders": [],
  "created_at": "2026-11-01T09:14:02Z",
  "updated_at": "2026-11-02T03:20:11Z"
}

عرض الطلبات

GET/v1/orders

الأحدث أولًا.

النطاقorders:read

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

statusstring: اختياري. إحدى الحالات أدناه.
sourcestring: اختياري. api أو shopify.
external_idstring: اختياري. ابحث عن طلب برقم طلبك الخاص.
created_sincestring: اختياري. وقت.
limit, cursor: Pagination

curl "https://www.ninjabuy.com/api/v1/orders?status=checked" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{
  "data": [
    {
      "id": "ord_3n7q",
      "external_id": "1012",
      "status": "checked",
      "payment_status": "paid"
    }
  ],
  "has_more": false,
  "cursor": null
}

جلب طلب

GET/v1/orders/{id}

حالة كل بند، وصوره في المستودع بعد فحصه، وتكلفته، وطروده.

النطاقorders:read

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

idstringمطلوب: معرّف الطلب.

الأخطاء

الحالة	النوع	متى
404	not-found	لا يوجد طلب كهذا في هذا الحساب.

curl "https://www.ninjabuy.com/api/v1/orders/ord_3n7q" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{
  "id": "ord_3n7q",
  "external_id": "1012",
  "source": "shopify",
  "status": "checked",
  "payment_status": "paid",
  "lane": "saver",
  "lines": [
    {
      "id": "lin_9a2c",
      "variant": "var_41hz",
      "sku": "5187209554",
      "title": "Heavyweight Washed Hoodie, Black / M",
      "quantity": 1,
      "units": 1,
      "status": "checked",
      "photos": [
        "https://media.ninjabuy.com/qc/ord_3n7q/1.webp",
        "https://media.ninjabuy.com/qc/ord_3n7q/2.webp"
      ],
      "reason": null
    }
  ],
  "ship_to": {
    "name": "Sam Rivera",
    "line1": "500 Congress Ave",
    "line2": null,
    "city": "Austin",
    "region": "TX",
    "postal_code": "78701",
    "country": "US",
    "phone": "+15125550142",
    "email": "sam@example.com"
  },
  "packaging": "pkg_acme_mailer",
  "charges": {
    "procurement": {
      "goods": { "amount": "38.00", "currency": "CNY" },
      "intake_fee": { "amount": "12.00", "currency": "CNY" },
      "tax": { "amount": "7.00", "currency": "CNY" },
      "total": { "amount": "57.00", "currency": "CNY" }
    },
    "parcel": {
      "lane": "saver",
      "shipping": { "amount": "68.00", "currency": "CNY" },
      "handling_fee": { "amount": "50.00", "currency": "CNY" },
      "tax": { "amount": "16.52", "currency": "CNY" },
      "total": { "amount": "134.52", "currency": "CNY" },
      "estimate": true
    },
    "total": { "amount": "191.52", "currency": "CNY" }
  },
  "amount_due": null,
  "fulfillment_orders": ["fo_7k2m"],
  "created_at": "2026-11-01T09:14:02Z",
  "updated_at": "2026-11-02T03:20:11Z"
}

إلغاء طلب

POST/v1/orders/{id}/cancel

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

النطاقorders:write

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

idstringمطلوب: معرّف الطلب.

النص

reasonstring: اختياري. يُحفظ مع الطلب.

الأخطاء

الحالة	النوع	متى
404	not-found	لا يوجد طلب كهذا في هذا الحساب.
409	invalid-state	تم شحنه.

curl -X POST "https://www.ninjabuy.com/api/v1/orders/ord_3n7q/cancel" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Customer changed their mind" }'

Response 200

HTTP/2 200 OK

{
  "id": "ord_3n7q",
  "status": "cancelled",
  "payment_status": "refunded",
  "refunded": { "amount": "191.52", "currency": "CNY" }
}

الحالات

لكل بند حالته، وحالة الطلب هي حالة أقل بنوده تقدّمًا. بالترتيب:

الحالة	المعنى
awaiting_payment	لم يغطّه رصيدك. اشحن رصيدك فيتابع تلقائيًا.
buying	مدفوع؛ نشتريه من البائع.
with_seller	تم الشراء، ولم يرسله البائع إلى مستودعنا بعد.
checked	في مستودعنا، مفحوص ومصوَّر، ينتظر التغليف.
shipped	في طريقه، مع التتبّع.
delivered	تقول شركة الشحن إنه وصل.
rejected	لم نستطع شراءه (نافد، أو الرابط لم يعد موجودًا)؛ يوضح reason السبب، ويُعاد المبلغ.
cancelled	ألغيته أنت.

المال

في العيّنات، شراء قطعة واحدة يكلّف ‏57.00 CN¥‎ وشحنها ‏134.52 CN¥‎، يُخصمان من رصيدك. ما يمثّله كل بند: الرسوم.

كائن Order

إنشاء طلب

النص

الأخطاء

عرض الطلبات

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

جلب طلب

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

الأخطاء

إلغاء طلب

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

النص

الأخطاء

الحالات

المال