API de catálogo2026-11Prévia

Regras de sincronização

O que acontece com o seu anúncio quando um vendedor na China muda um preço ou fica sem estoque.

Lemos um anúncio de novo quando chega um pedido dele e periodicamente; o last_checked_at de cada produto diz quando fizemos isso pela última vez. Manter os produtos sincronizados é grátis.
Cada mudança sobre a qual agimos também é um evento: product.cost_changed e product.out_of_stock.

Endpoints

GET/v1/sync_rulesListar regras de sincronização
GET/v1/sync_rules/{id}Obter uma regra de sincronização
POST/v1/sync_rulesExceção para um produto
PUT/v1/sync_rules/{id}Substituir uma regra de sincronização
DELETE/v1/sync_rules/{id}Excluir uma exceção

O objeto Sync rule

idstring: Começa com rule_; a regra padrão é rule_default.
applies_tostring: all para a regra padrão, ou um id de produto para uma exceção.
on_cost_increase.actionstring: reprice para manter a sua margem, pause para pausar o produto, ou notify só para avisar.
on_cost_increase.keep_margin_percentstring: Com reprice: a margem a manter, sobre o preço de venda.
on_cost_increase.max_increase_percentstring|null: Com reprice: o máximo que um preço pode subir de uma vez. Acima disso, vale above_max: pausar ou notificar.
on_cost_decreasestring: keep_price, ou reajustar para baixo até a mesma margem.
on_out_of_stockstring: Sempre zero_stock: um SKU esgotado mostra 0 nos seus canais.
on_back_in_stockstring: restock, ou stay_paused até você retomar.
round_tostring|null: Uma terminação para preços reajustados, como .99 ou .00.

sync_rule

{
  "id": "rule_default",
  "applies_to": "all",
  "on_cost_increase": {
    "action": "reprice",
    "keep_margin_percent": "30",
    "max_increase_percent": "15",
    "above_max": "pause"
  },
  "on_cost_decrease": "keep_price",
  "on_out_of_stock": "zero_stock",
  "on_back_in_stock": "restock",
  "round_to": ".99",
  "updated_at": "2026-11-02T08:00:00Z"
}

Listar regras de sincronização

GET/v1/sync_rules

Primeiro a regra padrão, depois cada exceção por produto.

Escopoproducts:read

curl "https://www.ninjabuy.com/api/v1/sync_rules" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{
  "data": [
    {
      "id": "rule_default",
      "applies_to": "all",
      "on_cost_increase": {
        "action": "reprice",
        "keep_margin_percent": "30",
        "max_increase_percent": "15",
        "above_max": "pause"
      },
      "on_cost_decrease": "keep_price",
      "on_out_of_stock": "zero_stock",
      "on_back_in_stock": "restock",
      "round_to": ".99",
      "updated_at": "2026-11-02T08:00:00Z"
    },
    {
      "id": "rule_9p3e",
      "applies_to": "prd_1x0a",
      "on_cost_increase": { "action": "pause" },
      "on_cost_decrease": "keep_price",
      "on_out_of_stock": "zero_stock",
      "on_back_in_stock": "stay_paused",
      "round_to": null,
      "updated_at": "2026-11-03T10:14:00Z"
    }
  ],
  "has_more": false,
  "cursor": null
}

Obter uma regra de sincronização

GET/v1/sync_rules/{id}

Uma regra.

Escopoproducts:read

Parâmetros de caminho

idstringobrigatório: O id da regra.

Erros

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

curl "https://www.ninjabuy.com/api/v1/sync_rules/rule_default" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{
  "id": "rule_default",
  "applies_to": "all",
  "on_cost_increase": {
    "action": "reprice",
    "keep_margin_percent": "30",
    "max_increase_percent": "15",
    "above_max": "pause"
  },
  "on_cost_decrease": "keep_price",
  "on_out_of_stock": "zero_stock",
  "on_back_in_stock": "restock",
  "round_to": ".99",
  "updated_at": "2026-11-02T08:00:00Z"
}

Exceção para um produto

POST/v1/sync_rules

