Annullamento e conferme

Due regole proteggono uno store quando lo gestisce un'app (o un agente AI):

1. Tutto è tracciabile e quasi tutto si può annullare. Ogni modifica viene registrata nel registro delle azioni con chi l'ha fatta e i valori esatti prima e dopo. Per 30 giorni puoi annullarla.
2. Ciò che non si può annullare chiede prima. Rimuovere dai canali, scollegare un canale, rimuovere varianti, rimborsare un ordine dello storefront, annullare un'importazione e chiudere un'azienda usano tutti la stessa conferma in due passaggi.

Trova cosa è stato fatto

Ogni scrittura risponde con un header Nembol-Action-Id, comprese quelle irreversibili (spedire un ordine, rimuovere dai canali, scollegare). La ripetizione della stessa Idempotency-Key (Idempotent-Replayed: true) non è una nuova scrittura: non registra nessuna azione e non ha l'header. Il registro completo:

curl "https://api.nembol.com/rest/v1/actions?product_id=prod_66f0a1" \
  -H "Authorization: Bearer $NEMBOL_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "act_66f0b2",
      "object": "action",
      "type": "product.update",
      "summary": "Edited product \"Blue mug\"",
      "actor": { "type": "api_key", "name": "Inventory agent", "via": "mcp" },
      "reversibility": "reversible",
      "undoable": true,
      "undoable_until": "2026-11-07T10:00:00.000Z",
      "items": [
        {
          "product_id": "prod_66f0a1",
          "changes": [
            { "path": "fields.title", "before": "Blue mug", "after": "Big blue mug" },
            { "path": "variants.66f0a2.price", "before": "10.00", "after": "12.00" }
          ]
        }
      ],
      "created_at": "2026-10-08T10:00:00.000Z"
    }
  ]
}

Vengono registrati: creazione/modifica/eliminazione/ripristino di prodotti, modifiche a varianti e inventario, variazioni di prezzo, batch di prodotti, importazioni, impostazioni degli account dei canali (anche quando cambiate nella dashboard), pubblicazioni, rimozioni dai canali, spedizioni e collegamenti/scollegamenti. Conservati 90 giorni. Per leggerli serve events:read o products:read.

Annulla

Prima l'anteprima:

curl -X POST https://api.nembol.com/rest/v1/actions/act_66f0b2/undo \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": true}'

{
  "object": "undo_preview",
  "status": "simulated",
  "outcome": "partial",
  "items": [
    {
      "product_id": "prod_66f0a1",
      "restored": ["variants.var_66f0a2.price"],
      "unchanged": [],
      "conflicts": [{ "path": "fields.title", "reason": "changed_since", "current": "Mug v3" }]
    }
  ]
}

Un dry run non annulla mai nulla: status è sempre simulated e outcome dice cosa risponderebbe l'annullamento reale (undone, partial, conflict, nothing_to_undo). L'annullamento di un'unione elenca tutti i prodotti: il superstite (role: "survivor": campi, varianti e inserzioni che tornano indietro) e ognuno di quelli assorbiti (role: "absorbed": torna con le sue inserzioni).

Poi la stessa chiamata senza dry_run. Come viene trattato ogni valore:

I prodotti ripristinati vengono reinviati ai loro canali. L'annullamento è a sua volta un'azione (undo_of punta all'originale) e un'azione si può annullare una sola volta.

Prodotti eliminati e le loro immagini

Un prodotto eliminato mantiene le sue immagini per 30 giorni, quindi ripristinandolo entro quel periodo tornano anche loro. Dopo 30 giorni le immagini vengono rimosse; i dati del prodotto si possono ancora ripristinare, senza immagini.

Conferma in due passaggi

Le azioni irreversibili (DELETE /listings/{id}, POST /listings/batch con action: "delist", lo scollegamento di un account del canale…) rispondono prima 409. La spedizione di un ordine (POST /orders/{id}/fulfillment) non chiede conferma: è il passaggio automatico di un sistema di evasione, e il marketplace viene avvisato al massimo una volta per ordine.

{
  "error": {
    "type": "invalid_request_error",
    "code": "confirmation_required",
    "message": "Delisting ends this listing on its channel. Publishing it again later creates a NEW listing … repeat the SAME request with header \"Nembol-Confirmation: cfm_3kTq9Xb2\" within 10 minutes."
  },
  "confirmation": {
    "token": "cfm_3kTq9Xb2",
    "summary": "Delisting ends this listing on its channel. …",
    "expires_at": "2026-10-08T10:10:00.000Z"
  }
}

Mostra confirmation.summary alla persona. Se è d'accordo, invia di nuovo la stessa richiesta con l'header:

curl -X DELETE https://api.nembol.com/rest/v1/listings/list_cHJvZF8x \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Nembol-Confirmation: cfm_3kTq9Xb2"

Nembol chiede la conferma solo quando la richiesta è valida e l'azione è possibile, così la tua app non chiede mai a una persona di confermare qualcosa che non può accadere:

• un'azienda, un'importazione, un'inserzione o un ordine sconosciuti rispondono subito 404;
• un'importazione già annullata o un'inserzione che non si può rimuovere dal canale rispondono subito con il proprio errore;
• chiudere un'azienda già chiusa risponde 200 con l'azienda così com'è: la chiusura è idempotente, non c'è nulla da confermare;
• una rimozione in blocco conta nel suo riepilogo solo le inserzioni che verrebbero davvero chiuse; quando nessuna lo sarebbe (sconosciute, già rimosse, non rimovibili), risponde con gli esiti per elemento senza conferma.

Il riepilogo nomina l'oggetto dell'azione (il prodotto e il negozio per una rimozione dal canale, il negozio per uno scollegamento, l'azienda per una chiusura), così puoi mostrarlo alla persona così com'è.

Il token vale una sola volta, per quella richiesta esatta, per 10 minuti. Viene richiesto per le chiavi create dal 2026-10-08 e per ogni chiamata fatta tramite il server MCP di Nembol (Nembol-Client: mcp).

Buone pratiche per gli agenti

• Conserva il Nembol-Action-Id di ciò che hai fatto, così puoi annullarlo con precisione. Non "annullare l'ultima cosa" alla cieca.
• Fai l'anteprima con dry_run e informa la persona dei conflitti invece di forzare i valori.
• Non confermare mai al posto della persona: una risposta confirmation_required è il momento di chiederglielo.

Ultimo aggiornamento il 20 ottobre 2026