API de catálogo2026-11Vista previa

Reglas de sincronización

Qué pasa con tu publicación cuando un vendedor en China cambia un precio o se queda sin stock.

Volvemos a leer una publicación cuando llega un pedido de ella y de forma periódica; el last_checked_at de cada producto indica cuándo lo hicimos por última vez. Mantener los productos sincronizados es gratis.
Cada cambio sobre el que actuamos también es un evento: product.cost_changed y product.out_of_stock.

Endpoints

GET/v1/sync_rulesListar reglas de sincronización
GET/v1/sync_rules/{id}Obtener una regla de sincronización
POST/v1/sync_rulesExcepción para un producto
PUT/v1/sync_rules/{id}Reemplazar una regla de sincronización
DELETE/v1/sync_rules/{id}Eliminar una excepción

El objeto Sync rule

idstring: Empieza por rule_; la regla por defecto es rule_default.
applies_tostring: all para la regla por defecto, o un id de producto para una excepción.
on_cost_increase.actionstring: reprice para mantener tu margen, pause para pausar el producto, o notify solo para avisar.
on_cost_increase.keep_margin_percentstring: Con reprice: el margen que se conserva, sobre el precio de venta.
on_cost_increase.max_increase_percentstring|null: Con reprice: lo máximo que puede subir un precio de una vez. Por encima, se aplica above_max: pausar o notificar.
on_cost_decreasestring: keep_price, o bajar el precio hasta el mismo margen.
on_out_of_stockstring: Siempre zero_stock: un SKU agotado muestra 0 en tus canales.
on_back_in_stockstring: restock, o stay_paused hasta que lo reanudes.
round_tostring|null: Una terminación para los precios recalculados, como .99 o .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 reglas de sincronización

GET/v1/sync_rules

Primero la regla por defecto, luego cada excepción por producto.

Alcanceproducts: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
}

Obtener una regla de sincronización

GET/v1/sync_rules/{id}

Una regla.

Alcanceproducts:read

Parámetros de ruta

idstringobligatorio: El id de la regla.

Errores

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

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

Excepción para un producto

POST/v1/sync_rules

Un producto con su propia regla la sigue en lugar de la regla por defecto. Los campos que omites toman los de la regla por defecto.

Alcanceproducts:write

Cuerpo

applies_tostringobligatorio: all para la regla por defecto, o un id de producto para una excepción.
on_cost_increase.actionstring: reprice para mantener tu margen, pause para pausar el producto, o notify solo para avisar.
on_cost_increase.keep_margin_percentstring: Con reprice: el margen que se conserva, sobre el precio de venta.
on_cost_increase.max_increase_percentstring|null: Con reprice: lo máximo que puede subir un precio de una vez. Por encima, se aplica above_max: pausar o notificar.
on_cost_decreasestring: keep_price, o bajar el precio hasta el mismo margen.
on_out_of_stockstring: Siempre zero_stock: un SKU agotado muestra 0 en tus canales.
on_back_in_stockstring: restock, o stay_paused hasta que lo reanudes.
round_tostring|null: Una terminación para los precios recalculados, como .99 o .00.

Errores

Estado	Tipo	Cuándo
404	not-found	No existe ese producto en esta cuenta.
409	invalid-state	El producto ya tiene una excepción: reemplaza esa.

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

Reemplazar una regla de sincronización

PUT/v1/sync_rules/{id}

Envía la regla completa. Se aplica a partir de la siguiente vez que leamos cada publicación.

Alcanceproducts:write

Parámetros de ruta

idstringobligatorio: El id de la regla.

Cuerpo

on_cost_increase.actionstring: reprice para mantener tu margen, pause para pausar el producto, o notify solo para avisar.
on_cost_increase.keep_margin_percentstring: Con reprice: el margen que se conserva, sobre el precio de venta.
on_cost_increase.max_increase_percentstring|null: Con reprice: lo máximo que puede subir un precio de una vez. Por encima, se aplica above_max: pausar o notificar.
on_cost_decreasestring: keep_price, o bajar el precio hasta el mismo margen.
on_out_of_stockstring: Siempre zero_stock: un SKU agotado muestra 0 en tus canales.
on_back_in_stockstring: restock, o stay_paused hasta que lo reanudes.
round_tostring|null: Una terminación para los precios recalculados, como .99 o .00.

Errores

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

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

Eliminar una excepción

DELETE/v1/sync_rules/{id}

El producto vuelve a seguir la regla por defecto. rule_default en sí no se puede eliminar.

Alcanceproducts:write

Parámetros de ruta

idstringobligatorio: El id de la regla.

Errores

Estado	Tipo	Cuándo
409	invalid-state	rule_default no se puede eliminar.

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 }