API Catalogue2026-11Aperçu

Imports

Collez le lien d’une annonce, récupérez ses variantes et ce que chacune vous coûte à vendre : les articles, nos frais de réception de 12,00 CNY pour le colis du vendeur jusqu’à nous, la taxe forfaitaire de 14 %, puis la ligne d’expédition, les frais de préparation de 50,00 CNY par colis et la taxe correspondante, les frais de la marketplace, et le prix qui garde votre marge.

L’import est gratuit, sans limite de produits. Vous ne payez que ce que vous commandez.
Chaque chiffre porte sur une unité, achetée dans sa propre commande et expédiée dans son propre colis : une vente en dropshipping. Plusieurs unités dans une commande ou un colis coûtent moins que ce qui est indiqué.
Les frais de marketplace prennent par défaut le taux public principal de chaque marketplace. Envoyez le vôtre si votre catégorie ou votre forfait diffère.

Endpoints

POST/v1/importsImporter depuis un lien
POST/v1/imports/{id}/analysisRefaire le prix
GET/v1/imports/{id}Récupérer un import
GET/v1/importsLister les imports
POST/v1/imports/{id}/saveEnregistrer comme produit

L’objet Import

Une annonce telle que nous la lisons, avec le coût d’une vente livrée chez votre acheteur : les articles, nos frais de réception de 12,00 CNY pour le colis du vendeur jusqu’à nous, la taxe forfaitaire de 14 %, puis la ligne d’expédition, les frais de préparation de 50,00 CNY par colis et la taxe correspondante. En US$, c’est le montant débité sur une carte en US$, conversion comprise.

idstring: Commence par imp_.
statusstring: running (un tableur de trouvailles encore en lecture), ready, ou failed.
urlstring: Le lien que vous avez envoyé.
marketplacestring: taobao, tmall, weidian ou 1688.
title, seller, images[]string: Tels que le vendeur les a écrits, le plus souvent en chinois.
read_atstring: La dernière lecture de l’annonce sur la marketplace.
analysis.ship_to, lane, weight_g: Les paramètres pour lesquels il a été chiffré.
analysis.coveredboolean: False quand aucun tarif publié n’expédie vers ce pays sur cette ligne ; aucune variante n’a alors de coût rendu.
analysis.marketplace_feeobject: percent et fixed : ce que la marketplace garde sur une vente. default vaut true quand vous n’en avez envoyé aucun et que nous avons utilisé son taux public principal : une estimation, jamais votre facture réelle.
analysis.margin_reachableboolean: False quand les frais et la marge prennent ensemble tout le prix : aucun prix ne peut l’atteindre.
analysis.brand_hintobject|null: Mots de marque ou de réplique trouvés dans le titre, en anglais ou en chinois. Un indice, jamais un verdict : il ne voit pas un logo sur une photo, et un résultat propre ne prouve rien.
analysis.variants[].procurementobject: goods, intake_fee, tax et total de la commande qui achète une unité.
analysis.variants[].seller_shippingobject|null: La livraison du vendeur jusqu’à notre entrepôt. Aucune annonce ne l’indique, donc elle vaut null : inconnue, pas gratuite.
analysis.variants[].parcelobject|null: lane, shipping, handling_fee, tax et total du colis qui l’expédie.
analysis.variants[].landedobject: Article et colis ensemble : en CN¥, en US$, frais de conversion inclus dans le montant en US$.
analysis.variants[].minimum_priceobject|null: Le prix le plus bas qui garde votre marge après les frais de marketplace.
analysis.variants[].suggestedobject|null: Le prix en x.99 le plus bas, égal ou supérieur au minimum, avec les frais, le bénéfice et la marge qu’il laisse.
productstring|null: Le produit qu’il est devenu une fois enregistré.

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

Importer depuis un lien

POST/v1/imports

Lit une annonce Taobao, Tmall, Weidian ou 1688 (un lien court, ou le lien d’un autre agent d’achat, fonctionne aussi) et la renvoie analysée, dans le même appel. Une annonce lue dans les cinq dernières minutes n’est pas récupérée à nouveau.

