Deweloperzy2026-11Podgląd

NinjaBuy Business API

Importuj produkty z Taobao, Weidian i 1688, synchronizuj ich ceny i stany i śledź każde zamówienie od sprzedawcy w Chinach, przez kontrolę w naszym magazynie, pod drzwi klienta. JSON przez HTTPS, jedno konto, jedno saldo.

Bazowy URL

Każda trasa na tej stronie znajduje się pod jednym bazowym URL. Aplikacja Shopify i wszystko, co budujesz, wywołuje te same trasy, więc cokolwiek robi aplikacja, może to zrobić też twój kod.

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

Wolisz zapytać asystenta AI? To samo konto działa przez MCP pod https://www.ninjabuy.com/mcp: Asystenci AI (MCP).

Katalog

ImportyLink na wejściu, pełny koszt sprzedaży na wyjściu.
ProduktyCo sprzedajesz i gdzie jest wystawione.
WariantyKażda opcja, powiązana z SKU sprzedawcy.
Stany magazynoweCo możesz sprzedać teraz.
Reguły synchronizacjiCo się dzieje, gdy sprzedawca zmienia cenę.

Zamówienia

ZamówieniaSprzedaż, którą kupujemy, sprawdzamy i wysyłamy.
Zlecenia realizacjiPozycje wychodzące w jednej paczce.
PrzesyłkiPaczki w drodze, z numerem śledzenia.

Konto

SaldoŚrodki, z których opłacane są zamówienia.
Endpointy webhookówDokąd wysyłamy zdarzenia.

Twoje pierwsze wywołanie

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

Uwierzytelnianie

Wysyłaj klucz API jako token bearer w każdym żądaniu. Klucze zaczynają się od nb_. W okresie wersji zapoznawczej wydaje je nasz zespół: gdy twoje konto Business jest skonfigurowane, wysyłamy każdy klucz raz, wybranym przez ciebie kanałem, z zakresami, o które prosiłeś. Poproś nas o unieważnienie klucza, a przestanie działać od następnego żądania.

Trzymaj klucze na serwerze. Klucz w przeglądarce, aplikacji lub publicznym repozytorium może przeczytać każdy i może on wydać twoje saldo.

Aplikacja działająca w imieniu innych sprzedawców NinjaBuy używa zamiast tego OAuth 2.1: dynamicznej rejestracji klienta, przepływu authorization code z PKCE (S256) i własnego ekranu zatwierdzenia sprzedawcy. Jej token dostępu trafia do tego samego nagłówka i działa na tych samych trasach. Tokeny dostępu ważne są godzinę; tokeny odświeżania odnawiają je przez siedem dni. Asystenci AI łączą się tak samo (MCP).

products:readscope: Odczyt importów, produktów, wariantów i reguł synchronizacji.
products:writescope: Import, edycja, wysyłanie i usuwanie produktów; zmiana reguł synchronizacji.
inventory:readscope: Odczyt stanów magazynowych.
orders:readscope: Odczyt zamówień, zleceń realizacji i przesyłek.
orders:writescope: Tworzenie, wstrzymywanie, zwalnianie i anulowanie zamówień. Wydaje twoje saldo.
balance:readscope: Odczyt salda i jego transakcji.
webhooks:writescope: Zarządzanie endpointami webhooków.

Wywołanie poza zakresami klucza zwraca 403 insufficient-scope i podaje potrzebny zakres.

Nagłówek

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

Wersjonowanie

Ścieżka zawiera główną wersję, /v1. W jej ramach wersje datowane zmieniają pola i zachowanie. Przypnij tę, pod którą budowałeś, nagłówkiem NinjaBuy-Version; każda odpowiedź podaje użytą wersję w tym samym nagłówku.

2026-11 to bieżąca wersja i jest to wersja zapoznawcza: nazwy i pola mogą się jeszcze zmienić, zanim zostanie oznaczona jako stabilna. Każda zmiana jest w dzienniku zmian, a przed zmianą, która mogłaby coś zepsuć, piszemy e-mailem do każdego posiadacza klucza.

W ramach wersji tylko dodajemy: nowe trasy, nowe opcjonalne parametry, nowe pola w odpowiedziach i nowe typy zdarzeń. Zbuduj klienta tak, by ignorował pola, których nie zna.

Przypnij wersję

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

HTTP/2 200
NinjaBuy-Version: 2026-11

Żądania i odpowiedzi

