Siparişler API'si2026-11Önizleme

Siparişler

Satıcıdan satın aldığımız, depomuzda kontrol edip fotoğrafladığımız, kutunuza paketleyip müşterinize gönderdiğimiz bir satışınız.

Bir siparişi sorgulamak yerine webhook'larla takip edin: her adım gerçekleştikçe sipariş olayları tetiklenir. Paketin kendisi önce bir fulfillment siparişi, sonra bir gönderidir.

Uç noktalar

POST/v1/ordersSipariş oluştur
GET/v1/ordersSiparişleri listele
GET/v1/orders/{id}Siparişi getir
POST/v1/orders/{id}/cancelSipariş iptal et

Order nesnesi

idstring: ord_ ile başlar.
external_idstring: Mağazanızın sipariş numarası. Hesabınızda benzersizdir.
sourcestring: api ya da Shopify mağazanızın bize gönderdiği siparişler için shopify.
statusstring: En az ilerlemiş satırın durumu; aşağıdaki Durumlar'a bakın.
payment_statusstring: awaiting_payment, paid, partially_refunded ya da refunded.
lanestring: saver ya da fast.
lines[]array: Varyant, miktar, ürün başına satın alınan adet, durum, kontrol edildikten sonra depo fotoğrafları ve reddedildiğinde reason.
ship_toobject: Müşterinizin adı, adresi, telefonu ve e-postası.
packagingstring|null: Markalı kutunuz ya da kargo poşetiniz; null ise varsayılanınız.
chargesobject: CN¥ cinsinden maliyeti: satın alma (ürün bedeli, kabul ücreti, vergi) ve paket (kargo, işlem ücreti, vergi). Paket, biz tartana kadar ağırlıklarınızdan yapılmış bir tahmindir.
amount_duemoney|null: awaiting_payment durumundayken bakiyenizin hâlâ karşılaması gereken tutar.
fulfillment_orders[]array: Çıktığı paketler.

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

Mağazanızın siparişlerinden birini bize gönderin. Her satır, kaydettiğiniz bir varyant ya da olduğu gibi satın aldığımız bir ilan bağlantısı ve SKU'dur. Sipariş hemen bakiyenizden ödenir; bakiyenizin karşılayamadığı bir sipariş yine de amount_due ile awaiting_payment olarak oluşturulur ve bakiye yüklediğinizde kendiliğinden ilerler.

Shopify mağazanızdan gelen siparişler bu çağrı olmadan bize ulaşır. Bunu WooCommerce, Wix, kendi siteniz ya da satış yapan başka herhangi bir şey için kullanın.

Kapsamorders:write

Gövde

external_idstringzorunlu: Sipariş numaranız. Aynı numarayla ikinci bir sipariş reddedilir.
lines[]arrayzorunlu: variant ve quantity ya da url, sku ve quantity. units (isteğe bağlı), paketler için ürün başına o kadar adet satın alır.
ship_toobjectzorunlu: name, line1, line2, city, region, postal_code, country (iki harf), phone, email.
lanestring: saver ya da fast. Belirtilmezse saver.
packagingstring: İsteğe bağlı. Bir ambalaj id'si; belirtilmezse varsayılanınız.
notestring: İsteğe bağlı. Depo ekibimiz için, en fazla 500 karakter.

Hatalar

Durum	Tür	Ne zaman
400	bad-body	Bir alan eksik ya da hatalı; errors[] hangisi olduğunu gösterir.
409	duplicate-order	external_id zaten bir sipariş; order onu belirtir.
422	unprocessable	Bir satırın varyantı tükenmiş ya da bağlantısı okunamıyor.
422	not-shippable	O hatta ship_to.country'ye ulaşan yayımlanmış bir fiyat yok.

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

Siparişleri listele

GET/v1/orders

En yenisi önce.

Kapsamorders:read

Sorgu parametreleri

statusstring: İsteğe bağlı. Aşağıdaki durumlardan biri.
sourcestring: İsteğe bağlı. api ya da shopify.
external_idstring: İsteğe bağlı. Kendi sipariş numaranızla bir sipariş bulun.
created_sincestring: İsteğe bağlı. Bir zaman.
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
}

Siparişi getir

GET/v1/orders/{id}

Her satırın durumu, kontrol edildikten sonra depo fotoğrafları, maliyeti ve paketleri.

Kapsamorders:read

Yol parametreleri

idstringzorunlu: Siparişin id'si.

Hatalar

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

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

Sipariş iptal et

POST/v1/orders/{id}/cancel

Satın almadan önce siparişin tamamı bakiyenize iade edilir. Satın alındıktan sonra satıcının geri aldığı satırlar iade edilir, kalanlar depo stoğu olarak rafınızda kalır. Gönderilmiş bir sipariş iptal edilemez.

Kapsamorders:write

Yol parametreleri

idstringzorunlu: Siparişin id'si.

Gövde

reasonstring: İsteğe bağlı. Siparişte saklanır.

Hatalar

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

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

Durumlar

Her satırın kendi durumu vardır; siparişin durumu en az ilerlemiş satırınkidir. Sırasıyla:

Durum	Anlamı
awaiting_payment	Bakiyeniz karşılamadı. Bakiye yükleyin, kendiliğinden ilerler.
buying	Ödendi; satıcıdan satın alıyoruz.
with_seller	Satın alındı; satıcı henüz depomuza göndermedi.
checked	Depomuzda, kontrol edilmiş ve fotoğraflanmış, paketlenmeyi bekliyor.
shipped	Yolda, takip bilgisiyle.
delivered	Kargo firması ulaştığını bildiriyor.
rejected	Satın alamadık (tükendi, bağlantı kaldırıldı); reason nedenini söyler ve tutar iade edilir.
cancelled	Siz iptal ettiniz.

Para

Örneklerde bir adet satın almak CN¥57,00, göndermek CN¥134,52 tutar ve bakiyenizden alınır. Her satırın ne olduğu: Ücretler.

Order nesnesi

Sipariş oluştur

Gövde

Hatalar

Siparişleri listele

Sorgu parametreleri

Siparişi getir

Yol parametreleri

Hatalar

Sipariş iptal et

Yol parametreleri

Gövde

Hatalar

Durumlar

Para