Geliştiriciler2026-11Önizleme

NinjaBuy Business API'si

Taobao, Weidian ve 1688'den ürün içe aktarın, fiyat ve stoğu senkronize tutun, her siparişi Çin'deki satıcıdan depo kontrolümüze, oradan müşterinizin kapısına kadar takip edin. HTTPS üzerinden JSON, tek hesap, tek bakiye.

Temel URL

Bu sitedeki her rota tek bir temel URL altındadır. Shopify uygulaması ve sizin geliştirdiğiniz her şey aynı rotaları çağırır; uygulamanın yaptığı her şeyi kodunuz da yapabilir.

https://www.ninjabuy.com/api/v1

Bir yapay zekâ asistanına sormayı mı tercih edersiniz? Aynı hesap MCP üzerinden https://www.ninjabuy.com/mcp adresinde çalışır: Yapay zekâ asistanları (MCP).

Katalog

İçe aktarmalarBir bağlantı girer, tam satış maliyeti çıkar.
ÜrünlerNe sattığınız ve nerede listelendiği.
VaryantlarSatıcının SKU'suna bağlı her seçenek.
Stok seviyeleriŞu anda satabilecekleriniz.
Senkronizasyon kurallarıBir satıcı fiyatı değiştirdiğinde ne olur.

Siparişler

SiparişlerSatın aldığımız, kontrol ettiğimiz ve gönderdiğimiz bir satış.
Fulfillment siparişleriTek pakette çıkan satırlar.
GönderilerTakip bilgisiyle yoldaki paketler.

Hesap

BakiyeSiparişlerin ödendiği para.
Webhook uç noktalarıOlayları gönderdiğimiz yer.

İlk çağrınız

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

Kimlik doğrulama

Her istekte bir API anahtarını bearer token olarak gönderin. Anahtarlar nb_ ile başlar. Önizleme süresince anahtarları ekibimiz verir: Business hesabınız kurulduktan sonra her anahtarı, istediğiniz kapsamlarla, seçtiğiniz bir kanaldan bir kez göndeririz. Birini iptal etmemizi isteyin, bir sonraki istekte çalışmayı bırakır.

Anahtarları sunucunuzda tutun. Tarayıcıdaki, uygulamadaki ya da herkese açık bir depodaki anahtarı herkes okuyabilir ve bakiyenizi harcayabilir.

Diğer NinjaBuy satıcıları adına hareket eden bir uygulama bunun yerine OAuth 2.1 kullanır: dinamik istemci kaydı, PKCE (S256) ile yetkilendirme kodu akışı ve satıcının kendi onay ekranı. Erişim token'ı aynı başlığa konur ve aynı rotalarda çalışır. Erişim token'ları bir saat geçerlidir; yenileme token'ları bunları yedi gün boyunca yeniler. Yapay zekâ asistanları da aynı şekilde bağlanır (MCP).

products:readkapsam: İçe aktarmaları, ürünleri, varyantları ve senkronizasyon kurallarını okuyun.
products:writekapsam: Ürünleri içe aktarın, düzenleyin, gönderin ve silin; senkronizasyon kurallarını değiştirin.
inventory:readkapsam: Stok seviyelerini okuyun.
orders:readkapsam: Siparişleri, fulfillment siparişlerini ve gönderileri okuyun.
orders:writekapsam: Sipariş oluşturun, bekletin, serbest bırakın ve iptal edin. Bakiyenizden harcar.
balance:readkapsam: Bakiyeyi ve işlemlerini okuyun.
webhooks:writekapsam: Webhook uç noktalarını yönetin.

Bir anahtarın kapsamları dışındaki çağrı 403 insufficient-scope yanıtı verir ve gereken kapsamı belirtir.

Başlık

Authorization: Bearer nb_7Qk2...vX9e

Response 401

HTTP/2 401

{
  "type": "https://www.ninjabuy.com/api/v1/problems/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "The API key is missing, wrong, expired or revoked.",
  "request_id": "req_7Hq2Lw9c"
}

