API Catalogo2026-11Anteprima

Regole di sincronizzazione

Cosa succede alla tua inserzione quando un venditore in Cina cambia un prezzo o esaurisce.

Rileggiamo un’inserzione quando arriva un suo ordine e a intervalli regolari; last_checked_at di ogni prodotto indica l’ultima volta. Tenere i prodotti sincronizzati è gratis.
Ogni modifica che applichiamo è anche un evento: product.cost_changed e product.out_of_stock.

Endpoint

GET/v1/sync_rulesElenca le regole di sincronizzazione
GET/v1/sync_rules/{id}Recupera una regola di sincronizzazione
POST/v1/sync_rulesEccezione per un prodotto
PUT/v1/sync_rules/{id}Sostituisci una regola di sincronizzazione
DELETE/v1/sync_rules/{id}Elimina un’eccezione

L’oggetto Sync rule

idstring: Inizia con rule_; la regola predefinita è rule_default.
applies_tostring: all per la regola predefinita, o un ID prodotto per un’eccezione.
on_cost_increase.actionstring: ricalcola il prezzo per mantenere il margine, metti in pausa il prodotto o invia solo una notifica.
on_cost_increase.keep_margin_percentstring: Con reprice: il margine da mantenere, sul prezzo di vendita.
on_cost_increase.max_increase_percentstring|null: Con reprice: l’aumento massimo di un prezzo in una volta. Oltre, si applica above_max: pause o notify.
on_cost_decreasestring: keep_price, o abbassa il prezzo allo stesso margine.
on_out_of_stockstring: Sempre zero_stock: uno SKU esaurito mostra 0 sui tuoi canali.
on_back_in_stockstring: restock, o stay_paused finché non lo riprendi.
round_tostring|null: Un finale di prezzo per i prezzi ricalcolati, come .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"
}

Elenca le regole di sincronizzazione

GET/v1/sync_rules

Prima la regola predefinita, poi ogni eccezione per prodotto.

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

Recupera una regola di sincronizzazione

GET/v1/sync_rules/{id}

Una regola.

Scopeproducts:read

Parametri di percorso

idstringobbligatorio: L’ID della regola.

Errori

Stato	Tipo	Quando
404	not-found	Nessuna regola simile su questo account.

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

Eccezione per un prodotto

POST/v1/sync_rules

Un prodotto con una regola propria segue quella invece della predefinita. I campi omessi prendono il valore della predefinita.

Scopeproducts:write

Corpo

applies_tostringobbligatorio: all per la regola predefinita, o un ID prodotto per un’eccezione.
on_cost_increase.actionstring: ricalcola il prezzo per mantenere il margine, metti in pausa il prodotto o invia solo una notifica.
on_cost_increase.keep_margin_percentstring: Con reprice: il margine da mantenere, sul prezzo di vendita.
on_cost_increase.max_increase_percentstring|null: Con reprice: l’aumento massimo di un prezzo in una volta. Oltre, si applica above_max: pause o notify.
on_cost_decreasestring: keep_price, o abbassa il prezzo allo stesso margine.
on_out_of_stockstring: Sempre zero_stock: uno SKU esaurito mostra 0 sui tuoi canali.
on_back_in_stockstring: restock, o stay_paused finché non lo riprendi.
round_tostring|null: Un finale di prezzo per i prezzi ricalcolati, come .99 o .00.

Errori

Stato	Tipo	Quando
404	not-found	Nessun prodotto simile su questo account.
409	invalid-state	Il prodotto ha già un’eccezione: sostituisci quella.

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

Sostituisci una regola di sincronizzazione

PUT/v1/sync_rules/{id}

Invia l’intera regola. Si applica dalla prossima volta che leggiamo ciascuna inserzione.

Scopeproducts:write

Parametri di percorso

idstringobbligatorio: L’ID della regola.

Corpo

on_cost_increase.actionstring: ricalcola il prezzo per mantenere il margine, metti in pausa il prodotto o invia solo una notifica.
on_cost_increase.keep_margin_percentstring: Con reprice: il margine da mantenere, sul prezzo di vendita.
on_cost_increase.max_increase_percentstring|null: Con reprice: l’aumento massimo di un prezzo in una volta. Oltre, si applica above_max: pause o notify.
on_cost_decreasestring: keep_price, o abbassa il prezzo allo stesso margine.
on_out_of_stockstring: Sempre zero_stock: uno SKU esaurito mostra 0 sui tuoi canali.
on_back_in_stockstring: restock, o stay_paused finché non lo riprendi.
round_tostring|null: Un finale di prezzo per i prezzi ricalcolati, come .99 o .00.

Errori

Stato	Tipo	Quando
404	not-found	Nessuna regola simile su questo account.

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

Elimina un’eccezione

DELETE/v1/sync_rules/{id}

Il prodotto segue di nuovo la regola predefinita. rule_default stessa non può essere eliminata.

Scopeproducts:write

Parametri di percorso

idstringobbligatorio: L’ID della regola.

Errori

Stato	Tipo	Quando
409	invalid-state	rule_default non può essere eliminata.

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 }