Acciones de cambio

Define un cambio#

Usa una acción de cambio para actualizar un registro en tu propio sistema, por ejemplo para cancelar un pedido. Abre Agente → Acciones, configura el secreto de tu agente en Clientes con sesión iniciada y después añade una Acción de cambio: un nombre único, una descripción de cuándo usarla, un endpoint HTTPS público y entradas de texto declaradas. Un nombre como cancel_order se convierte en la herramienta del modelo change_cancel_order. Las ediciones existentes se guardan automáticamente; espera a que aparezca el indicador de guardado.

Mantén activada la opción Requiere cliente con sesión iniciada para los registros privados. Tu endpoint debe seguir autorizando el registro solicitado con respecto al ID de cliente verificado. Un nombre, un correo electrónico o un ID de pedido escrito en el chat no es una prueba de identidad. Si desactivas esta opción, customer puede ser null: permite únicamente los cambios apropiados para visitantes anónimos. Los pagos quedan fuera del alcance de esta función.

Elige la aprobación del propietario#

La confirmación del cliente es obligatoria en todos los modos:

Revisa las solicitudes en espera en Agente → Acciones → Aprobaciones. El propietario del sitio puede aprobar o rechazar. Si tienes vinculadas las alertas privadas de Telegram para el propietario, la alerta también incluye los botones Aprobar / Rechazar. Solo el chat privado del propietario vinculado puede usarlos; los toques caducados o repetidos no pueden ejecutar la acción de nuevo. La aprobación caduca 24 horas después de la confirmación del cliente. El cliente recibe el resultado, incluido un rechazo o una caducidad. Las ejecuciones recientes muestran el estado, las marcas de tiempo, la referencia y el ID del cliente.

Qué recibe tu endpoint#

No se envía ninguna solicitud cuando el modelo propone el cambio. Tras la confirmación del cliente y la aprobación del propietario, si se requiere, Make Agent Fast envía:

POST /agent/cancel-order HTTP/1.1
Content-Type: application/json
x-maf-timestamp: <unix-seconds>
x-maf-signature: v1=<64-lowercase-hex-characters>
x-maf-idempotency-key: c5c1d94b-e88f-4bf6-8023-2dcd1e7ac67b

{
  "version": 1,
  "action": "cancel_order",
  "runId": "c5c1d94b-e88f-4bf6-8023-2dcd1e7ac67b",
  "requestId": "c5c1d94b-e88f-4bf6-8023-2dcd1e7ac67b",
  "siteId": "YOUR_SITE_ID",
  "input": { "order_id": "A128" },
  "customer": { "id": "customer_123", "email": "customer@example.com" }
}

action no incluye el prefijo change_. Ambos ID y la cabecera de idempotencia se mantienen iguales en los reintentos. input contiene únicamente cadenas declaradas y sin espacios sobrantes; customer es null o el objeto verificado con id y, opcionalmente, email/name.

Usa el verificador de firma de las consultas: HMAC-SHA256 con el secreto de tu agente sobre "maf-webhook-v1:" + timestamp + "." + rawBody, en hexadecimal en minúsculas con el prefijo v1=. Verifica los bytes originales, la vigencia de la marca de tiempo, el sitio y la acción esperados, y la pertenencia del registro al cliente antes de escribir. Deduplica de forma atómica x-maf-idempotency-key junto con tu cambio y conserva el resultado. Una solicitud repetida debe devolver el resultado guardado sin modificar el registro de nuevo. El bloqueo de la plataforma no puede sustituir la deduplicación en tu sistema.

Devuelve un resultado#

Devuelve un JSON con código 2xx que incluya el campo obligatorio status (done, pending o failed) y, opcionalmente, message, reference y card:

{
  "status": "done",
  "message": "Order cancelled.",
  "reference": "A128",
  "card": {
    "kind": "status",
    "title": "Order A128",
    "fields": [{ "label": "Order", "value": "A128" }]
  }
}

La tarjeta de estado opcional requiere title y fields; kind: "status" es opcional. Admite status: { label, tone }, reference, asOf y link: { label, url }, como en las consultas. Los tonos son neutral, success, warning o danger; los enlaces deben ser URL HTTPS seguras. Los campos que no estén en el esquema se rechazan. Mantén el texto breve y sencillo. El status externo determina el resultado; el texto de la tarjeta no puede convertir un resultado pendiente en un éxito.

