Deshacer y confirmaciones

Dos reglas mantienen segura una tienda cuando la gestiona una app (o un agente de IA):

1. Todo se puede rastrear y casi todo se puede deshacer. Cada cambio se registra en el historial de acciones con quién lo hizo y los valores exactos de antes y de después. Durante 30 días puedes deshacerlo.
2. Lo que no se puede deshacer pregunta antes. Retirar un anuncio, desconectar un canal, eliminar variantes, reembolsar un pedido de la storefront, deshacer una importación y cerrar una empresa usan todos la misma confirmación en dos pasos.

Encontrar lo que se hizo

Cada escritura responde con una cabecera Nembol-Action-Id, incluidas las irreversibles (enviar un pedido, retirar un anuncio, desconectar). Una repetición del mismo Idempotency-Key (Idempotent-Replayed: true) no es una escritura nueva: no registra ninguna acción y no lleva la cabecera. El historial 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"
    }
  ]
}

Se registran: creación, edición, eliminación y restauración de productos, cambios de variantes e inventario, ajustes de precio, lotes de productos, importaciones, configuración de las cuentas de canal (también cuando se cambia en el panel), publicaciones, retiradas de anuncios, envíos y conexiones/desconexiones. Se conservan 90 días. Para leerlas hace falta events:read o products:read.

Deshacer

Primero, la vista previa:

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

Una simulación nunca deshace nada: status es siempre simulated y outcome indica qué respondería el deshacer real (undone, partial, conflict, nothing_to_undo). Deshacer una unión muestra todos los productos: el superviviente (role: "survivor": los campos, variantes y anuncios que vuelven atrás) y cada absorbido (role: "absorbed": vuelve con sus anuncios).

Después, la misma llamada sin dry_run. Cómo se trata cada valor:

Los productos restaurados se vuelven a enviar a sus canales. El deshacer es a su vez una acción (undo_of apunta a la original) y una acción se puede deshacer una sola vez.

Productos eliminados y sus imágenes

Un producto eliminado conserva sus imágenes durante 30 días, así que restaurarlo en ese plazo las recupera. Pasados 30 días, las imágenes se eliminan; los datos del producto se pueden seguir restaurando, sin ellas.

Confirmación en dos pasos

Las acciones irreversibles (DELETE /listings/{id}, POST /listings/batch con action: "delist", desconectar una cuenta de canal…) responden primero 409. Enviar un pedido (POST /orders/{id}/fulfillment) no lo pide: es el paso automatizado de un sistema de gestión de envíos, y se avisa al marketplace como máximo una vez por pedido.

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

Muestra confirmation.summary a la persona. Si está de acuerdo, envía otra vez la misma solicitud con la cabecera:

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

Nembol pide la confirmación solo cuando la solicitud es válida y la acción es posible, así que tu app nunca pide a una persona que confirme algo que no puede ocurrir:

• una empresa, importación, anuncio o pedido desconocido responde 404 directamente;
• una importación ya deshecha o un anuncio que no se puede retirar responde su propio error directamente;
• cerrar una empresa que ya está cerrada responde 200 con la empresa tal como está: cerrar es idempotente, no hay nada que confirmar;
• una retirada en lote cuenta en su resumen solo los anuncios que realmente terminarían; cuando no terminaría ninguno (desconocidos, ya retirados, no retirables), responde con los resultados por elemento sin confirmación.

El resumen nombra aquello a lo que se refiere la acción (el producto y la tienda en una retirada, la tienda en una desconexión, la empresa en un cierre), así que puedes mostrárselo a la persona tal cual.

El token sirve una sola vez, para esa solicitud exacta, durante 10 minutos. Se pide para las claves creadas a partir del 2026-10-08 y para todas las llamadas hechas a través del servidor MCP de Nembol (Nembol-Client: mcp).

Buenas prácticas para agentes

• Guarda el Nembol-Action-Id de lo que hiciste, para poder deshacerlo con precisión. Nunca "deshagas lo último" a ciegas.
• Haz una vista previa con dry_run e informa a la persona de los conflictos en lugar de forzar valores.
• Nunca confirmes en nombre de la persona: una respuesta confirmation_required es el momento de preguntarle.

Última actualización el 20 de octubre de 2026