API Catalogo2026-11Anteprima

Prodotti

Un’inserzione salvata da un’importazione, con il tuo titolo, i tuoi prezzi e i negozi in cui è in vendita.

È in Shopify che si inviano i prodotti. Anche gli ordini dei marketplace su cui vende il tuo negozio Shopify arrivano a noi tramite Shopify: Collega un negozio.
Un negozio WooCommerce o Wix tiene i propri prodotti e invia i suoi ordini con Crea un ordine.

Endpoint

GET/v1/productsElenca i prodotti
GET/v1/products/{id}Recupera un prodotto
PATCH/v1/products/{id}Aggiorna un prodotto
POST/v1/products/{id}/pushPush to Shopify
DELETE/v1/products/{id}Elimina un prodotto

L’oggetto Product

idstring: Inizia con prd_.
titlestring: Il tuo titolo. Quello del venditore resta sull’importazione.
statusstring: active, o paused (da te, o da una regola di sincronizzazione quando un costo è salito troppo o il venditore ha esaurito).
sourceobject: Marketplace, link dell’inserzione e venditore in Cina.
options[]array: Nomi delle opzioni, al massimo tre, come li mostra il tuo negozio.
price_range, cost_rangeobject: I tuoi prezzi e quelli del venditore, per ogni variante.
channels[]array: Dove è pubblicato: il negozio, il suo ID prodotto e il suo stato lì.
syncobject: La regola di sincronizzazione che segue e quando abbiamo letto l’inserzione l’ultima volta.
importstring: L’importazione da cui è stato salvato.

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

Elenca i prodotti

GET/v1/products

I tuoi prodotti, dal più recente.

Scopeproducts:read

Parametri di query

statusstring: Facoltativo. active o paused.
channelstring: Facoltativo. shopify, per quelli pubblicati lì.
changed_sincestring: Facoltativo. Una data: solo i prodotti il cui costo o stock è cambiato da allora.
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"
}

Recupera un prodotto

GET/v1/products/{id}

Un prodotto con la sua fonte, i canali e lo stato di sincronizzazione. Le sue varianti hanno una route propria.

Scopeproducts:read

Parametri di percorso

idstringobbligatorio: L’ID del prodotto.

Errori

Stato	Tipo	Quando
404	not-found	Nessun prodotto simile su questo account.

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

Aggiorna un prodotto

PATCH/v1/products/{id}

Cambia titolo o descrizione, o mettilo in pausa e riprendilo. Invia solo ciò che cambia. I prezzi sono per variante (Variants); un prodotto inviato porta la modifica al tuo negozio al prossimo invio.

Scopeproducts:write

Parametri di percorso

idstringobbligatorio: L’ID del prodotto.

Corpo

titlestring: Facoltativo.
descriptionstring: Facoltativo. HTML mostrato dal tuo negozio.
statusstring: Facoltativo. active o paused. paused porta lo stock a 0 sui tuoi canali.
sync_rulestring: Facoltativo. Un ID di regola di sincronizzazione; la regola predefinita se null.

Errori

Stato	Tipo	Quando
404	not-found	Nessun prodotto simile su questo account.

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

Pubblica il prodotto sul negozio Shopify collegato: un prodotto Shopify, una variante per ogni SKU tenuto, le sue foto, ogni variante a stock nella sede Fulfilled by NinjaBuy, così i suoi ordini arrivano a noi.

Il primo invio lo crea come bozza: titolo e foto vengono da un marketplace cinese, quindi leggili prima dei tuoi acquirenti, poi pubblica in Shopify.
Inviare di nuovo aggiorna lo stesso prodotto Shopify: prezzi e stock vengono reimpostati, le varianti scartate vengono rimosse. Stato, titolo, descrizione e foto restano come li hai lasciati in Shopify, a meno che tu non ne invii di nuovi.
Lo stock è il conteggio del venditore, con un tetto di 100: acquistiamo su richiesta, quindi è il numero di ordini che Shopify accetta prima di mostrare esaurito.
Il tuo negozio deve vendere in US$, perché i prezzi sono in quella valuta. Le varianti esaurite vengono saltate e indicate in skipped[].

Scopeproducts:write

Parametri di percorso

idstringobbligatorio: L’ID del prodotto.

Corpo

shopstring: Quale negozio collegato, come acme-goods.myshopify.com. Necessario solo se ne hai collegati diversi.
title, descriptionstring: Facoltativo. Inviati a Shopify solo se li invii.

Errori

Stato	Tipo	Quando
409	no-linked-store	Nessun negozio Shopify è collegato a questo account, o ne sono collegati diversi e manca `shop`.
409	store-not-ready	L’accesso del negozio è scaduto, o la nostra sede non è ancora configurata: apri una volta l’app NinjaBuy in Shopify.
422	store-currency	Il negozio non vende in US$.
422	too-many-options	L’inserzione ha più di tre opzioni; Shopify ne accetta tre.
422	unprocessable	Tutte le varianti sono esaurite, o Shopify ha rifiutato un campo; detail ne riporta il messaggio.

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

Elimina un prodotto

DELETE/v1/products/{id}

Interrompe la sincronizzazione e porta il suo stock a 0 sui tuoi canali; il prodotto Shopify resta, da archiviare tu. Gli ordini già effettuati partono comunque.

Scopeproducts:write

Parametri di percorso

idstringobbligatorio: L’ID del prodotto.

Errori

Stato	Tipo	Quando
404	not-found	Nessun prodotto simile su questo account.

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 }

L’oggetto Product

Elenca i prodotti

Parametri di query

Recupera un prodotto

Parametri di percorso

Errori

Aggiorna un prodotto

Parametri di percorso

Corpo

Errori

Push to Shopify

Parametri di percorso

Corpo

Errori

Elimina un prodotto

Parametri di percorso

Errori