Sürümleme

Yol, ana sürümü taşır: /v1. Bunun içinde tarihli sürümler alanları ve davranışı değiştirir. Geliştirdiğiniz sürümü NinjaBuy-Version başlığıyla sabitleyin; her yanıt kullandığı sürümü aynı başlıkta belirtir.

2026-11 güncel sürümdür ve önizleme aşamasındadır: kararlı olarak işaretlenmeden önce adlar ve alanlar değişebilir. Her değişiklik değişiklik günlüğünde yer alır ve sizi etkileyebilecek bir değişiklikten önce her anahtar sahibine e-posta göndeririz.

Bir sürüm içinde yalnızca ekleme yaparız: yeni rotalar, yeni isteğe bağlı parametreler, yanıtlarda yeni alanlar ve yeni olay türleri. İstemcinizi bilmediği alanları yok sayacak şekilde geliştirin.

Sürüm sabitleme

GET /api/v1/orders
NinjaBuy-Version: 2026-11

HTTP/2 200
NinjaBuy-Version: 2026-11

İstekler ve yanıtlar

Content-Type: application/json ile JSON gönderin; yanıtlar UTF-8 JSON'dur. Hatalar application/problem+json biçimindedir.
Para, ondalık bir dize ve para biriminden oluşan bir nesnedir: { "amount": "264.20", "currency": "CNY" }. NinjaBuy'ın ücretleri CN¥ cinsindendir; satış fiyatlarınız mağazanızın para birimindedir.
Id'ler türlerini belirten bir önekle başlayan dizelerdir (prd_, ord_, shp_). Onları opak kabul edin.
Zamanlar UTC cinsinden ISO 8601'dir. Ülkeler iki harfli ISO kodlarıdır.
Her yanıt bir X-Request-Id başlığı taşır ve her hata aynı id'yi request_id olarak taşır. Bize yazarken belirtin.

Para, id'ler ve tarihler

{
  "id": "ord_3n7q",
  "created_at": "2026-11-01T09:14:02Z",
  "total": { "amount": "264.20", "currency": "CNY" },
  "suggested_price": { "amount": "49.99", "currency": "USD" }
}

Sayfalama

Listeler en yeniden başlayarak data, has_more ve cursor olarak yanıt verir. has_more true olduğu sürece bir sonraki sayfa için o cursor'ı geri gönderin. Bir cursor yalnızca geldiği filtrelerle çalışır.

limitinteger: 1 ile 100 arası. Belirtilmezse 25.
cursorstring: Önceki sayfanın cursor'ı. İlk sayfa için boş bırakın.

curl "https://www.ninjabuy.com/api/v1/orders?limit=25&cursor=c_2v9kq" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{
  "data": [
    { "id": "ord_3n7q", "status": "checked" },
    { "id": "ord_3n6z", "status": "shipped" }
  ],
  "has_more": true,
  "cursor": "c_1q4ea"
}

Hız sınırları

Sınırlar hesap başınadır; hesabın tüm anahtarları, OAuth token'ları ve MCP bağlantısı tarafından paylaşılır. Her yanıt, IETF RateLimit-Policy ve RateLimit başlıklarında ne durumda olduğunuzu söyler; ret, saniye cinsinden Retry-After ile 429 rate-limited yanıtıdır.

Pencere	Neler sayılır
"create-links";q=30;w=60	Pazaryerinden bir ilanı okuyan çağrılar: içe aktarma oluşturma ya da yenileme, ürün gönderme. Dakikada 30, bağlantı API'si ve MCP ile ortak.
"default";q=120;w=60	Diğer tüm çağrılar. Dakikada 120.

Yanıt 429

HTTP/2 429
Content-Type: application/problem+json
Retry-After: 12
RateLimit-Policy: "create-links";q=30;w=60
RateLimit: "create-links";r=0;t=12

{
  "type": "https://www.ninjabuy.com/api/v1/problems/rate-limited",
  "title": "Too many requests",
  "status": 429,
  "detail": "Try again in 12 seconds.",
  "request_id": "req_7Hq2Lw9c"
}

