Annulation et confirmations

Deux règles protègent une boutique quand une application (ou un agent IA) la gère :

1. Tout est traçable et la plupart des choses peuvent être annulées. Chaque modification est enregistrée dans le journal des actions avec son auteur et les valeurs exactes avant et après. Pendant 30 jours, vous pouvez l'annuler.
2. Ce qui ne peut pas être annulé demande d'abord. Retirer des annonces, déconnecter un canal, supprimer des variantes, rembourser une commande du storefront, annuler un import et fermer une entreprise utilisent tous la même confirmation en deux étapes.

Retrouver ce qui a été fait

Chaque écriture répond avec un en-tête Nembol-Action-Id, y compris les écritures irréversibles (expédier une commande, retirer une annonce, déconnecter). Un rejeu de la même Idempotency-Key (Idempotent-Replayed: true) n'est pas une nouvelle écriture : il n'enregistre aucune action et n'a pas d'en-tête. Le journal complet :

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

Sont journalisés : création/modification/suppression/restauration de produits, modifications de variantes et d'inventaire, ajustements de prix, batchs de produits, imports, paramètres des comptes de canal (y compris quand ils sont modifiés dans le tableau de bord), publications, retraits, expéditions et connexions/déconnexions. Conservé 90 jours. La lecture nécessite events:read ou products:read.

Annuler

D'abord l'aperçu :

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 n'annule jamais rien : status vaut toujours simulated et outcome indique ce que répondrait la vraie annulation (undone, partial, conflict, nothing_to_undo). L'annulation d'une fusion liste chaque produit : le produit conservé (role: "survivor" : champs, variantes et annonces qui reviennent en arrière) et chaque produit absorbé (role: "absorbed" : il revient avec ses annonces).

Puis le même appel sans dry_run. Comment chaque valeur est traitée :

Les produits restaurés sont renvoyés vers leurs canaux. L'annulation est elle-même une action (undo_of pointe vers l'originale) et une action ne peut être annulée qu'une fois.

Produits supprimés et leurs images

Un produit supprimé garde ses images pendant 30 jours : le restaurer dans ce délai les ramène. Après 30 jours, les images sont supprimées ; les données du produit peuvent toujours être restaurées, sans elles.

Confirmation en deux étapes

Les actions irréversibles (DELETE /listings/{id}, POST /listings/batch avec action: "delist", la déconnexion d'un compte de canal…) répondent d'abord 409. L'expédition d'une commande (POST /orders/{id}/fulfillment) ne demande rien : c'est l'étape automatisée d'un système d'expédition, et la marketplace est informée au plus une fois par commande.

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

Montrez confirmation.summary à la personne. Si elle est d'accord, renvoyez la même requête avec l'en-tête :

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

Nembol ne demande la confirmation qu'une fois la requête valide et l'action possible : votre application ne demande donc jamais à une personne de confirmer quelque chose qui ne peut pas avoir lieu :

• une entreprise, un import, une annonce ou une commande inconnus répondent 404 immédiatement ;
• un import déjà annulé ou une annonce qui ne peut pas être retirée répondent leur propre erreur immédiatement ;
• fermer une entreprise déjà fermée répond 200 avec l'entreprise telle qu'elle est : la fermeture est idempotente, rien à confirmer ;
• un retrait par batch ne compte dans son résumé que les annonces qui prendraient réellement fin ; quand aucune ne le ferait (inconnue, déjà retirée, non retirable), il répond avec les résultats par élément sans confirmation.

Le résumé nomme l'objet de l'action (le produit et la boutique pour un retrait, la boutique pour une déconnexion, l'entreprise pour une fermeture) : vous pouvez donc le montrer tel quel à la personne.

Le jeton fonctionne une seule fois, pour cette requête précise, pendant 10 minutes. Il est demandé pour les clés créées à partir du 2026-10-08 et pour chaque appel passé via le serveur MCP de Nembol (Nembol-Client: mcp).

Bonnes pratiques pour les agents

• Gardez le Nembol-Action-Id de ce que vous avez fait, pour pouvoir l'annuler précisément. N'« annulez jamais la dernière chose » à l'aveugle.
• Faites un aperçu avec dry_run et informez la personne des conflits au lieu de forcer les valeurs.
• Ne confirmez jamais à la place de la personne : une réponse confirmation_required est le moment de lui demander.

Dernière mise à jour le 20 octobre 2026