API katalogu2026-11Podgląd

Importy

Wklej link do oferty i dostań jej warianty oraz koszt sprzedaży każdego: towar, nasza opłata za przyjęcie 12,00 CNY za paczkę sprzedawcy do nas, ryczałtowy podatek 14%, potem linia wysyłkowa, opłata manipulacyjna 50,00 CNY za paczkę i podatek od nich, prowizję marketplace’u i cenę, która zachowuje twoją marżę.

Import jest darmowy i bez limitu produktów. Płacisz tylko za to, co zamawiasz.
Każda wartość dotyczy jednej sztuki, kupionej w osobnym zamówieniu i wysłanej w osobnej paczce: jednej sprzedaży w dropshippingu. Kilka sztuk w jednym zamówieniu lub paczce kosztuje mniej, niż tu widać.
Prowizje marketplace’u domyślnie przyjmują publiczną stawkę bazową każdego marketplace’u. Podaj własną, gdy twoja kategoria lub plan się różnią.

Endpointy

POST/v1/importsImport z linku
POST/v1/imports/{id}/analysisWyceń ponownie
GET/v1/imports/{id}Pobranie importu
GET/v1/importsLista importów
POST/v1/imports/{id}/saveZapisz jako produkt

Obiekt Import

Oferta w naszym odczycie i koszt jednej sprzedaży z dostawą pod drzwi kupującego: towar, nasza opłata za przyjęcie 12,00 CNY za paczkę sprzedawcy do nas, ryczałtowy podatek 14%, potem linia wysyłkowa, opłata manipulacyjna 50,00 CNY za paczkę i podatek od nich. W US$ to kwota, jaką obciążona zostanie karta w US$, z przewalutowaniem.

idstring: Zaczyna się od imp_.
statusstring: running (arkusz znalezisk jest jeszcze odczytywany), ready lub failed.
urlstring: Link, który wysłałeś.
marketplacestring: taobao, tmall, weidian lub 1688.
title, seller, images[]string: Tak, jak napisał je sprzedawca, najczęściej po chińsku.
read_atstring: Kiedy ostatnio odczytaliśmy ofertę z marketplace’u.
analysis.ship_to, lane, weight_g: Dane wejściowe, dla których wyceniono.
analysis.coveredboolean: False, gdy żadna opublikowana stawka nie obsługuje wysyłki do tego kraju na tej linii; wtedy żaden wariant nie ma kosztu z dostawą.
analysis.marketplace_feeobject: percent i fixed: ile marketplace zatrzymuje ze sprzedaży. default ma wartość true, gdy nic nie wysłałeś, a my użyliśmy publicznej stawki bazowej — to szacunek, nigdy twój rzeczywisty rachunek.
analysis.margin_reachableboolean: False, gdy prowizja i marża razem zabierają całą cenę: żadna cena nie może tego osiągnąć.
analysis.brand_hintobject|null: Słowa z nazwami marek lub o replikach w tytule, po angielsku lub chińsku. Wskazówka, nigdy werdykt: nie widzi logo na zdjęciu, a czysty wynik niczego nie dowodzi.
analysis.variants[].procurementobject: goods, intake_fee, tax i total zamówienia, które kupuje jedną sztukę.
analysis.variants[].seller_shippingobject|null: Wysyłka sprzedawcy do naszego magazynu. Żadna oferta jej nie podaje, więc ma wartość null: nieznana, a nie darmowa.
analysis.variants[].parcelobject|null: lane, shipping, handling_fee, tax i total paczki, w której jest wysyłany.
analysis.variants[].landedobject: Produkt i paczka razem: w CN¥, w US$, z opłatą za przewalutowanie wliczoną w kwotę w US$.
analysis.variants[].minimum_priceobject|null: Najniższa cena, która zachowuje twoją marżę po prowizji marketplace’u.
analysis.variants[].suggestedobject|null: Najniższa cena x.99 równa minimum lub wyższa, z prowizją, zyskiem i marżą, które zostawia.
productstring|null: Produkt, którym stał się po zapisaniu.

import

