API de catálogo2026-11Prévia

Importações

Cole o link de um anúncio e receba as variantes e quanto custa vender cada uma: as mercadorias, a nossa taxa de recebimento de CN¥ 12,00 pelo pacote do vendedor até nós, o imposto fixo de 14%, depois a linha de envio, a taxa de manuseio de CN¥ 50,00 por pacote e o imposto sobre elas, a taxa do marketplace e o preço que mantém a sua margem.

Importar é grátis, sem limite de produtos. Você só paga pelo que pedir.
Cada valor é uma unidade, comprada no seu próprio pedido e enviada no seu próprio pacote: uma venda por dropshipping. Várias unidades em um pedido ou pacote custam menos do que isto indica.
As taxas do marketplace usam por padrão a tarifa pública principal de cada marketplace. Envie a sua quando a sua categoria ou plano for diferente.

Endpoints

POST/v1/importsImportar de um link
POST/v1/imports/{id}/analysisPrecificar de novo
GET/v1/imports/{id}Obter uma importação
GET/v1/importsListar importações
POST/v1/imports/{id}/saveSalvar como produto

O objeto Import

Um anúncio como nós o lemos, com o custo de uma venda entregue na porta do seu comprador: as mercadorias, a nossa taxa de recebimento de CN¥ 12,00 pelo pacote do vendedor até nós, o imposto fixo de 14%, depois a linha de envio, a taxa de manuseio de CN¥ 50,00 por pacote e o imposto sobre elas. Em US$, é o que um cartão em US$ paga, conversão de moeda incluída.

idstring: Começa com imp_.
statusstring: running (uma planilha de achados ainda sendo lida), ready ou failed.
urlstring: O link que você enviou.
marketplacestring: taobao, tmall, weidian ou 1688.
title, seller, images[]string: Como o vendedor escreveu, quase sempre em chinês.
read_atstring: Quando lemos o anúncio no marketplace pela última vez.
analysis.ship_to, lane, weight_g: Os dados usados para o cálculo do preço.
analysis.coveredboolean: False quando nenhuma tarifa publicada envia para esse país nessa linha; aí nenhuma variante tem custo final.
analysis.marketplace_feeobject: percent e fixed: o que o marketplace fica de uma venda. default é true quando você não enviou nenhuma e usamos a tarifa pública principal, uma estimativa, nunca a sua conta real.
analysis.margin_reachableboolean: False quando a taxa e a margem juntas tomam o preço inteiro: nenhum preço consegue alcançá-lo.
analysis.brand_hintobject|null: Palavras de marca ou de réplica encontradas no título, em inglês ou chinês. Uma pista, nunca um veredito: não enxerga um logo em uma foto, e um resultado limpo não prova nada.
analysis.variants[].procurementobject: goods, intake_fee, tax e total do pedido que compra uma unidade.
analysis.variants[].seller_shippingobject|null: O frete do vendedor até o nosso armazém. Nenhum anúncio informa isso, então é null: desconhecido, não grátis.
analysis.variants[].parcelobject|null: lane, shipping, handling_fee, tax e total do pacote que o envia.
analysis.variants[].landedobject: Item e pacote juntos: em CN¥, em US$ e com a taxa de conversão incluída no valor em US$.
analysis.variants[].minimum_priceobject|null: O menor preço que mantém a sua margem depois da taxa do marketplace.
analysis.variants[].suggestedobject|null: O menor preço x.99 igual ou acima do mínimo, com a taxa, o lucro e a margem que ele deixa.
productstring|null: O produto em que se transformou ao ser salvo.

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 de um link

POST/v1/imports

Lê um anúncio da Taobao, Tmall, Weidian ou 1688 (um link curto, ou o link de outro agente de compras para ele, também funciona) e responde com ele analisado, na mesma chamada. Um anúncio que lemos nos últimos cinco minutos não é buscado de novo.

Um link de planilha de achados (https://www.ninjabuy.com/spreadsheets/d/…) importa todos os produtos dela: 202 com status: running; depois consulte a importação.

Escopoproducts:write

Corpo

urlstringobrigatório: Um link de produto, ou uma planilha de achados.
ship_tostring: País de duas letras para o cálculo do pacote. US se omitido.
lanestring: saver ou fast. saver se omitido.
weight_gintegerobrigatório: O peso embalado de uma unidade, em gramas. Os anúncios não informam peso, então o pacote é calculado pelo seu.
marketplacestring: Onde você vende: ebay, shopify, amazon ou tiktok. shopify se omitido.
marketplace_feeobject: Opcional. percent e fixed (US$) para usar no lugar da tarifa principal do marketplace, conforme a sua categoria ou plano.
margin_percentstring: A margem para o cálculo do preço, sobre o preço de venda. 30 se omitido.

Erros

Status	Tipo	Quando
400	bad-body	weight_g está faltando, ou um campo está fora do intervalo.
422	unprocessable	Não é um link que conseguimos ler, ou o anúncio não existe mais.
429	rate-limited	A janela do marketplace se esgotou; veja Limites de requisições.

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

Precificar de novo

POST/v1/imports/{id}/analysis

O mesmo anúncio para outro país, linha, peso, marketplace ou margem. Calculado com o que já lemos, então não gasta nenhuma chamada ao marketplace. Responde com a nova análise e a guarda na importação.

Escopoproducts:write

Parâmetros de caminho

idstringobrigatório: O id da importação.

Corpo

ship_tostring: País de duas letras para o cálculo do pacote. US se omitido.
lanestring: saver ou fast. saver se omitido.
weight_gintegerobrigatório: O peso embalado de uma unidade, em gramas. Os anúncios não informam peso, então o pacote é calculado pelo seu.
marketplacestring: Onde você vende: ebay, shopify, amazon ou tiktok. shopify se omitido.
marketplace_feeobject: Opcional. percent e fixed (US$) para usar no lugar da tarifa principal do marketplace, conforme a sua categoria ou plano.
margin_percentstring: A margem para o cálculo do preço, sobre o preço de venda. 30 se omitido.

Erros

Status	Tipo	Quando
404	not-found	Essa importação não existe nesta conta.

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

Obter uma importação

GET/v1/imports/{id}

Leia uma importação de novo, ou consulte uma planilha de achados enquanto ela está sendo processada.

Escopoproducts:read

Parâmetros de caminho

idstringobrigatório: O id da importação.

Erros

Status	Tipo	Quando
404	not-found	Essa importação não existe nesta conta.

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 importações

GET/v1/imports

Mais recentes primeiro. Importações que você nunca salvou ficam aqui para você voltar a elas.

Escopoproducts:read

Parâmetros de consulta

statusstring: Opcional. running, ready ou failed.
savedboolean: Opcional. true para as que viraram produtos.
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"
}

Salvar como produto

POST/v1/imports/{id}/save

Guarda as variantes que você escolher como um produto, pelos preços que você definir ou pelos sugeridos. Adicione push_to: shopify para anunciá-lo na sua loja na mesma chamada (Enviar para a Shopify).

Escopoproducts:write

Parâmetros de caminho

idstringobrigatório: O id da importação.

Corpo

variants[]array: Opcional. sku e price de cada variante a manter. Se omitido, toda variante em estoque pelo preço sugerido.
titlestring: Opcional. O seu próprio título; o do vendedor quase sempre está em chinês.
push_tostring: Opcional. shopify.

Erros

Status	Tipo	Quando
409	invalid-state	Já salvo; product o identifica.
422	unprocessable	Todas as variantes que você manteve estão esgotadas.

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