Idempotency

Her POST isteğinde bir Idempotency-Key (1 ile 255 arası yazdırılabilir ASCII karakter; ideali bir UUID) gönderin; zaman aşımından sonra yeniden deneme ikinci bir sipariş oluşturamaz. 24 saat boyunca aynı rota ve aynı gövdeyle aynı anahtar, ilk yanıtı bayt bayt aynı şekilde Idempotent-Replayed: true ile yeniden döndürür; yeniden çalışmaz ve bir sınıra sayılmaz.

Farklı bir gövde ya da rotayla aynı anahtar: 422 idempotency-key-reused.
İlk istek hâlâ çalışıyor: Retry-After ile 409 idempotency-key-in-progress.
Hız sınırı reddi bir yanıt değildir: anahtar serbest kalır, bu yüzden Retry-After sonrasında yeniden denemek isteği çalıştırır.

Siparişler kendi external_id değerinizi de taşır: aynı değere sahip ikinci bir sipariş, hangi anahtarla gönderilmiş olursa olsun 409 duplicate-order ile reddedilir.

Yeniden denenen bir istek

POST /api/v1/orders
Idempotency-Key: 4f0c2b4e-9d1a-4e0f-b0a8-5d1d3c7e2f61

HTTP/2 201
Idempotent-Replayed: true
X-Request-Id: req_7Hq2Lw9c

Hatalar

Hatalar problem JSON'dur (RFC 9457): type dallanma için sabit bir URL'dir, title onu adlandırır, detail bu durumu gösterebileceğiniz kelimelerle açıklar ve request_id onu kayıtlarımızda bulur. Doğrulamadan geçemeyen bir gövde, her biri alana işaret eden bir JSON pointer içeren errors ekler.

Durum	Tür	Ne zaman
400	bad-json	Gövde JSON değil.
400	bad-body	Bir alan eksik ya da hatalı; errors[] hangisi olduğunu gösterir.
400	bad-idempotency-key	Idempotency-Key boş, çok uzun ya da yazdırılabilir ASCII değil.
401	unauthorized	Anahtar ya da token eksik, hatalı, süresi dolmuş ya da iptal edilmiş.
403	insufficient-scope	Anahtarda rotanın gerektirdiği kapsam yok.
404	not-found	Bu hesapta böyle bir nesne yok. Başka bir hesabın id'leri de aynı yanıtı alır.
405	method-not-allowed	Rota var ama bu yöntemle değil; Allow kabul ettiklerini listeler.
409	duplicate-order	Bu external_id ile bir sipariş var; order onu belirtir.
409	idempotency-key-in-progress	Bu anahtarla yapılan ilk istek hâlâ çalışıyor.
409	invalid-state	Nesne bunu şu anda yapamaz; örneğin gönderilmiş bir siparişi iptal etmek.
415	unsupported-media-type	Gövde application/json değil.
422	idempotency-key-reused	Anahtar farklı bir istek için kullanıldı.
422	unprocessable	Üzerinde işlem yapamadığımız geçerli JSON: okunamayan bir bağlantı, tükenmiş bir varyant. detail hangisi olduğunu söyler.
429	rate-limited	Pencerede çok fazla çağrı. Retry-After kadar saniye bekleyin.
500	internal-error	Bizim hatamız. Aynı Idempotency-Key ile yeniden deneyin.
503	service-unavailable	Şu anda anahtarı kontrol edemedik ya da bir mağazaya ulaşamadık. Retry-After sonrasında yeniden deneyin.

Response 400

HTTP/2 400

{
  "type": "https://www.ninjabuy.com/api/v1/problems/bad-body",
  "title": "Invalid request body",
  "status": 400,
  "detail": "1 field is invalid.",
  "request_id": "req_7Hq2Lw9c",
  "errors": [
    {
      "pointer": "/ship_to/country",
      "detail": "Must be a two-letter country code."
    }
  ]
}