{
  "id": "imp_2c9d",
  "status": "ready",
  "url": "https://weidian.com/item.html?itemID=7750970856",
  "marketplace": "weidian",
  "title": "Heavyweight washed hoodie",
  "seller": "Ruoyi Studio",
  "images": [
    "https://media.ninjabuy.com/listings/weidian-7750970856/1.webp"
  ],
  "read_at": "2026-11-04T09:12:40Z",
  "analysis": {
    "ship_to": "US",
    "lane": "saver",
    "weight_g": 180,
    "covered": true,
    "marketplace": "ebay",
    "marketplace_fee": {
      "percent": "13.6",
      "fixed": { "amount": "0.40", "currency": "USD" },
      "default": true
    },
    "margin_percent": "30",
    "margin_reachable": true,
    "brand_hint": null,
    "variants": [
      {
        "sku": "5187209554",
        "label": "Black / M",
        "in_stock": true,
        "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" }
        },
        "seller_shipping": null,
        "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" }
        },
        "landed": {
          "cny": { "amount": "191.52", "currency": "CNY" },
          "usd": { "amount": "27.71", "currency": "USD" },
          "fx_fee": { "amount": "5.75", "currency": "CNY" }
        },
        "minimum_price": { "amount": "49.84", "currency": "USD" },
        "suggested": {
          "price": { "amount": "49.99", "currency": "USD" },
          "marketplace_fee": { "amount": "7.20", "currency": "USD" },
          "profit": { "amount": "15.08", "currency": "USD" },
          "margin_percent": "30.16"
        }
      },
      {
        "sku": "5187209555",
        "label": "Black / L",
        "in_stock": false,
        "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" }
        },
        "seller_shipping": null,
        "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" }
        },
        "landed": {
          "cny": { "amount": "191.52", "currency": "CNY" },
          "usd": { "amount": "27.71", "currency": "USD" },
          "fx_fee": { "amount": "5.75", "currency": "CNY" }
        },
        "minimum_price": { "amount": "49.84", "currency": "USD" },
        "suggested": {
          "price": { "amount": "49.99", "currency": "USD" },
          "marketplace_fee": { "amount": "7.20", "currency": "USD" },
          "profit": { "amount": "15.08", "currency": "USD" },
          "margin_percent": "30.16"
        }
      }
    ]
  },
  "product": null,
  "created_at": "2026-11-04T09:12:41Z"
}

Import z linku

POST/v1/imports

Odczytuje ofertę z Taobao, Tmall, Weidian lub 1688 (zadziała też krótki link albo link innego agenta zakupowego do niej) i w tym samym wywołaniu zwraca ją z analizą. Oferty odczytanej w ciągu ostatnich pięciu minut nie pobieramy ponownie.

Link do arkusza znalezisk (https://www.ninjabuy.com/spreadsheets/d/…) importuje każdy produkt z arkusza: 202 ze status: running, potem odpytuj import.

Zakresproducts:write

Body

urlstringwymagane: Link do produktu lub arkusz znalezisk.
ship_tostring: Dwuliterowy kod kraju, dla którego wyceniamy paczkę. Domyślnie US.
lanestring: saver lub fast. Domyślnie saver.
weight_gintegerwymagane: Waga jednej sztuki z opakowaniem, w gramach. Oferty nie podają wagi, więc paczka jest wyceniana według twojej.
marketplacestring: Gdzie to sprzedajesz: ebay, shopify, amazon lub tiktok. Domyślnie shopify.
marketplace_feeobject: Opcjonalne. percent i fixed (US$) zamiast stawki bazowej marketplace’u, dla twojej kategorii lub planu.
margin_percentstring: Marża do wyceny, liczona od ceny sprzedaży. Domyślnie 30.

Błędy

Status	Typ	Kiedy
400	bad-body	Brakuje weight_g albo pole jest poza zakresem.
422	unprocessable	Link, którego nie umiemy odczytać, albo oferta już nie istnieje.
429	rate-limited	Okno zapytań do marketplace’u wyczerpane; zobacz Limity zapytań.

curl -X POST "https://www.ninjabuy.com/api/v1/imports" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://weidian.com/item.html?itemID=7750970856",
    "ship_to": "US",
    "weight_g": 180,
    "marketplace": "ebay",
    "margin_percent": "30"
  }'

Response 201

HTTP/2 201 Created

