API katalogu2026-11Podgląd

Produkty

Oferta zapisana z importu, z twoim tytułem, cenami i sklepami, w których się sprzedaje.

Produkty są wysyłane do Shopify. Zamówienia z marketplace’ów, na których sprzedaje twój sklep Shopify, też docierają do nas przez Shopify: Połącz sklep.
Sklep WooCommerce lub Wix zachowuje własne produkty i wysyła zamówienia przez Utworzenie zamówienia.

Endpointy

GET/v1/productsLista produktów
GET/v1/products/{id}Pobranie produktu
PATCH/v1/products/{id}Aktualizacja produktu
POST/v1/products/{id}/pushWyślij do Shopify
DELETE/v1/products/{id}Usunięcie produktu

Obiekt Product

idstring: Zaczyna się od prd_.
titlestring: Twój tytuł. Tytuł sprzedawcy zostaje w imporcie.
statusstring: active lub paused (przez ciebie albo przez regułę synchronizacji, gdy koszt wzrósł za bardzo lub sprzedawcy zabrakło towaru).
sourceobject: Marketplace, link do oferty i sprzedawca w Chinach.
options[]array: Nazwy opcji, najwyżej trzy, tak jak pokazuje je twój sklep.
price_range, cost_rangeobject: Twoje ceny i ceny sprzedawcy, dla wszystkich wariantów.
channels[]array: Gdzie jest wystawiony: sklep, jego własne ID produktu i status tam.
syncobject: Reguła synchronizacji, którą stosuje, i kiedy ostatnio odczytaliśmy ofertę.
importstring: Import, z którego go zapisano.

product

{
  "id": "prd_8f2k",
  "title": "Heavyweight Washed Hoodie",
  "status": "active",
  "source": {
    "marketplace": "weidian",
    "url": "https://weidian.com/item.html?itemID=7750970856",
    "seller": "Ruoyi Studio"
  },
  "options": ["Color", "Size"],
  "variants_count": 6,
  "price_range": {
    "min": { "amount": "49.99", "currency": "USD" },
    "max": { "amount": "54.99", "currency": "USD" }
  },
  "cost_range": {
    "min": { "amount": "38.00", "currency": "CNY" },
    "max": { "amount": "42.00", "currency": "CNY" }
  },
  "channels": [
    {
      "channel": "shopify",
      "shop": "acme-goods.myshopify.com",
      "external_id": "gid://shopify/Product/8812042",
      "status": "draft",
      "pushed_at": "2026-11-04T09:20:03Z"
    }
  ],
  "sync": {
    "rule": "rule_default",
    "last_checked_at": "2026-11-04T09:12:40Z"
  },
  "import": "imp_2c9d",
  "created_at": "2026-11-04T09:20:01Z",
  "updated_at": "2026-11-04T09:20:03Z"
}

Lista produktów

GET/v1/products

Twoje produkty, od najnowszych.

Zakresproducts:read

Parametry zapytania

statusstring: Opcjonalne. active lub paused.
channelstring: Opcjonalne. shopify — dla wystawionych tam.
changed_sincestring: Opcjonalne. Czas: tylko produkty, których koszt lub stan zmienił się od tego czasu.
limit, cursor: Pagination

curl "https://www.ninjabuy.com/api/v1/products?status=active&limit=2" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{
  "data": [
    {
      "id": "prd_8f2k",
      "title": "Heavyweight Washed Hoodie",
      "status": "active",
      "variants_count": 6
    },
    {
      "id": "prd_1x0a",
      "title": "Canvas Tote",
      "status": "active",
      "variants_count": 3
    }
  ],
  "has_more": true,
  "cursor": "c_1x0a"
}

Pobranie produktu

GET/v1/products/{id}

Jeden produkt ze źródłem, kanałami i stanem synchronizacji. Jego warianty mają własną trasę.

Zakresproducts:read

Parametry ścieżki

idstringwymagane: ID produktu.

Błędy

Status	Typ	Kiedy
404	not-found	Na tym koncie nie ma takiego produktu.

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

Response 200

HTTP/2 200 OK

{
  "id": "prd_8f2k",
  "title": "Heavyweight Washed Hoodie",
  "status": "active",
  "source": {
    "marketplace": "weidian",
    "url": "https://weidian.com/item.html?itemID=7750970856",
    "seller": "Ruoyi Studio"
  },
  "options": ["Color", "Size"],
  "variants_count": 6,
  "price_range": {
    "min": { "amount": "49.99", "currency": "USD" },
    "max": { "amount": "54.99", "currency": "USD" }
  },
  "cost_range": {
    "min": { "amount": "38.00", "currency": "CNY" },
    "max": { "amount": "42.00", "currency": "CNY" }
  },
  "channels": [
    {
      "channel": "shopify",
      "shop": "acme-goods.myshopify.com",
      "external_id": "gid://shopify/Product/8812042",
      "status": "draft",
      "pushed_at": "2026-11-04T09:20:03Z"
    }
  ],
  "sync": {
    "rule": "rule_default",
    "last_checked_at": "2026-11-04T09:12:40Z"
  },
  "import": "imp_2c9d",
  "created_at": "2026-11-04T09:20:01Z",
  "updated_at": "2026-11-04T09:20:03Z"
}

Aktualizacja produktu

PATCH/v1/products/{id}

Zmień tytuł lub opis albo wstrzymaj i wznów. Wysyłaj tylko to, co się zmienia. Ceny są per wariant (Warianty); wysłany produkt przenosi zmianę do sklepu przy kolejnym wysłaniu.

