API de catálogo2026-11Vista previa

Importaciones

Pega el enlace de una publicación y recibe sus variantes y lo que te cuesta vender cada una: la mercancía, nuestra tarifa de recepción de 12,00 CNY por el paquete del vendedor hasta nosotros, el impuesto fijo del 14%, luego la línea de envío, la tarifa de manipulación de 50,00 CNY por paquete y el impuesto sobre ellas, la comisión del marketplace y el precio que mantiene tu margen.

Importar es gratis, sin límite de productos. Solo pagas por lo que pides.
Cada cifra es una unidad, comprada en su propio pedido y enviada en su propio paquete: una venta por dropshipping. Varias unidades en un pedido o un paquete cuestan menos de lo que indica esto.
Las comisiones del marketplace toman por defecto la tarifa pública principal de cada marketplace. Envía la tuya cuando tu categoría o tu plan sean distintos.

Endpoints

POST/v1/importsImportar desde un enlace
POST/v1/imports/{id}/analysisRecalcular el precio
GET/v1/imports/{id}Obtener una importación
GET/v1/importsListar importaciones
POST/v1/imports/{id}/saveGuardar como producto

El objeto Import

Una publicación tal como la leemos, con lo que cuesta una venta puesta en la puerta de tu comprador: la mercancía, nuestra tarifa de recepción de 12,00 CNY por el paquete del vendedor hasta nosotros, el impuesto fijo del 14%, luego la línea de envío, la tarifa de manipulación de 50,00 CNY por paquete y el impuesto sobre ellas. En US$, es lo que se cobra a una tarjeta en US$, conversión de moneda incluida.

idstring: Empieza por imp_.
statusstring: running (una hoja de hallazgos que aún se está leyendo), ready o failed.
urlstring: El enlace que enviaste.
marketplacestring: taobao, tmall, weidian o 1688.
title, seller, images[]string: Como los escribió el vendedor, casi siempre en chino.
read_atstring: Cuándo leímos por última vez la publicación en el marketplace.
analysis.ship_to, lane, weight_g: Los datos con los que se calculó el precio.
analysis.coveredboolean: False cuando ninguna tarifa publicada envía a ese país en esa línea; entonces ninguna variante tiene costo puesto en destino.
analysis.marketplace_feeobject: percent y fixed: lo que el marketplace se queda de una venta. default es true cuando no enviaste ninguna y usamos su tarifa pública principal, una estimación, nunca tu factura real.
analysis.margin_reachableboolean: False cuando la comisión y el margen juntos se llevan todo el precio: ningún precio puede alcanzarlo.
analysis.brand_hintobject|null: Palabras de marca o de réplica encontradas en el título, en inglés o en chino. Una pista, nunca un veredicto: no puede ver un logo en una foto, y un resultado limpio no prueba nada.
analysis.variants[].procurementobject: goods, intake_fee, tax y total del pedido que compra una unidad.
analysis.variants[].seller_shippingobject|null: El envío del vendedor hasta nuestro almacén. Ninguna publicación lo indica, así que es null: desconocido, no gratis.
analysis.variants[].parcelobject|null: lane, shipping, handling_fee, tax y total del paquete que lo envía.
analysis.variants[].landedobject: Artículo y paquete juntos: en CN¥, en US$ y con la comisión de conversión incluida en los US$.
analysis.variants[].minimum_priceobject|null: El precio más bajo que mantiene tu margen después de la comisión del marketplace.
analysis.variants[].suggestedobject|null: El precio x.99 más bajo igual o superior al mínimo, con la comisión, la ganancia y el margen que deja.
productstring|null: El producto en que se convirtió al guardarse.

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

Importar desde un enlace

POST/v1/imports

Lee una publicación de Taobao, Tmall, Weidian o 1688 (también sirve un enlace corto, o el enlace de otro agente de compras) y responde con ella analizada, en la misma llamada. Una publicación que leímos en los últimos cinco minutos no se vuelve a obtener.

