API Catalogo2026-11Anteprima

Importazioni

Incolla il link di un’inserzione e ottieni le sue varianti e quanto ti costa venderle: la merce, la nostra commissione di ricezione di 12,00 CN¥ per il pacco del venditore fino a noi, la tassa forfettaria del 14%, poi la linea di spedizione, la commissione di gestione di 50,00 CN¥ per pacco e la relativa tassa, la commissione del marketplace e il prezzo che mantiene il tuo margine.

Importare è gratis, senza limite di prodotti. Paghi solo ciò che ordini.
Ogni cifra si riferisce a un’unità, acquistata nel suo ordine e spedita nel suo pacco: una vendita in dropshipping. Più unità in un ordine o in un pacco costano meno di quanto indicato.
Le commissioni del marketplace usano di default l’aliquota pubblica principale di ciascun marketplace. Invia la tua se la tua categoria o il tuo piano sono diversi.

Endpoint

POST/v1/importsImporta da un link
POST/v1/imports/{id}/analysisRicalcola il prezzo
GET/v1/imports/{id}Recupera un’importazione
GET/v1/importsElenca le importazioni
POST/v1/imports/{id}/saveSalva come prodotto

L’oggetto Import

Un’inserzione come la leggiamo, con quanto costa una vendita consegnata a casa dell’acquirente: la merce, la nostra commissione di ricezione di 12,00 CN¥ per il pacco del venditore fino a noi, la tassa forfettaria del 14%, poi la linea di spedizione, la commissione di gestione di 50,00 CN¥ per pacco e la relativa tassa. In US$ è l’importo addebitato su una carta in US$, conversione inclusa.

idstring: Inizia con imp_.
statusstring: running (un foglio di scoperte ancora in lettura), ready o failed.
urlstring: Il link che hai inviato.
marketplacestring: taobao, tmall, weidian o 1688.
title, seller, images[]string: Come li ha scritti il venditore, il più delle volte in cinese.
read_atstring: Quando abbiamo letto l’ultima volta l’inserzione dal marketplace.
analysis.ship_to, lane, weight_g: I parametri con cui è stato calcolato.
analysis.coveredboolean: False quando nessuna tariffa pubblicata spedisce verso quel paese su quella linea; nessuna variante ha allora un costo finale.
analysis.marketplace_feeobject: percent e fixed: quanto trattiene il marketplace su una vendita. default è true quando non ne hai inviato nessuno e abbiamo usato l’aliquota pubblica principale: una stima, mai il tuo addebito reale.
analysis.margin_reachableboolean: False quando commissione e margine insieme prendono tutto il prezzo: nessun prezzo può raggiungerlo.
analysis.brand_hintobject|null: Parole di marchio o di replica trovate nel titolo, in inglese o in cinese. Un indizio, mai un verdetto: non vede un logo in una foto e un risultato pulito non prova nulla.
analysis.variants[].procurementobject: goods, intake_fee, tax e total dell’ordine che acquista un’unità.
analysis.variants[].seller_shippingobject|null: La spedizione del venditore al nostro magazzino. Nessuna inserzione la indica, quindi è null: sconosciuta, non gratuita.
analysis.variants[].parcelobject|null: lane, shipping, handling_fee, tax e total del pacco che lo spedisce.
analysis.variants[].landedobject: Articolo e pacco insieme: in CN¥, in US$, con la commissione di conversione inclusa negli US$.
analysis.variants[].minimum_priceobject|null: Il prezzo più basso che mantiene il tuo margine dopo la commissione del marketplace.
analysis.variants[].suggestedobject|null: Il prezzo x.99 più basso pari o superiore al minimo, con commissione, profitto e margine che lascia.
productstring|null: Il prodotto che è diventato una volta salvato.

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

Importa da un link

POST/v1/imports

Legge un’inserzione Taobao, Tmall, Weidian o 1688 (funziona anche un link breve, o il link di un altro agente di acquisto) e la restituisce analizzata, nella stessa chiamata. Un’inserzione letta negli ultimi cinque minuti non viene recuperata di nuovo.