Wysyłaj JSON z Content-Type: application/json; odpowiedzi to JSON w UTF-8. Błędy to application/problem+json.
Kwota to obiekt z ciągiem dziesiętnym i walutą: { "amount": "264.20", "currency": "CNY" }. To, co nalicza NinjaBuy, jest w CN¥; twoje ceny sprzedaży są w walucie twojego sklepu.
ID to ciągi znaków z prefiksem określającym ich rodzaj (prd_, ord_, shp_). Traktuj je jako nieprzejrzyste.
Czas w formacie ISO 8601 w UTC. Kraje to dwuliterowe kody ISO.
Każda odpowiedź zawiera nagłówek X-Request-Id, a każdy błąd ten sam identyfikator jako request_id. Podaj go, gdy do nas piszesz.

Kwoty, ID i daty

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

Paginacja

Listy zwracają wyniki od najnowszych jako data, has_more i cursor. Odsyłaj ten cursor po następną stronę, dopóki has_more ma wartość true. Cursor działa tylko z filtrami, z którymi go otrzymano.

limitinteger: Od 1 do 100. Domyślnie 25.
cursorstring: cursor poprzedniej strony. Pomiń dla pierwszej strony.

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

Limity zapytań

Limity są na konto, wspólne dla wszystkich jego kluczy, tokenów OAuth i połączenia MCP. Każda odpowiedź mówi, gdzie jesteś, w nagłówkach IETF RateLimit-Policy i RateLimit; odmowa to 429 rate-limited z Retry-After w sekundach.

Okno	Co się liczy
"create-links";q=30;w=60	Wywołania odczytujące ofertę z marketplace’u: utworzenie lub odświeżenie importu, wysłanie produktu. 30 na minutę, wspólnie z API linków i MCP.
"default";q=120;w=60	Wszystkie pozostałe wywołania. 120 na minutę.

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

Idempotencja

Wysyłaj Idempotency-Key (od 1 do 255 drukowalnych znaków ASCII; idealny jest UUID) przy każdym POST, a ponowienie po przekroczeniu czasu nie złoży drugiego zamówienia. Przez 24 godziny ten sam klucz, na tej samej trasie z tym samym body, zwraca pierwszą odpowiedź bajt w bajt, z Idempotent-Replayed: true, bez ponownego wykonania i bez liczenia do limitu.

Ten sam klucz z innym body lub trasą: 422 idempotency-key-reused.
Pierwsze żądanie wciąż trwa: 409 idempotency-key-in-progress, z Retry-After.
Odmowa z powodu limitu to nie odpowiedź: klucz pozostaje wolny, więc ponowienie po Retry-After wykona żądanie.

Zamówienia mają też twój własny external_id: drugie zamówienie z tym samym jest odrzucane z 409 duplicate-order, niezależnie od klucza, którym je wysłano.

Ponowione żądanie

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

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

Błędy

Błędy to problem JSON (RFC 9457): type to stały URL do rozgałęziania logiki, title go nazywa, detail wyjaśnia ten przypadek słowami, które możesz pokazać, a request_id pozwala znaleźć go w naszych logach. Body, które nie przejdzie walidacji, dodaje errors, każdy z JSON pointer do pola.

Status	Typ	Kiedy
400	bad-json	Body nie jest JSON-em.
400	bad-body	Brakuje pola lub jest błędne; wskazuje je errors[].
400	bad-idempotency-key	Idempotency-Key jest pusty, za długi albo zawiera niedrukowalne znaki ASCII.
401	unauthorized	Brak klucza lub tokenu albo jest błędny, wygasł lub został unieważniony.
403	insufficient-scope	Klucz nie ma zakresu, którego wymaga trasa.
404	not-found	Na tym koncie nie ma takiego obiektu. ID innego konta dają tę samą odpowiedź.
405	method-not-allowed	Trasa istnieje, ale nie z tą metodą; Allow wymienia te, które przyjmuje.
409	duplicate-order	Zamówienie z tym external_id już istnieje; wskazuje je order.
409	idempotency-key-in-progress	Pierwsze żądanie z tym kluczem wciąż trwa.
409	invalid-state	Obiekt nie może teraz tego zrobić, np. anulować wysłanego zamówienia.
415	unsupported-media-type	Body nie jest typu application/json.
422	idempotency-key-reused	Klucz został użyty do innego żądania.
422	unprocessable	Poprawny JSON, z którym nie możemy nic zrobić: nieodczytany link, wyprzedany wariant. detail mówi, co.
429	rate-limited	Za dużo wywołań w oknie. Odczekaj Retry-After sekund.
500	internal-error	Błąd po naszej stronie. Ponów z tym samym Idempotency-Key.
503	service-unavailable	Nie mogliśmy teraz sprawdzić klucza ani połączyć się ze sklepem. Ponów po Retry-After.

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