Usa done solo cuando el cambio esté completado, pending cuando aún se esté procesando y failed para un fallo conocido. Los tiempos de espera agotados, los errores de red, los 5xx y las respuestas no válidas se tratan como inciertos (unknown). La reconciliación reintenta tras un minuto y luego tras cinco minutos, con un máximo de tres intentos de ejecución y la misma clave; la programación de la cola puede retrasar estos tiempos. Un HTTP 4xx falla sin reintento. Si se agota la incertidumbre, la ejecución falla y se notifica al propietario, pero eso no demuestra que tu sistema no haya realizado ningún cambio. Investígalo antes de iniciar otra ejecución. pending no desencadena otra ejecución.

Envía un callback final firmado#

Cuando una ejecución pending o unknown se resuelva, envía mediante POST una respuesta final a https://makeagent.fast/api/agent/actions/RUN_ID/callback. Envía el mismo contrato de respuesta con status: "done" o "failed"; aquí no se acepta pending.

Contrato de callback actualizado el 2026-10-14: firma maf-callback-v1: + runId + : + timestamp + . + rawBody. Si el cuerpo incluye runId, debe coincidir con el ID de ejecución de la ruta; si no coincide, se devuelve 400. Las firmas de otra ejecución o del formato anterior sin vinculación devuelven 403.

import { createHmac } from "node:crypto";

const body = JSON.stringify({ status: "done", reference: "A128" });
const timestamp = String(Math.floor(Date.now() / 1000));
const signature = createHmac("sha256", agentSecret)
  .update(`maf-callback-v1:${runId}:${timestamp}.${body}`)
  .digest("hex");
const response = await fetch(
  `https://makeagent.fast/api/agent/actions/${encodeURIComponent(runId)}/callback`,
  {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "x-maf-timestamp": timestamp,
      "x-maf-signature": `v1=${signature}`,
    },
    body,
  },
);

Usa el secreto del agente almacenado en tu servidor y el ID de ejecución recibido en la solicitud original. El callback usa maf-callback-v1:, no el espacio de nombres de la solicitud saliente. El desfase de la marca de tiempo debe ser de cinco minutos como máximo. Las firmas no válidas devuelven 403; los cuerpos no válidos devuelven 400; una ejecución ya terminada o incompatible devuelve 409. Un callback repetido no sobrescribe el resultado final. Rota este secreto junto con la configuración de identidad y de firma de tu endpoint.

Confirmación del cliente y recibos#

El cliente revisa las entradas exactas y pulsa Confirmar o Cancelar en la propuesta. Una propuesta caduca a los 15 minutos; una nueva propuesta para la misma acción y conversación reemplaza a la anterior. La confirmación usa un token vinculado a esa ejecución, sitio y visitante. Escribir «sí» o hacer clic en una tarjeta de confirmación genérica no autoriza el cambio. Los botones del ensayo están inactivos y no llaman a tu endpoint.

En la web, el widget abierto consulta periódicamente los recibos no finalizados, al principio cada cinco segundos y después cada 30 segundos, durante un máximo de 24 horas. Un recibo puede mostrar los estados solicitado, esperando al propietario, en ejecución, pendiente, comprobando un resultado desconocido, completado, fallido, rechazado, cancelado o caducado. Solo done confirma la finalización.

Las propuestas en los canales funcionan solo en chats privados, nunca en grupos ni en canales. Los recibos diferidos usan el buzón de salida duradero: se admiten los mensajes directos normales de bots de Telegram; WhatsApp, Messenger, Instagram y Telegram Business requieren un mensaje entrante registrado en las últimas 24 horas, que se vuelve a comprobar en el momento del envío. El envío diferido no está disponible para las consultas de invitados de Telegram, Discord ni KakaoTalk. Las ventanas cerradas y las conexiones desactivadas pueden impedir la entrega; el historial de ejecuciones sigue registrando el resultado.

Límites y pruebas#

Usa un endpoint controlado para verificar la confirmación, la cancelación, la aprobación, el tiempo de espera agotado, la gestión de claves duplicadas y los callbacks finales. Comprueba sus registros, no solo el texto del recibo. El ensayo demuestra que no se realiza ninguna escritura externa; no es una prueba de ejecución del endpoint. Prueba cada canal privado previsto antes de confiar en los recibos.