Il link di un foglio di scoperte (https://www.ninjabuy.com/spreadsheets/d/…) importa tutti i suoi prodotti: 202 con status: running, poi interroga l’importazione.

Scopeproducts:write

Corpo

urlstringobbligatorio: Un link di prodotto, o un foglio di scoperte.
ship_tostring: Paese a due lettere per cui calcolare il pacco. US se omesso.
lanestring: saver o fast. saver se omesso.
weight_gintegerobbligatorio: Il peso imballato di un’unità, in grammi. Le inserzioni non indicano il peso, quindi il pacco si calcola sul tuo.
marketplacestring: Dove lo vendi: ebay, shopify, amazon o tiktok. shopify se omesso.
marketplace_feeobject: Facoltativo. percent e fixed (US$) da usare al posto dell’aliquota principale del marketplace, per la tua categoria o il tuo piano.
margin_percentstring: Il margine su cui calcolare il prezzo, sul prezzo di vendita. 30 se omesso.

Errori

Stato	Tipo	Quando
400	bad-body	weight_g manca, o un campo è fuori intervallo.
422	unprocessable	Non è un link che riusciamo a leggere, o l’inserzione non c’è più.
429	rate-limited	La finestra del marketplace è esaurita; vedi Limiti di frequenza.

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

Ricalcola il prezzo

POST/v1/imports/{id}/analysis

La stessa inserzione per un altro paese, linea, peso, marketplace o margine. Calcolata da ciò che abbiamo già letto, quindi non consuma chiamate al marketplace. Restituisce la nuova analisi e la conserva sull’importazione.

Scopeproducts:write

Parametri di percorso

idstringobbligatorio: L’ID dell’importazione.

Corpo

ship_tostring: Paese a due lettere per cui calcolare il pacco. US se omesso.
lanestring: saver o fast. saver se omesso.
weight_gintegerobbligatorio: Il peso imballato di un’unità, in grammi. Le inserzioni non indicano il peso, quindi il pacco si calcola sul tuo.
marketplacestring: Dove lo vendi: ebay, shopify, amazon o tiktok. shopify se omesso.
marketplace_feeobject: Facoltativo. percent e fixed (US$) da usare al posto dell’aliquota principale del marketplace, per la tua categoria o il tuo piano.
margin_percentstring: Il margine su cui calcolare il prezzo, sul prezzo di vendita. 30 se omesso.

Errori

Stato	Tipo	Quando
404	not-found	Nessuna importazione simile su questo account.

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

Recupera un’importazione

GET/v1/imports/{id}

Rileggi un’importazione, o interroga un foglio di scoperte mentre è in corso.

Scopeproducts:read

Parametri di percorso

idstringobbligatorio: L’ID dell’importazione.

Errori

Stato	Tipo	Quando
404	not-found	Nessuna importazione simile su questo account.

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
}

Elenca le importazioni

GET/v1/imports

Dal più recente. Le importazioni mai salvate restano qui per quando vorrai riprenderle.

Scopeproducts:read

Parametri di query

statusstring: Facoltativo. running, ready o failed.
savedboolean: Facoltativo. true per quelli diventati prodotti.
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"
}

Salva come prodotto

POST/v1/imports/{id}/save

Tiene le varianti scelte come prodotto, ai prezzi che imposti o a quelli suggeriti. Aggiungi push_to: shopify per pubblicarlo nel tuo negozio nella stessa chiamata (Push to Shopify).

Scopeproducts:write

Parametri di percorso

idstringobbligatorio: L’ID dell’importazione.

Corpo

variants[]array: Facoltativo. sku e price di ogni variante da tenere. Se omesso, ogni variante disponibile al prezzo suggerito.
titlestring: Facoltativo. Il tuo titolo; quello del venditore è il più delle volte in cinese.
push_tostring: Facoltativo. shopify.

Errori

Stato	Tipo	Quando
409	invalid-state	Già salvato; product lo indica.
422	unprocessable	Tutte le varianti che hai tenuto sono esaurite.

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