Un lien de tableur de trouvailles (https://www.ninjabuy.com/spreadsheets/d/…) importe tous ses produits : 202 avec status: running, puis interrogez l’import.

Scopeproducts:write

Corps

urlstringobligatoire: Un lien produit, ou un tableur de trouvailles.
ship_tostring: Pays à deux lettres pour lequel chiffrer le colis. US si omis.
lanestring: saver ou fast. saver si omis.
weight_gintegerobligatoire: Le poids emballé d’une unité, en grammes. Les annonces n’indiquent pas de poids : le colis est chiffré sur le vôtre.
marketplacestring: Où vous le vendez : ebay, shopify, amazon ou tiktok. shopify si omis.
marketplace_feeobject: Facultatif. percent et fixed (US$) à utiliser à la place du taux principal de la marketplace, pour votre catégorie ou votre forfait.
margin_percentstring: La marge visée, en part du prix de vente. 30 si omis.

Erreurs

Statut	Type	Quand
400	bad-body	weight_g manque, ou un champ est hors limites.
422	unprocessable	Ce n’est pas un lien lisible, ou l’annonce a disparu.
429	rate-limited	La fenêtre de la marketplace est épuisée ; voir Limites de débit.

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

Refaire le prix

POST/v1/imports/{id}/analysis

La même annonce pour un autre pays, une autre ligne, un autre poids, une autre marketplace ou une autre marge. Chiffrée à partir de ce que nous avons déjà lu : aucun appel à la marketplace. Renvoie la nouvelle analyse et la garde sur l’import.

Scopeproducts:write

Paramètres de chemin

idstringobligatoire: L’identifiant de l’import.

Corps

ship_tostring: Pays à deux lettres pour lequel chiffrer le colis. US si omis.
lanestring: saver ou fast. saver si omis.
weight_gintegerobligatoire: Le poids emballé d’une unité, en grammes. Les annonces n’indiquent pas de poids : le colis est chiffré sur le vôtre.
marketplacestring: Où vous le vendez : ebay, shopify, amazon ou tiktok. shopify si omis.
marketplace_feeobject: Facultatif. percent et fixed (US$) à utiliser à la place du taux principal de la marketplace, pour votre catégorie ou votre forfait.
margin_percentstring: La marge visée, en part du prix de vente. 30 si omis.

Erreurs

Statut	Type	Quand
404	not-found	Aucun import de ce type sur ce compte.

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

Récupérer un import

GET/v1/imports/{id}

Relisez un import, ou interrogez un tableur de trouvailles pendant sa lecture.

Scopeproducts:read

Paramètres de chemin

idstringobligatoire: L’identifiant de l’import.

Erreurs

Statut	Type	Quand
404	not-found	Aucun import de ce type sur ce compte.

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
}

Lister les imports

GET/v1/imports

Les plus récents d’abord. Les imports jamais enregistrés restent ici pour que vous y reveniez.

Scopeproducts:read

Paramètres de requête

statusstring: Facultatif. running, ready ou failed.
savedboolean: Facultatif. true pour ceux devenus des produits.
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"
}

Enregistrer comme produit

POST/v1/imports/{id}/save

Garde les variantes choisies comme produit, aux prix que vous fixez ou aux prix suggérés. Ajoutez push_to: shopify pour le publier dans votre boutique dans le même appel (Push to Shopify).

Scopeproducts:write

Paramètres de chemin

idstringobligatoire: L’identifiant de l’import.

Corps

variants[]array: Facultatif. sku et price de chaque variante à garder. Si omis, chaque variante en stock à son prix suggéré.
titlestring: Facultatif. Votre propre titre ; celui du vendeur est le plus souvent en chinois.
push_tostring: Facultatif. shopify.

Erreurs

Statut	Type	Quand
409	invalid-state	Déjà enregistré ; product l’indique.
422	unprocessable	Toutes les variantes conservées sont épuisées.

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