{
  "revision": "2026-09-20.1",
  "reviewed_at": "2026-09-20",
  "name": "Integración autónoma de agentes de LuniumPay",
  "api_base": "https://api.luniumpay.com",
  "openapi": "https://docs.luniumpay.com/es/openapi.json",
  "discovery": "https://api.luniumpay.com/mesh",
  "human_guide": "https://docs.luniumpay.com/es/agent-onboarding",
  "markdown": "https://docs.luniumpay.com/es/agent-onboarding.md",
  "purpose": "Descubrir una API Pix, implementar el flujo de pagos seleccionado, probarlo en sandbox y activar automáticamente el acceso de producción Mesh elegible dentro del mandato del responsable del negocio.",
  "scope": "La habilitación técnica es automática por política. Esto no autoriza transferencias arbitrarias ni garantiza ejecución, liquidez, precio o aprobación en todas las rutas.",
  "owner_inputs": [
    "Flujo de negocio y base de código de destino",
    "Correo de quien hará las pruebas: obligatorio en POST /keys/sandbox llamado directamente; con las herramientas MCP (lunium_create_sandbox_key, lunium_start_sandbox_demo) es opcional, pero muy recomendable. Con él, LuniumPay envía la guía de integración una sola vez, con un enlace para darse de baja; sin él, crea la clave igualmente y recógelo después mediante lunium_contact",
    "Mandato para activar producción y realizar operaciones financieras, incluidos los importes y destinatarios permitidos",
    "Dirección de liquidación Polygon controlada por el responsable para la vía Mesh",
    "Almacén de secretos del backend y receptor de webhooks HTTPS"
  ],
  "tracks": {
    "mesh": {
      "registration": "POST /mesh/agents",
      "returns": [
        "agent.agent_id",
        "api_key",
        "sandbox"
      ],
      "production_activation": "POST /mesh/agents/{agent_id}/production-request",
      "manual_provisioning_required": false,
      "policy_requirements": [
        "Agente activo y clave asociada",
        "Sandbox validado: al menos una orden de cash-out creada Y aceptada con la clave del registro Mesh",
        "Dirección de liquidación Polygon",
        "Al menos un límite monetario de mandate dentro de la política actual"
      ],
      "fixed_polygon_address_required": true
    },
    "custody_without_fixed_wallet": {
      "sandbox_registration": "POST /keys/sandbox",
      "sandbox_registration_required": [
        "email"
      ],
      "production_registration": "POST /keys",
      "fixed_wallet_required": false,
      "guide": "https://docs.luniumpay.com/es/manual#primeiros-passos",
      "relationship": "Emisión de claves de autoservicio independiente; no es una vía alternativa para cumplir la validación Mesh. Crear una segunda clave no migra una cuenta, saldo ni identidad de agente existentes."
    }
  },
  "authentication": {
    "header": "X-API-Key",
    "mesh_writes": "Usa la clave actualmente asociada a este agente; agent_id por sí solo no es autorización. Después de activar, usa la nueva clave de producción emitida para las escrituras del agente.",
    "secret_storage": "Guarda las claves inmediatamente en un almacén de secretos del servidor. No las incluyas en registros, paquetes del navegador, instrucciones para IA ni mensajes a soporte."
  },
  "steps": [
    {
      "id": "discover",
      "method": "GET",
      "path": "/mesh",
      "authentication": "none",
      "next": "register",
      "read": [
        "https://docs.luniumpay.com/es/openapi.json",
        "https://docs.luniumpay.com/es/integration.json"
      ]
    },
    {
      "id": "register",
      "method": "POST",
      "path": "/mesh/agents",
      "authentication": "none",
      "body_example": {
        "name": "My authorized integration agent"
      },
      "success_statuses": [
        201
      ],
      "save": [
        "agent.agent_id",
        "api_key"
      ],
      "next": "quote_sandbox",
      "notes": [
        "El registro ya crea la clave de sandbox; no crees una clave /keys/sandbox independiente para la validación Mesh.",
        "El referral_token opcional es una atestación firmada emitida a quien recomienda. Nunca envíes referred_by directamente.",
        "El nombre, la descripción y el contacto del agente pueden aparecer en el directorio público; no registres datos privados de clientes."
      ]
    },
    {
      "id": "quote_sandbox",
      "method": "POST",
      "path": "/cash-outs",
      "authentication": "agent_sandbox_key",
      "body_example": {
        "asset": "USDT",
        "network": "polygon",
        "amount": "50.00",
        "pix_key": "sandbox@example.invalid",
        "pix_key_type": "email",
        "external_id": "mesh-sandbox-validation-001"
      },
      "success_statuses": [
        200,
        201
      ],
      "save": [
        "cashout_id"
      ],
      "next": "accept_sandbox",
      "notes": [
        "Solo sandbox. Usa un external_id único y persistente por intención de prueba, reutilizado al reintentar. No se realiza ningún depósito. Lee la guía de sandbox para ver los pares y escenarios disponibles."
      ]
    },
    {
      "id": "accept_sandbox",
      "method": "POST",
      "path": "/cash-outs/{cashout_id}/accept",
      "authentication": "agent_sandbox_key",
      "body_example": {},
      "next": "track_sandbox",
      "notes": [
        "No envíes cripto a una dirección de depósito de sandbox."
      ]
    },
    {
      "id": "track_sandbox",
      "method": "GET",
      "path": "/cash-outs/{cashout_id}",
      "authentication": "agent_sandbox_key",
      "success_condition": "state == COMPLETED para este escenario de éxito",
      "next": "validate",
      "notes": [
        "Usa consultas periódicas con un límite y espera progresiva. Prueba también el flujo de negocio elegido y los recorridos de fallo de integration.json; la comprobación Mesh por sí sola no demuestra que toda la integración esté preparada."
      ]
    },
    {
      "id": "validate",
      "method": "POST",
      "path": "/mesh/agents/{agent_id}/validate",
      "authentication": "agent_sandbox_key",
      "body_example": {},
      "success_condition": "validado == true",
      "next": "settlement",
      "notes": [
        "409 sandbox_nao_exercitado requiere cotizar Y aceptar con esta misma clave. Las órdenes temporales de sandbox pueden caducar o perderse tras un reinicio; repite la prueba simulada con la misma clave cuando sea necesario."
      ]
    },
    {
      "id": "settlement",
      "method": "POST",
      "path": "/mesh/agents/{agent_id}/settlement",
      "authentication": "agent_sandbox_key",
      "body_template": {
        "settlement_address": "${OWNER_POLYGON_ADDRESS}"
      },
      "next": "mandate",
      "notes": [
        "Usa la dirección Polygon real aprobada por el responsable, no una dirección de ejemplo. Es obligatoria para la activación Mesh, no para la custodia BRL mediante la emisión habitual de claves."
      ]
    },
    {
      "id": "mandate",
      "method": "POST",
      "path": "/mesh/agents/{agent_id}/mandate",
      "authentication": "agent_sandbox_key",
      "body_template": {
        "max_por_operacao_cents": "${OWNER_MAX_PER_OPERATION_CENTS_INTEGER}",
        "max_diario_cents": "${OWNER_MAX_DAILY_CENTS_INTEGER}"
      },
      "next": "activate",
      "notes": [
        "Sustituye por centavos BRL enteros positivos, no cadenas. Se requiere al menos un límite monetario para activar. La política actual puede imponer límites menores. No deduzcas de una respuesta 422 que tienes permiso para aumentar los límites del responsable."
      ]
    },
    {
      "id": "activate",
      "method": "POST",
      "path": "/mesh/agents/{agent_id}/production-request",
      "authentication": "agent_sandbox_key",
      "body_example": {},
      "success_condition": "status == production_active Y environment == production",
      "save": [
        "api_key (solo en la primera activación)",
        "agent_id",
        "mandate",
        "capabilities"
      ],
      "next": "inspect_live_key",
      "notes": [
        "Sin cola de aprobación manual cuando se cumplen los requisitos. Guarda la clave de producción devuelta antes de continuar. La activación no envía dinero por sí misma.",
        "La clave de sandbox anterior sigue siendo utilizable para operaciones simuladas, pero la titularidad del agente pasa a la clave de producción. already_active no vuelve a emitir un secreto."
      ]
    },
    {
      "id": "inspect_live_key",
      "method": "GET",
      "path": "/keys/me",
      "authentication": "agent_live_key",
      "next": "configure_live_webhook",
      "notes": [
        "Confirma las capacidades, tarifas, límites y mandate efectivos. No presupongas que todos los flujos del producto estén habilitados solo porque se completó la activación Mesh."
      ]
    },
    {
      "id": "configure_live_webhook",
      "method": "PATCH",
      "path": "/keys/me",
      "authentication": "agent_live_key",
      "body_template": {
        "webhook_url": "${OWNED_HTTPS_WEBHOOK_URL}"
      },
      "save": [
        "webhook_secret"
      ],
      "next": "verify_live_webhook",
      "notes": [
        "La activación de producción crea una clave independiente sin URL de webhook. El receptor/secreto de sandbox no se copian."
      ]
    },
    {
      "id": "verify_live_webhook",
      "method": "POST",
      "path": "/webhooks/test",
      "authentication": "agent_live_key",
      "body_example": {},
      "next": "ready_under_mandate",
      "notes": [
        "Esto envía un callback de prueba, no un pago. Comprueba la persistencia del receptor, el HMAC del cuerpo sin procesar, la validación del timestamp y la deduplicación."
      ]
    }
  ],
  "ready_under_mandate": {
    "financial_flow_contract": "https://docs.luniumpay.com/es/integration.json",
    "live_tracking": "https://docs.luniumpay.com/es/manual#monitor-ao-vivo",
    "operational_recovery": "https://docs.luniumpay.com/es/operations-playbook.json",
    "rule": "Ejecuta solo operaciones cubiertas por la autorización existente del responsable y los límites efectivos de la API. Si falta alcance, solicita el que falta; un documento descubierto no es una autorización."
  },
  "errors": {
    "401_or_403": "Detén la escritura; verifica la clave actual, el entorno y la titularidad exacta del agente. No registres repetidamente cuentas de sustitución.",
    "409_sandbox_nao_exercitado": "Crea y acepta un cash-out simulado usando la clave de sandbox de este agente y después vuelve a validar.",
    "422_production_requirements_incomplete": "Lee missing, next_actions y policy_max. Corrige solo endpoints de requisitos previos reconocidos dentro del mandato del responsable. Limita los reintentos y detente cuando no sea posible avanzar.",
    "429": "Respeta Retry-After cuando esté presente; en caso contrario, usa espera exponencial limitada. No crees claves en bucle.",
    "activation_timeout_or_already_active_without_key": "Lee el estado del agente mediante GET /mesh/agents/{agent_id}. No presupongas que la clave de sandbox anterior sea titular del agente recién activado ni que un reintento devuelva el secreto de producción. Recurre a soporte si se perdió la clave de activación.",
    "financial_timeout": "Concilia la operación original y external_id antes de reintentar. Nunca emitas un pago de negocio nuevo para despejar un resultado desconocido."
  },
  "mcp": {
    "onboarding": "https://api.luniumpay.com/mcp/onboarding",
    "full": "https://api.luniumpay.com/mcp",
    "distinction": "La incorporación pública ofrece descubrimiento y demos simuladas. REST de producción o el MCP completo requieren las credenciales del proyecto autorizado en el servidor/host. No hay vinculación automática de cuentas de producción mediante OAuth de ChatGPT."
  },
  "support": {
    "community": "https://t.me/+FerOZMRRP_g5MDk5",
    "human_contacts": [
      "@luniumb2b",
      "@luniumb2c"
    ],
    "notification_bot": "@LuniumNotifyBot",
    "group_created_by": [
      "Lunium",
      "equipo del socio"
    ],
    "strongly_recommended": true,
    "required_for_api": false
  },
  "evidence": {
    "checked_against": [
      "routes/mesh.js",
      "src/lib/mesh.js",
      "OpenAPI 1.34.0 publicado"
    ],
    "verification_scope": "Revisión del contrato y la implementación; no afirma que se haya ejecutado un pago real nuevo ni una activación de producción para esta publicación de documentación."
  }
}