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

أوامر التنفيذ

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

لمعظم الطلبات شحنة واحدة. الطلب الذي تصل قطعه في أوقات متباعدة، أو الذي تقسّمه، له أكثر.
يصل طلب Shopify كطلب تنفيذ من Shopify نفسه. نقبله حين يكون كل بند مربوطًا بـ SKU (المتغيّرات)، ونرفضه مع ذكر البنود غير المربوطة، فيبقيه Shopify لديك.
القطعة التي لا تجتاز فحصنا تُطلق qc.issue وتنتظر قرارك قبل الشحن.

نقاط النهاية

GET/v1/fulfillment_ordersعرض أوامر التنفيذ
GET/v1/fulfillment_orders/{id}جلب أمر تنفيذ
POST/v1/fulfillment_orders/{id}/holdتعليق
POST/v1/fulfillment_orders/{id}/releaseتحرير
POST/v1/fulfillment_orders/{id}/cancelإلغاء

كائن Fulfillment order

idstring: يبدأ بـ fo_.
orderstring: الطلب الذي ينتمي إليه.
statusstring: open (ينتظر قطعه) أو in_progress (قيد التغليف) أو on_hold أو closed (مشحون) أو cancelled.
requestobject|null: لطلب Shopify: أمر التنفيذ من Shopify وردّنا عليه، مقبولًا، أو مرفوضًا مع متغيّرات المتجر غير المربوطة بـ SKU.
holdobject|null: reason وnote، أثناء التعليق.
packagingstring|null: العلبة أو المغلّف البريدي الذي يوضع فيه.
lines[].qcobject: فحصنا: pending أو passed أو issue، مع الصور والوقت.
shipmentstring|null: يُضبط بعد مغادرته.

fulfillment_order

{
  "id": "fo_7k2m",
  "order": "ord_3n7q",
  "status": "in_progress",
  "request": {
    "channel": "shopify",
    "external_id": "gid://shopify/FulfillmentOrder/6650012",
    "status": "accepted",
    "unmapped": []
  },
  "hold": null,
  "packaging": "pkg_acme_mailer",
  "lines": [
    {
      "line": "lin_9a2c",
      "sku": "5187209554",
      "quantity": 1,
      "qc": {
        "status": "passed",
        "photos": [
          "https://media.ninjabuy.com/qc/ord_3n7q/1.webp",
          "https://media.ninjabuy.com/qc/ord_3n7q/2.webp"
        ],
        "checked_at": "2026-11-02T03:20:11Z"
      }
    }
  ],
  "shipment": null,
  "created_at": "2026-11-01T09:14:03Z"
}

عرض أوامر التنفيذ

GET/v1/fulfillment_orders

الأحدث أولًا. صفِّ حسب الطلب أو الحالة.

النطاقorders:read

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

orderstring: اختياري. معرّف طلب.
statusstring: اختياري.
limit, cursor: Pagination

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

Response 200

HTTP/2 200 OK

{
  "data": [
    {
      "id": "fo_7k1x",
      "order": "ord_3n6z",
      "status": "on_hold",
      "hold": { "reason": "combine" }
    }
  ],
  "has_more": false,
  "cursor": null
}

جلب أمر تنفيذ

GET/v1/fulfillment_orders/{id}

بنوده، وفحصنا لكل منها، والتغليف، والشحنة.

النطاقorders:read

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

idstringمطلوب: معرّف أمر التنفيذ.

الأخطاء

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

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

Response 200

HTTP/2 200 OK

{
  "id": "fo_7k2m",
  "order": "ord_3n7q",
  "status": "in_progress",
  "request": {
    "channel": "shopify",
    "external_id": "gid://shopify/FulfillmentOrder/6650012",
    "status": "accepted",
    "unmapped": []
  },
  "hold": null,
  "packaging": "pkg_acme_mailer",
  "lines": [
    {
      "line": "lin_9a2c",
      "sku": "5187209554",
      "quantity": 1,
      "qc": {
        "status": "passed",
        "photos": [
          "https://media.ninjabuy.com/qc/ord_3n7q/1.webp",
          "https://media.ninjabuy.com/qc/ord_3n7q/2.webp"
        ],
        "checked_at": "2026-11-02T03:20:11Z"
      }
    }
  ],
  "shipment": null,
  "created_at": "2026-11-01T09:14:03Z"
}

تعليق

POST/v1/fulfillment_orders/{id}/hold

