API de catálogo2026-11Prévia

Produtos

Um anúncio que você salvou de uma importação, com o seu título, os seus preços e as lojas em que ele é vendido.

A Shopify é para onde os produtos são enviados. Os pedidos dos marketplaces em que a sua loja Shopify vende também chegam até nós pela Shopify: Conecte uma loja.
Uma loja WooCommerce ou Wix mantém os próprios produtos e envia os pedidos com Criar um pedido.

Endpoints

GET/v1/productsListar produtos
GET/v1/products/{id}Obter um produto
PATCH/v1/products/{id}Atualizar um produto
POST/v1/products/{id}/pushEnviar para a Shopify
DELETE/v1/products/{id}Excluir um produto

O objeto Product

idstring: Começa com prd_.
titlestring: O seu título. O do vendedor fica na importação.
statusstring: active, ou paused (por você, ou por uma regra de sincronização quando um custo subiu demais ou o vendedor ficou sem estoque).
sourceobject: Marketplace, link do anúncio e vendedor na China.
options[]array: Nomes das opções, no máximo três, como a sua loja os mostra.
price_range, cost_rangeobject: Os seus preços e os do vendedor, em todas as variantes.
channels[]array: Onde está anunciado: a loja, o id do produto lá e o status lá.
syncobject: A regra de sincronização que ele segue e quando lemos o anúncio pela última vez.
importstring: A importação de onde foi salvo.

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

Listar produtos

GET/v1/products

Os seus produtos, dos mais recentes aos mais antigos.

Escopoproducts:read

Parâmetros de consulta

statusstring: Opcional. active ou paused.
channelstring: Opcional. shopify, para os anunciados lá.
changed_sincestring: Opcional. Um horário: só os produtos cujo custo ou estoque mudou desde então.
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"
}

Obter um produto

GET/v1/products/{id}

Um produto com a fonte, os canais e o estado de sincronização. As variantes dele têm rota própria.

Escopoproducts:read

Parâmetros de caminho

idstringobrigatório: O id do produto.

Erros

Status	Tipo	Quando
404	not-found	Esse produto não existe nesta conta.

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

Atualizar um produto

PATCH/v1/products/{id}

Altere o título ou a descrição, ou pause e retome o produto. Envie só o que muda. Os preços são por variante (Variantes); um produto enviado leva a mudança à sua loja no próximo envio.

Escopoproducts:write

Parâmetros de caminho

idstringobrigatório: O id do produto.

Corpo

titlestring: Opcional.
descriptionstring: Opcional. HTML que a sua loja mostra.
statusstring: Opcional. active ou paused. Paused coloca o estoque em 0 nos seus canais.
sync_rulestring: Opcional. Um id de regra de sincronização; a regra padrão se null.

Erros

Status	Tipo	Quando
404	not-found	Esse produto não existe nesta conta.

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

Anuncia o produto na sua loja Shopify vinculada: um produto da Shopify, uma variante por SKU que você manteve, as fotos e cada variante com estoque no local Fulfilled by NinjaBuy, para que os pedidos cheguem até nós.

O primeiro envio cria o produto como rascunho: o título e as fotos vieram de um marketplace chinês, então leia antes dos seus compradores e depois publique na Shopify.
Enviar de novo atualiza o mesmo produto da Shopify: preços e estoque são definidos de novo, e as variantes que você descartou são removidas. Status, título, descrição e fotos ficam como você deixou na Shopify, a menos que você envie novos.
O estoque é a contagem do vendedor, limitada a 100: compramos sob demanda, então é quantos pedidos a Shopify aceita antes de mostrar esgotado.
A sua loja precisa vender em US$, já que os preços estão nessa moeda. Variantes esgotadas são ignoradas e listadas em skipped[].

Escopoproducts:write

Parâmetros de caminho

idstringobrigatório: O id do produto.

Corpo

shopstring: Qual loja vinculada, como acme-goods.myshopify.com. Necessário só quando você vinculou várias.
title, descriptionstring: Opcional. Enviados à Shopify só quando você os envia.

Erros

Status	Tipo	Quando
409	no-linked-store	Nenhuma loja Shopify está vinculada a esta conta, ou há várias e `shop` está faltando.
409	store-not-ready	O acesso da loja expirou, ou o nosso local ainda não está configurado: abra o app da NinjaBuy na Shopify uma vez.
422	store-currency	A loja não vende em US$.
422	too-many-options	O anúncio tem mais de três opções; a Shopify aceita três.
422	unprocessable	Todas as variantes estão esgotadas, ou a Shopify recusou um campo; detail repassa as palavras dela.

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

Excluir um produto

DELETE/v1/products/{id}

Para de sincronizá-lo e coloca o estoque em 0 nos seus canais; o produto da Shopify fica para você arquivar. Pedidos já feitos continuam sendo enviados.

Escopoproducts:write

Parâmetros de caminho

idstringobrigatório: O id do produto.

Erros

Status	Tipo	Quando
404	not-found	Esse produto não existe nesta conta.

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 }

O objeto Product

Listar produtos

Parâmetros de consulta

Obter um produto

Parâmetros de caminho

Erros

Atualizar um produto

Parâmetros de caminho

Corpo

Erros

Enviar para a Shopify

Parâmetros de caminho

Corpo

Erros

Excluir um produto

Parâmetros de caminho

Erros