Auditoría de reembolsos

burnbound-mcp audit-refunds lee tus reembolsos de Stripe de los últimos días y los repasa con una política de Burnbound, por defecto el pack de reembolsos de soporte. Te dice cuántos reembolsos habría denegado Burnbound o retenido para aprobación, por qué regla y por cuánto. Se ejecuta en tu máquina, no necesita cuenta de Burnbound y no manda nada a Burnbound.

¿Qué sale de tu máquina?

• A Stripe: peticiones de solo lectura a api.stripe.com (GET /v1/refunds y GET /v1/customers/:id), con tu clave. Nadie más recibe nunca la clave.
• A Frankfurter: una petición sin tu clave para los tipos de referencia del día del Banco Central Europeo, solo cuando algún reembolso no está en USD y no pasaste --usd-rates.
• A Burnbound: nada. El informe se imprime o se escribe en el archivo que indiques.

La clave nunca se escribe en disco, nunca se imprime y nunca aparece en un error: cualquier mensaje que pudiera llevarla la enmascara.

¿Cómo se usa?

1. En Stripe, crea una clave restringida (Desarrolladores → Claves de API → Crear clave restringida) con Cargos, Reembolsos y Clientes en Lectura, y todo lo demás en Ninguno. También vale una clave del modo de prueba.
2. Ponla en el entorno sin que quede en el historial de tu shell y lanza la auditoría (Node.js 20 o posterior):

read -rs STRIPE_API_KEY && export STRIPE_API_KEY
npx -y @burnbound/mcp audit-refunds

La clave sale de STRIPE_API_KEY o de un archivo con --key-file <ruta>. Una clave pasada como argumento se rechaza, porque quedaría en el historial y en la lista de procesos. Una clave secreta del modo real (sk_…) se rechaza salvo que añadas --allow-secret-key: una clave restringida de solo lectura es más segura.

¿Qué opciones hay?

Códigos de salida: 0 el informe se escribió, 1 la auditoría no pudo ejecutarse (una clave rechazada, Stripe o los tipos inalcanzables), 2 uso incorrecto. Las respuestas 429 y 5xx de Stripe se reintentan hasta cinco veces, respetando Retry-After.

¿Qué comprueba?

El pack support-refunds tiene cuatro reglas, las mismas que puedes aplicar a un agente en Burnbound:

• tpl-refund-amount-approval: aprobación para un reembolso de más de 100 USD.
• tpl-refund-customer-monthly-limit: un reembolso por cliente y mes natural (UTC); el siguiente se deniega. Un reembolso denegado no gasta el mes.
• tpl-refund-old-charge-approval: aprobación para reembolsar un cargo de hace más de 30 días.
• tpl-refund-disputed-deny: ningún reembolso de un cargo disputado.

Cada reembolso se juzga con los hechos tal como eran cuando se hizo: lo ya reembolsado del cargo, la antigüedad del cliente y sus reembolsos de los 90 días anteriores. Se construyen igual que los construye el gateway de acciones para un reembolso real. Una denegación gana a una retención, y el informe nombra todas las reglas que coincidieron.

Con --rules, todas las reglas se repasan como aplicadas, aunque alguna esté marcada observe. Las reglas se escriben como en Conceptos.

¿Qué no ve?

• Solo las reglas. Los topes propios del agente (por reembolso, diario, hosts permitidos) necesitan su política y su gasto, que una ejecución local no tiene: no se evalúan.
• Tipos de hoy. Los importes en otras monedas se pasan a USD con los tipos de hoy, no con los del día de cada reembolso. Una moneda sin tipo no se evalúa, y el informe dice cuál.
• Reembolsos que movieron dinero. Los fallidos y los cancelados se dejan fuera; los pendientes cuentan.
• Historiales largos. Si --max-refunds corta la lectura, faltan los reembolsos más antiguos de la ventana y algunos historiales de clientes quedan cortos: el informe avisa de las dos cosas.
• Clientes. Una clave sin Clientes: Lectura sigue funcionando, pero la antigüedad de cada cliente es desconocida y las reglas sobre ella toman la rama restrictiva.

¿Cómo es el informe JSON?

--format json imprime un objeto con auditFormat: 1. Pueden añadirse campos; un cambio incompatible sube auditFormat.

{
  "auditFormat": 1,
  "window": {
    "from": "2026-08-05T00:00:00.000Z",
    "to": "2026-11-03T00:00:00.000Z",
    "days": 90
  },
  "policy": {
    "source": "pack",
    "packId": "support-refunds",
    "rules": [{ "id": "tpl-refund-disputed-deny", "action": "deny" }]
  },
  "rates": {
    "source": "ecb",
    "date": "2026-11-02",
    "usdPerUnit": { "EUR": "1.0834" }
  },
  "totals": { "refunds": 1284, "usd": "48210.4", "unpriced": 0 },
  "wouldDeny": {
    "refunds": 37,
    "usd": "2917.6",
    "byRule": [
      { "ruleId": "tpl-refund-disputed-deny", "refunds": 6, "usd": "1072.5" }
    ]
  },
  "wouldHold": { "refunds": 58, "usd": "9934.2", "byRule": [] },
  "topCustomers": [
    { "customer": "customer-8d21e0b7", "refunds": 9, "usd": "1240.3" }
  ],
  "affected": [
    {
      "at": "2026-10-14T09:12:00.000Z",
      "refundId": "refund-3f9a1c02",
      "chargeId": "charge-0b6e7d19",
      "customer": "customer-8d21e0b7",
      "amount": "149.00 EUR",
      "amountUsd": "161.43",
      "decision": "step_up",
      "rules": ["tpl-refund-amount-approval"]
    }
  ],
  "warnings": [
    {
      "code": "base_layer_not_evaluated",
      "message": "Only the custom rules were replayed. …"
    }
  ],
  "nextStep": {
    "message": "Turn these rules on in Burnbound: …",
    "url": "https://burnbound.dev/register"
  }
}

Los importes en USD son cadenas decimales exactas. affected lista los reembolsos que se habrían denegado (deny) o retenido (step_up), del más antiguo al más reciente. Los textos del informe están en inglés. Los códigos de aviso son base_layer_not_evaluated (siempre), history_truncated, currency_without_rate, max_refunds_reached, customers_unreadable, refunds_without_charge y refunds_not_counted.

¿Cómo activo las reglas?

Para parar esos reembolsos de verdad, regístrate, da a tu agente de soporte su clave de Burnbound y aplica el pack de reembolsos de soporte en las reglas del agente. Los reembolsos pasan entonces por el gateway de acciones que alojas tú: mira la herramienta stripe_refund en la referencia de las herramientas MCP.