يمنع شحنه حتى تُفرج عنه: لانتظار طلب آخر للعميل نفسه، أو لمخزون ترسله. التخزين المجاني على رفّك يستمر في الاحتساب.

النطاقorders:write

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

idstringمطلوب: معرّف أمر التنفيذ.

النص

reasonstringمطلوب: combine أو wait_for_stock أو other.
notestring: اختياري. ملاحظة لك، تُحفظ مع الإيقاف.

الأخطاء

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

curl -X POST "https://www.ninjabuy.com/api/v1/fulfillment_orders/fo_7k2m/hold" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "combine" }'

Response 200

HTTP/2 200 OK

{
  "id": "fo_7k2m",
  "order": "ord_3n7q",
  "status": "on_hold",
  "request": {
    "channel": "shopify",
    "external_id": "gid://shopify/FulfillmentOrder/6650012",
    "status": "accepted",
    "unmapped": []
  },
  "hold": {
    "reason": "combine",
    "note": null,
    "since": "2026-11-02T04:00:00Z"
  },
  "packaging": "pkg_acme_mailer",
  "lines": [
    {
      "line": "lin_9a2c",
      "sku": "5187209554",
      "quantity": 1,
      "qc": {
        "status": "passed",
        "photos": [
          "https://media.ninjabuy.com/qc/ord_3n7q/1.webp",
          "https://media.ninjabuy.com/qc/ord_3n7q/2.webp"
        ],
        "checked_at": "2026-11-02T03:20:11Z"
      }
    }
  ],
  "shipment": null,
  "created_at": "2026-11-01T09:14:03Z"
}

تحرير

POST/v1/fulfillment_orders/{id}/release

يتيح لأمر تنفيذ معلّق أن يتابع.

النطاقorders:write

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

idstringمطلوب: معرّف أمر التنفيذ.

الأخطاء

الحالة	النوع	متى
404	not-found	لا يوجد أمر تنفيذ كهذا في هذا الحساب.
409	invalid-state	ليس معلّقًا.

curl -X POST "https://www.ninjabuy.com/api/v1/fulfillment_orders/fo_7k2m/release" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)"

Response 200

HTTP/2 200 OK

{
  "id": "fo_7k2m",
  "order": "ord_3n7q",
  "status": "in_progress",
  "request": {
    "channel": "shopify",
    "external_id": "gid://shopify/FulfillmentOrder/6650012",
    "status": "accepted",
    "unmapped": []
  },
  "hold": null,
  "packaging": "pkg_acme_mailer",
  "lines": [
    {
      "line": "lin_9a2c",
      "sku": "5187209554",
      "quantity": 1,
      "qc": {
        "status": "passed",
        "photos": [
          "https://media.ninjabuy.com/qc/ord_3n7q/1.webp",
          "https://media.ninjabuy.com/qc/ord_3n7q/2.webp"
        ],
        "checked_at": "2026-11-02T03:20:11Z"
      }
    }
  ],
  "shipment": null,
  "created_at": "2026-11-01T09:14:03Z"
}

إلغاء

POST/v1/fulfillment_orders/{id}/cancel

يلغي الطرد ما دام لم يُغلَّف فيه شيء. تبقى قطعه على رفّك، لتُشحن لاحقًا أو مع طلب آخر. لإلغاء الشراء أيضًا، ألغِ الطلب.

النطاقorders:write

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

idstringمطلوب: معرّف أمر التنفيذ.

الأخطاء

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

curl -X POST "https://www.ninjabuy.com/api/v1/fulfillment_orders/fo_7k2m/cancel" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)"

Response 200

HTTP/2 200 OK

{
  "id": "fo_7k2m",
  "order": "ord_3n7q",
  "status": "cancelled",
  "request": {
    "channel": "shopify",
    "external_id": "gid://shopify/FulfillmentOrder/6650012",
    "status": "accepted",
    "unmapped": []
  },
  "hold": null,
  "packaging": "pkg_acme_mailer",
  "lines": [
    {
      "line": "lin_9a2c",
      "sku": "5187209554",
      "quantity": 1,
      "qc": {
        "status": "passed",
        "photos": [
          "https://media.ninjabuy.com/qc/ord_3n7q/1.webp",
          "https://media.ninjabuy.com/qc/ord_3n7q/2.webp"
        ],
        "checked_at": "2026-11-02T03:20:11Z"
      }
    }
  ],
  "shipment": null,
  "created_at": "2026-11-01T09:14:03Z"
}