Um produto com regra própria segue essa regra em vez da padrão. Os campos que você omitir usam os da padrão.

Escopoproducts:write

Corpo

applies_tostringobrigatório: all para a regra padrão, ou um id de produto para uma exceção.
on_cost_increase.actionstring: reprice para manter a sua margem, pause para pausar o produto, ou notify só para avisar.
on_cost_increase.keep_margin_percentstring: Com reprice: a margem a manter, sobre o preço de venda.
on_cost_increase.max_increase_percentstring|null: Com reprice: o máximo que um preço pode subir de uma vez. Acima disso, vale above_max: pausar ou notificar.
on_cost_decreasestring: keep_price, ou reajustar para baixo até a mesma margem.
on_out_of_stockstring: Sempre zero_stock: um SKU esgotado mostra 0 nos seus canais.
on_back_in_stockstring: restock, ou stay_paused até você retomar.
round_tostring|null: Uma terminação para preços reajustados, como .99 ou .00.

Erros

Status	Tipo	Quando
404	not-found	Esse produto não existe nesta conta.
409	invalid-state	O produto já tem uma exceção: substitua essa.

curl -X POST "https://www.ninjabuy.com/api/v1/sync_rules" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "applies_to": "prd_1x0a",
    "on_cost_increase": { "action": "pause" },
    "on_back_in_stock": "stay_paused"
  }'

Response 201

HTTP/2 201 Created

{
  "id": "rule_9p3e",
  "applies_to": "prd_1x0a",
  "on_cost_increase": { "action": "pause" },
  "on_cost_decrease": "keep_price",
  "on_out_of_stock": "zero_stock",
  "on_back_in_stock": "stay_paused",
  "round_to": null,
  "updated_at": "2026-11-03T10:14:00Z"
}

Substituir uma regra de sincronização

PUT/v1/sync_rules/{id}

Envie a regra inteira. Ela vale a partir da próxima vez que lermos cada anúncio.

Escopoproducts:write

Parâmetros de caminho

idstringobrigatório: O id da regra.

Corpo

on_cost_increase.actionstring: reprice para manter a sua margem, pause para pausar o produto, ou notify só para avisar.
on_cost_increase.keep_margin_percentstring: Com reprice: a margem a manter, sobre o preço de venda.
on_cost_increase.max_increase_percentstring|null: Com reprice: o máximo que um preço pode subir de uma vez. Acima disso, vale above_max: pausar ou notificar.
on_cost_decreasestring: keep_price, ou reajustar para baixo até a mesma margem.
on_out_of_stockstring: Sempre zero_stock: um SKU esgotado mostra 0 nos seus canais.
on_back_in_stockstring: restock, ou stay_paused até você retomar.
round_tostring|null: Uma terminação para preços reajustados, como .99 ou .00.

Erros

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

curl -X PUT "https://www.ninjabuy.com/api/v1/sync_rules/rule_default" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Content-Type: application/json" \
  -d '{
    "on_cost_increase": { "action": "notify" },
    "on_cost_decrease": "keep_price",
    "on_out_of_stock": "zero_stock",
    "on_back_in_stock": "restock",
    "round_to": ".99"
  }'

Response 200

HTTP/2 200 OK

{
  "id": "rule_default",
  "applies_to": "all",
  "on_cost_increase": { "action": "notify" },
  "on_cost_decrease": "keep_price",
  "on_out_of_stock": "zero_stock",
  "on_back_in_stock": "restock",
  "round_to": ".99",
  "updated_at": "2026-11-02T08:00:00Z"
}

Excluir uma exceção

DELETE/v1/sync_rules/{id}

O produto volta a seguir a regra padrão. A rule_default em si não pode ser excluída.

Escopoproducts:write

Parâmetros de caminho

idstringobrigatório: O id da regra.

Erros

Status	Tipo	Quando
409	invalid-state	rule_default não pode ser excluída.

curl -X DELETE "https://www.ninjabuy.com/api/v1/sync_rules/rule_9p3e" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{ "id": "rule_9p3e", "deleted": true }