Un enlace a una hoja de hallazgos (https://www.ninjabuy.com/spreadsheets/d/…) importa todos sus productos: 202 con status: running; luego consulta la importación.

Alcanceproducts:write

Cuerpo

urlstringobligatorio: Un enlace de producto, o una hoja de hallazgos.
ship_tostring: País de dos letras para el que se calcula el paquete. US si se omite.
lanestring: saver o fast. saver si se omite.
weight_gintegerobligatorio: El peso empacado de una unidad, en gramos. Las publicaciones no indican peso, así que el paquete se calcula con el tuyo.
marketplacestring: Dónde lo vendes: ebay, shopify, amazon o tiktok. shopify si se omite.
marketplace_feeobject: Opcional. percent y fixed (US$) para usar en lugar de la tarifa principal del marketplace, según tu categoría o plan.
margin_percentstring: El margen para el que se calcula el precio, sobre el precio de venta. 30 si se omite.

Errores

Estado	Tipo	Cuándo
400	bad-body	Falta weight_g, o un campo está fuera de rango.
422	unprocessable	No es un enlace que podamos leer, o la publicación ya no existe.
429	rate-limited	Se agotó la ventana del marketplace; consulta Límites de tasa.

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

Recalcular el precio

POST/v1/imports/{id}/analysis

La misma publicación para otro país, línea, peso, marketplace o margen. Se calcula con lo que ya leímos, así que no gasta ninguna llamada al marketplace. Responde con el nuevo análisis y lo guarda en la importación.

Alcanceproducts:write

Parámetros de ruta

idstringobligatorio: El id de la importación.

Cuerpo

ship_tostring: País de dos letras para el que se calcula el paquete. US si se omite.
lanestring: saver o fast. saver si se omite.
weight_gintegerobligatorio: El peso empacado de una unidad, en gramos. Las publicaciones no indican peso, así que el paquete se calcula con el tuyo.
marketplacestring: Dónde lo vendes: ebay, shopify, amazon o tiktok. shopify si se omite.
marketplace_feeobject: Opcional. percent y fixed (US$) para usar en lugar de la tarifa principal del marketplace, según tu categoría o plan.
margin_percentstring: El margen para el que se calcula el precio, sobre el precio de venta. 30 si se omite.

Errores

Estado	Tipo	Cuándo
404	not-found	No existe esa importación en esta cuenta.

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

Obtener una importación

GET/v1/imports/{id}

Vuelve a leer una importación, o consulta una hoja de hallazgos mientras se procesa.

Alcanceproducts:read

Parámetros de ruta

idstringobligatorio: El id de la importación.

Errores

Estado	Tipo	Cuándo
404	not-found	No existe esa importación en esta cuenta.

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
}

Listar importaciones

GET/v1/imports

Lo más reciente primero. Las importaciones que nunca guardaste se quedan aquí para que vuelvas a ellas.

Alcanceproducts:read

Parámetros de consulta

statusstring: Opcional. running, ready o failed.
savedboolean: Opcional. true para las que se convirtieron en productos.
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"
}

Guardar como producto

POST/v1/imports/{id}/save

Guarda las variantes que elijas como un producto, a los precios que fijes o a los sugeridos. Agrega push_to: shopify para publicarlo en tu tienda en la misma llamada (Enviar a Shopify).

Alcanceproducts:write

Parámetros de ruta

idstringobligatorio: El id de la importación.

Cuerpo

variants[]array: Opcional. sku y price de cada variante que se conserva. Si se omite, cada variante en stock a su precio sugerido.
titlestring: Opcional. Tu propio título; el del vendedor casi siempre está en chino.
push_tostring: Opcional. shopify.

Errores

Estado	Tipo	Cuándo
409	invalid-state	Ya guardado; product lo indica.
422	unprocessable	Todas las variantes que conservaste están agotadas.

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