{
  "id": "imp_2c9d",
  "status": "ready",
  "url": "https://weidian.com/item.html?itemID=7750970856",
  "marketplace": "weidian",
  "title": "Heavyweight washed hoodie",
  "seller": "Ruoyi Studio",
  "images": [
    "https://media.ninjabuy.com/listings/weidian-7750970856/1.webp"
  ],
  "read_at": "2026-11-04T09:12:40Z",
  "analysis": {
    "ship_to": "US",
    "lane": "saver",
    "weight_g": 180,
    "covered": true,
    "marketplace": "ebay",
    "marketplace_fee": {
      "percent": "13.6",
      "fixed": { "amount": "0.40", "currency": "USD" },
      "default": true
    },
    "margin_percent": "30",
    "margin_reachable": true,
    "brand_hint": null,
    "variants": [
      {
        "sku": "5187209554",
        "label": "Black / M",
        "in_stock": true,
        "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" }
        },
        "seller_shipping": null,
        "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" }
        },
        "landed": {
          "cny": { "amount": "191.52", "currency": "CNY" },
          "usd": { "amount": "27.71", "currency": "USD" },
          "fx_fee": { "amount": "5.75", "currency": "CNY" }
        },
        "minimum_price": { "amount": "49.84", "currency": "USD" },
        "suggested": {
          "price": { "amount": "49.99", "currency": "USD" },
          "marketplace_fee": { "amount": "7.20", "currency": "USD" },
          "profit": { "amount": "15.08", "currency": "USD" },
          "margin_percent": "30.16"
        }
      },
      {
        "sku": "5187209555",
        "label": "Black / L",
        "in_stock": false,
        "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" }
        },
        "seller_shipping": null,
        "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" }
        },
        "landed": {
          "cny": { "amount": "191.52", "currency": "CNY" },
          "usd": { "amount": "27.71", "currency": "USD" },
          "fx_fee": { "amount": "5.75", "currency": "CNY" }
        },
        "minimum_price": { "amount": "49.84", "currency": "USD" },
        "suggested": {
          "price": { "amount": "49.99", "currency": "USD" },
          "marketplace_fee": { "amount": "7.20", "currency": "USD" },
          "profit": { "amount": "15.08", "currency": "USD" },
          "margin_percent": "30.16"
        }
      }
    ]
  },
  "product": null,
  "created_at": "2026-11-04T09:12:41Z"
}

Wyceń ponownie

POST/v1/imports/{id}/analysis

Ta sama oferta dla innego kraju, linii, wagi, marketplace’u lub marży. Wyceniana z tego, co już odczytaliśmy, więc nie zużywa zapytania do marketplace’u. Zwraca nową analizę i zapisuje ją w imporcie.

Zakresproducts:write

Parametry ścieżki

idstringwymagane: ID importu.

Body

ship_tostring: Dwuliterowy kod kraju, dla którego wyceniamy paczkę. Domyślnie US.
lanestring: saver lub fast. Domyślnie saver.
weight_gintegerwymagane: Waga jednej sztuki z opakowaniem, w gramach. Oferty nie podają wagi, więc paczka jest wyceniana według twojej.
marketplacestring: Gdzie to sprzedajesz: ebay, shopify, amazon lub tiktok. Domyślnie shopify.
marketplace_feeobject: Opcjonalne. percent i fixed (US$) zamiast stawki bazowej marketplace’u, dla twojej kategorii lub planu.
margin_percentstring: Marża do wyceny, liczona od ceny sprzedaży. Domyślnie 30.

Błędy

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

curl -X POST "https://www.ninjabuy.com/api/v1/imports/imp_2c9d/analysis" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ship_to": "GB",
    "lane": "fast",
    "weight_g": 180,
    "marketplace": "tiktok",
    "margin_percent": "35"
  }'

Response 200

HTTP/2 200 OK

