Siparişler API'si2026-11Önizleme

Fulfillment siparişleri

Bir siparişin tek pakete koyduğumuz satırları; konuldukları kutu ve her ürün için kontrolümüzle birlikte.

Çoğu siparişin bir tane vardır. Ürünleri birbirinden çok farklı zamanlarda gelen ya da sizin böldüğünüz bir siparişin daha fazlası olur.
Bir Shopify siparişi, Shopify'ın kendi fulfillment talebi olarak gelir. Her satır bir SKU ile eşleştiğinde (Varyantlar) kabul ederiz; eşleşmeyen satırları belirterek reddederiz, böylece Shopify siparişi sizde tutar.
Kontrolümüzden geçemeyen bir ürün qc.issue olayını tetikler ve gönderilmeden önce seçiminizi bekler.

Uç noktalar

GET/v1/fulfillment_ordersFulfillment siparişlerini listele
GET/v1/fulfillment_orders/{id}Fulfillment siparişini getir
POST/v1/fulfillment_orders/{id}/holdBeklet
POST/v1/fulfillment_orders/{id}/releaseBloke kaldırma
POST/v1/fulfillment_orders/{id}/cancelİptal

Fulfillment order nesnesi

idstring: fo_ ile başlar.
orderstring: Ait olduğu sipariş.
statusstring: open (ürünlerini bekliyor), in_progress (paketleniyor), on_hold, closed (gönderildi) ya da cancelled.
requestobject|null: Bir Shopify siparişi için: Shopify'ın fulfillment siparişi ve ona verdiğimiz yanıt; kabul ya da bir SKU ile eşlenmemiş mağaza varyantlarıyla birlikte ret.
holdobject|null: Bekletmedeyken reason ve note.
packagingstring|null: İçine konduğu kutu ya da kargo poşeti.
lines[].qcobject: Kontrolümüz: fotoğraflar ve zamanıyla birlikte pending, passed ya da issue.
shipmentstring|null: Yola çıktığında ayarlanır.

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"
}

Fulfillment siparişlerini listele

GET/v1/fulfillment_orders

En yenisi önce. Siparişe ya da duruma göre filtreleyin.

Kapsamorders:read

Sorgu parametreleri

orderstring: İsteğe bağlı. Bir sipariş id'si.
statusstring: İsteğe bağlı.
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
}

Fulfillment siparişini getir

GET/v1/fulfillment_orders/{id}

Satırları, her biri için kontrolümüz, ambalaj ve gönderi.

Kapsamorders:read

Yol parametreleri

idstringzorunlu: Fulfillment siparişinin id'si.

Hatalar

Durum	Tür	Ne zaman
404	not-found	Bu hesapta böyle bir fulfillment siparişi yok.

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"
}

Beklet

POST/v1/fulfillment_orders/{id}/hold

Siz serbest bırakana kadar gönderilmesini engeller: aynı müşteriye giden başka bir siparişi ya da gönderdiğiniz stoğu beklemek için. Rafınızdaki ücretsiz depolama süresi işlemeye devam eder.

Kapsamorders:write

Yol parametreleri

idstringzorunlu: Fulfillment siparişinin id'si.

Gövde

reasonstringzorunlu: combine, wait_for_stock ya da other.
notestring: İsteğe bağlı. Bekletmeyle birlikte kaydedilen, kendiniz için bir not.

Hatalar

Durum	Tür	Ne zaman
404	not-found	Bu hesapta böyle bir fulfillment siparişi yok.
409	invalid-state	Kapatıldı ya da iptal edildi.

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"
}

Bloke kaldırma

POST/v1/fulfillment_orders/{id}/release

Bekletilen bir fulfillment siparişinin devam etmesini sağlar.

Kapsamorders:write

Yol parametreleri

idstringzorunlu: Fulfillment siparişinin id'si.

Hatalar

Durum	Tür	Ne zaman
404	not-found	Bu hesapta böyle bir fulfillment siparişi yok.
409	invalid-state	Bekletilmiyor.

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"
}

İptal

POST/v1/fulfillment_orders/{id}/cancel

İçine henüz hiçbir şey paketlenmemişken paketi iptal eder. Ürünleri, daha sonra ya da başka bir siparişle gönderilmek üzere rafınızda kalır. Satın almayı da iptal etmek için siparişi iptal edin.

Kapsamorders:write

Yol parametreleri

idstringzorunlu: Fulfillment siparişinin id'si.

Hatalar

Durum	Tür	Ne zaman
404	not-found	Bu hesapta böyle bir fulfillment siparişi yok.
409	invalid-state	Paketlendi ya da gönderildi.

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"
}