Zakresproducts:write

Parametry ścieżki

idstringwymagane: ID produktu.

Body

titlestring: Opcjonalne.
descriptionstring: Opcjonalne. HTML, który pokazuje twój sklep.
statusstring: Opcjonalne. active lub paused. Paused ustawia stan na 0 w twoich kanałach.
sync_rulestring: Opcjonalne. ID reguły synchronizacji; reguła domyślna przy null.

Błędy

Status	Typ	Kiedy
404	not-found	Na tym koncie nie ma takiego produktu.

curl -X PATCH "https://www.ninjabuy.com/api/v1/products/prd_8f2k" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paused" }'

Response 200

HTTP/2 200 OK

{
  "id": "prd_8f2k",
  "title": "Heavyweight Washed Hoodie",
  "status": "paused",
  "source": {
    "marketplace": "weidian",
    "url": "https://weidian.com/item.html?itemID=7750970856",
    "seller": "Ruoyi Studio"
  },
  "options": ["Color", "Size"],
  "variants_count": 6,
  "price_range": {
    "min": { "amount": "49.99", "currency": "USD" },
    "max": { "amount": "54.99", "currency": "USD" }
  },
  "cost_range": {
    "min": { "amount": "38.00", "currency": "CNY" },
    "max": { "amount": "42.00", "currency": "CNY" }
  },
  "channels": [
    {
      "channel": "shopify",
      "shop": "acme-goods.myshopify.com",
      "external_id": "gid://shopify/Product/8812042",
      "status": "draft",
      "pushed_at": "2026-11-04T09:20:03Z"
    }
  ],
  "sync": {
    "rule": "rule_default",
    "last_checked_at": "2026-11-04T09:12:40Z"
  },
  "import": "imp_2c9d",
  "created_at": "2026-11-04T09:20:01Z",
  "updated_at": "2026-11-04T09:20:03Z"
}

Wystawia produkt w połączonym sklepie Shopify: jeden produkt Shopify, wariant na każdy zachowany SKU, jego zdjęcia, każdy wariant ze stanem w lokalizacji Fulfilled by NinjaBuy, więc zamówienia na niego trafiają do nas.

Pierwsze wysłanie tworzy go jako szkic: tytuł i zdjęcia pochodzą z chińskiego marketplace’u, więc przeczytaj je, zanim zrobią to kupujący, potem opublikuj w Shopify.
Ponowne wysłanie aktualizuje ten sam produkt Shopify: ceny i stany są ustawiane od nowa, usunięte przez ciebie warianty są kasowane. Status, tytuł, opis i zdjęcia zostają takie, jak zostawiłeś je w Shopify, chyba że wyślesz nowe.
Stan to liczba u sprzedawcy, maksymalnie 100: kupujemy na żądanie, więc to tyle zamówień, ile Shopify przyjmie, zanim pokaże wyprzedanie.
Twój sklep musi sprzedawać w US$, bo w tej walucie są ceny. Wyprzedane warianty są pomijane i wymieniane w skipped[].

Zakresproducts:write

Parametry ścieżki

idstringwymagane: ID produktu.

Body

shopstring: Który połączony sklep, np. acme-goods.myshopify.com. Wymagane tylko, gdy połączyłeś kilka.
title, descriptionstring: Opcjonalne. Wysyłane do Shopify tylko wtedy, gdy je podasz.

Błędy

Status	Typ	Kiedy
409	no-linked-store	Z tym kontem nie jest połączony żaden sklep Shopify albo jest ich kilka i brakuje `shop`.
409	store-not-ready	Dostęp sklepu wygasł albo nasza lokalizacja nie jest jeszcze skonfigurowana: otwórz raz aplikację NinjaBuy w Shopify.
422	store-currency	Sklep nie sprzedaje w US$.
422	too-many-options	Oferta ma więcej niż trzy opcje; Shopify przyjmuje trzy.
422	unprocessable	Każdy wariant jest wyprzedany albo Shopify odrzucił pole; detail przekazuje jego komunikat.

curl -X POST "https://www.ninjabuy.com/api/v1/products/prd_8f2k/push" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "shop": "acme-goods.myshopify.com" }'

Response 200

HTTP/2 200 OK

{
  "channel": "shopify",
  "shop": "acme-goods.myshopify.com",
  "external_id": "gid://shopify/Product/8812042",
  "status": "draft",
  "created": true,
  "variants": 5,
  "skipped": [{ "sku": "5187209555", "reason": "sold_out" }],
  "admin_url": "https://admin.shopify.com/store/acme-goods/products/8812042"
}

Usunięcie produktu

DELETE/v1/products/{id}

Przestaje go synchronizować i ustawia stan na 0 w twoich kanałach; produkt w Shopify zostaje, żebyś go zarchiwizował. Już złożone zamówienia nadal zostaną wysłane.

Zakresproducts:write

Parametry ścieżki

idstringwymagane: ID produktu.

Błędy

Status	Typ	Kiedy
404	not-found	Na tym koncie nie ma takiego produktu.

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

Response 200

HTTP/2 200 OK

{ "id": "prd_8f2k", "deleted": true }

Obiekt Product

Lista produktów

Parametry zapytania

Pobranie produktu

Parametry ścieżki

Błędy

Aktualizacja produktu

Parametry ścieżki

Body

Błędy

Wyślij do Shopify

Parametry ścieżki

Body

Błędy

Usunięcie produktu

Parametry ścieżki

Błędy