API zamówień2026-11Podgląd

Zamówienia

Twoja sprzedaż, którą kupujemy od sprzedawcy, sprawdzamy i fotografujemy w naszym magazynie, pakujemy w twoje pudełko i wysyłamy twojemu klientowi.

Śledź zamówienie przez webhooki zamiast odpytywania: zdarzenia zamówienia wywołują się na każdym etapie. Sama paczka to zlecenie realizacji, a potem przesyłka.

Endpointy

POST/v1/ordersUtworzenie zamówienia
GET/v1/ordersLista zamówień
GET/v1/orders/{id}Pobranie zamówienia
POST/v1/orders/{id}/cancelAnulowanie zamówienia

Obiekt Order

idstring: Zaczyna się od ord_.
external_idstring: Numer zamówienia twojego sklepu. Unikalny na twoim koncie.
sourcestring: api lub shopify dla zamówień wysłanych przez twój sklep Shopify.
statusstring: Status pozycji, która jest najmniej zaawansowana; zobacz Statusy poniżej.
payment_statusstring: awaiting_payment, paid, partially_refunded lub refunded.
lanestring: saver lub fast.
lines[]array: Wariant, ilość, sztuki kupowane na produkt, status, zdjęcia z magazynu po kontroli oraz reason przy odrzuceniu.
ship_toobject: Imię i nazwisko, adres, telefon i e-mail twojego klienta.
packagingstring|null: Twoje markowe pudełko lub koperta; domyślne przy null.
chargesobject: Ile to kosztuje, w CN¥: zakup u sprzedawcy (towar, opłata za przyjęcie, podatek) i paczka (wysyłka, opłata manipulacyjna, podatek). Paczka to szacunek na podstawie twoich wag, dopóki jej nie zważymy.
amount_duemoney|null: Co twoje saldo musi jeszcze pokryć, gdy status to awaiting_payment.
fulfillment_orders[]array: Paczki, w których wychodzi.

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

Wyślij nam jedno z zamówień swojego sklepu. Każda pozycja to zapisany przez ciebie wariant albo link do oferty i SKU, które kupujemy bez zmian. Zamówienie jest od razu opłacane z salda; takie, którego saldo nie pokrywa, i tak zostaje utworzone, jako awaiting_payment z amount_due, i rusza samo po doładowaniu.

Zamówienia z twojego sklepu Shopify docierają do nas bez tego wywołania. Używaj go dla WooCommerce, Wix, własnej strony albo czegokolwiek innego, co sprzedaje.

Zakresorders:write

Body

external_idstringwymagane: Numer twojego zamówienia. Drugie zamówienie z tym numerem zostanie odrzucone.
lines[]arraywymagane: variant i quantity albo url, sku i quantity. units (opcjonalne) kupuje tyle sztuk na produkt, dla zestawów.
ship_toobjectwymagane: name, line1, line2, city, region, postal_code, country (dwie litery), phone, email.
lanestring: saver lub fast. Domyślnie saver.
packagingstring: Opcjonalne. ID opakowania; domyślne, jeśli pominięte.
notestring: Opcjonalne. Dla zespołu magazynu, do 500 znaków.

Błędy

Status	Typ	Kiedy
400	bad-body	Brakuje pola lub jest błędne; wskazuje je errors[].
409	duplicate-order	external_id jest już zamówieniem; wskazuje je order.
422	unprocessable	Wariant pozycji jest wyprzedany albo nie da się odczytać jej linku.
422	not-shippable	Żadna opublikowana stawka nie obsługuje ship_to.country na tej linii.

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

Lista zamówień

GET/v1/orders

Od najnowszych.

Zakresorders:read

Parametry zapytania

statusstring: Opcjonalne. Jeden ze statusów poniżej.
sourcestring: Opcjonalne. api lub shopify.
external_idstring: Opcjonalne. Znajdź po własnym numerze zamówienia.
created_sincestring: Opcjonalne. Czas.
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
}

Pobranie zamówienia

GET/v1/orders/{id}

Status każdej pozycji, jej zdjęcia z magazynu po kontroli, koszt i paczki.

Zakresorders:read

Parametry ścieżki

idstringwymagane: ID zamówienia.

Błędy

Status	Typ	Kiedy
404	not-found	Na tym koncie nie ma takiego zamówienia.

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

Anulowanie zamówienia

POST/v1/orders/{id}/cancel

Przed zakupem całe zamówienie wraca na saldo. Po zakupie zwracamy pozycje, które sprzedawca przyjmie z powrotem, a reszta zostaje na twojej półce jako zapas magazynowy. Wysłanego zamówienia nie można anulować.

Zakresorders:write

Parametry ścieżki

idstringwymagane: ID zamówienia.

Body

reasonstring: Opcjonalne. Przechowywane w zamówieniu.

Błędy

Status	Typ	Kiedy
404	not-found	Na tym koncie nie ma takiego zamówienia.
409	invalid-state	Zostało wysłane.

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

Statusy

Każda pozycja ma własny status; status zamówienia to status pozycji, która jest najmniej zaawansowana. Po kolei:

Status	Znaczenie
awaiting_payment	Saldo tego nie pokryło. Doładuj, a ruszy samo.
buying	Opłacone; kupujemy je od sprzedawcy.
with_seller	Kupione; sprzedawca jeszcze nie wysłał tego do naszego magazynu.
checked	W naszym magazynie, sprawdzone i sfotografowane, czeka na zapakowanie.
shipped	W drodze, z numerem śledzenia.
delivered	Przewoźnik podaje, że dotarło.
rejected	Nie mogliśmy tego kupić (wyprzedane, link nie działa); reason podaje powód, a kwota jest zwracana.
cancelled	Anulowałeś je.

Pieniądze

W przykładach zakup jednej sztuki kosztuje 57,00 CNY, a jej wysyłka 134,52 CNY, pobierane z salda. Czym jest każda pozycja: Opłaty.

Obiekt Order

Utworzenie zamówienia

Body

Błędy

Lista zamówień

Parametry zapytania

Pobranie zamówienia

Parametry ścieżki

Błędy

Anulowanie zamówienia

Parametry ścieżki

Body

Błędy

Statusy

Pieniądze