{
  "ship_to": "GB",
  "lane": "fast",
  "weight_g": 180,
  "covered": true,
  "marketplace": "tiktok",
  "marketplace_fee": {
    "percent": "6",
    "fixed": { "amount": "0.00", "currency": "USD" },
    "default": true
  },
  "margin_percent": "35",
  "margin_reachable": true,
  "brand_hint": null,
  "variants": [
    {
      "sku": "5187209554",
      "label": "Black / M",
      "in_stock": true,
      "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" }
      },
      "seller_shipping": null,
      "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" }
      },
      "landed": {
        "cny": { "amount": "191.52", "currency": "CNY" },
        "usd": { "amount": "27.71", "currency": "USD" },
        "fx_fee": { "amount": "5.75", "currency": "CNY" }
      },
      "minimum_price": { "amount": "49.84", "currency": "USD" },
      "suggested": {
        "price": { "amount": "49.99", "currency": "USD" },
        "marketplace_fee": { "amount": "7.20", "currency": "USD" },
        "profit": { "amount": "15.08", "currency": "USD" },
        "margin_percent": "30.16"
      }
    },
    {
      "sku": "5187209555",
      "label": "Black / L",
      "in_stock": false,
      "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" }
      },
      "seller_shipping": null,
      "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" }
      },
      "landed": {
        "cny": { "amount": "191.52", "currency": "CNY" },
        "usd": { "amount": "27.71", "currency": "USD" },
        "fx_fee": { "amount": "5.75", "currency": "CNY" }
      },
      "minimum_price": { "amount": "49.84", "currency": "USD" },
      "suggested": {
        "price": { "amount": "49.99", "currency": "USD" },
        "marketplace_fee": { "amount": "7.20", "currency": "USD" },
        "profit": { "amount": "15.08", "currency": "USD" },
        "margin_percent": "30.16"
      }
    }
  ]
}

Pobranie importu

GET/v1/imports/{id}

Odczytaj import ponownie albo odpytuj arkusz znalezisk, dopóki trwa przetwarzanie.

Zakresproducts:read

Parametry ścieżki

idstringwymagane: ID importu.

Błędy

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

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

Response 200

HTTP/2 200 OK

{
  "id": "imp_6t1b",
  "status": "running",
  "url": "https://www.ninjabuy.com/spreadsheets/d/1aBcD3fGh",
  "progress": { "done": 41, "total": 120 },
  "poll_after_seconds": 10
}

Lista importów

GET/v1/imports

Od najnowszych. Importy, których nie zapisałeś, zostają tu, żebyś mógł do nich wrócić.

Zakresproducts:read

Parametry zapytania

statusstring: Opcjonalne. running, ready lub failed.
savedboolean: Opcjonalne. true dla tych, które stały się produktami.
limit, cursor: Pagination

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

Response 200

HTTP/2 200 OK

{
  "data": [
    {
      "id": "imp_2c9d",
      "status": "ready",
      "title": "Heavyweight washed hoodie",
      "product": null
    },
    {
      "id": "imp_2c7a",
      "status": "ready",
      "title": "Canvas tote, 3 colours",
      "product": null
    }
  ],
  "has_more": true,
  "cursor": "c_2c7a"
}

Zapisz jako produkt

POST/v1/imports/{id}/save

Zachowuje wybrane warianty jako produkt, po ustawionych lub sugerowanych cenach. Dodaj push_to: shopify, aby wystawić go w sklepie tym samym wywołaniem (Wyślij do Shopify).

Zakresproducts:write

Parametry ścieżki

idstringwymagane: ID importu.

Body

variants[]array: Opcjonalne. sku i price każdego zachowywanego wariantu. Jeśli pominięte — każdy dostępny wariant po sugerowanej cenie.
titlestring: Opcjonalne. Twój własny tytuł; tytuł sprzedawcy jest najczęściej po chińsku.
push_tostring: Opcjonalne. shopify.

Błędy

Status	Typ	Kiedy
409	invalid-state	Już zapisane; wskazuje je product.
422	unprocessable	Każdy zachowany wariant jest wyprzedany.

curl -X POST "https://www.ninjabuy.com/api/v1/imports/imp_2c9d/save" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Heavyweight Washed Hoodie",
    "variants": [
      {
        "sku": "5187209554",
        "price": { "amount": "49.99", "currency": "USD" }
      }
    ],
    "push_to": "shopify"
  }'

Response 201

HTTP/2 201 Created

{
  "import": "imp_2c9d",
  "product": "prd_8f2k",
  "status": "draft",
  "channels": [{ "channel": "shopify", "status": "draft" }]
}