Incorporación: rieles, casos de uso e interacción

Esta guía es para negocios de eSIM que ya venden — operadores, MVNO, revendedores, plataformas de viaje — y quieren a los agentes de IA como clientes: qué son los rieles de AIMarket, qué te da conectarte, cómo se comunican las partes y las cuatro formas de entrar, conservando tu plataforma.

Otros documentos: resumen · integraciones · referencia del SDK · guía del operador · guía para agentes

1. Qué son los rieles

AIMarket es una federación de hubs donde los agentes de IA encuentran capacidades y pagan por ellas. Funciona gracias a tres mecanismos, y el kit usa los tres:

El hub enruta el descubrimiento, nunca el dinero. No guarda fondos, no ve el código de activación y no cobra comisión por las ventas directas.

flowchart LR
  subgraph discovery["Descubrimiento (hub)"]
    M["Tu manifiesto<br/>firmado con la clave del nodo"] --> ADM["Comprobación de admisión<br/>esim.quote con un país real"]
    ADM --> L["Listado: esim.quote@v1, esim.status@v1"]
    L --> S["market_search de los agentes<br/>en cualquier hub de la federación"]
  end
  subgraph trade["Venta (directa)"]
    Q["oferta — gratis, firmada"] --> O["pedido — 402, x402 USDC"]
    O --> D["entrega — código de activación"]
    D --> ST["estado — gratis, con token"]
  end
  S --> Q

2. Por qué conectarse

• Un canal de ventas nuevo que no necesita que le vendas. Los agentes comparan las ofertas de todos los vendedores por precio, datos y cobertura. Un buen precio se encuentra sin marketing.
• Sin integración por cada plataforma de agentes. Un contrato, esim.*@v1, es lo que cada agente usa con cada vendedor.
• Dinero sin procesador. Los USDC en Base llegan a tu monedero cuando la eSIM se entrega. Sin contracargos: un pago se liquida solo tras la entrega, y una liquidación fallida cancela la eSIM.
• Tus sistemas siguen siendo tuyos. El kit llama a tu proveedor o sistema de aprovisionamiento con cinco endpoints e informa a tu CRM y facturación de cada venta con webhooks firmados.
• Las mismas ofertas para personas. La tienda opcional vende el mismo catálogo con el mismo margen, en cinco idiomas, en diez redes de pago.

3. Casos de uso

3.1 Un agente de viajes reserva un viaje y añade datos

sequenceDiagram
  participant U as Viajero
  participant Ag as Agente de viajes (IA)
  participant Hub as Hub de AIMarket
  participant N as Nodo vendedor
  U->>Ag: "Tokio, 12 días, necesito datos"
  Ag->>Hub: market_search "eSIM Japan"
  Hub-->>Ag: vendedores con esim.quote@v1
  Ag->>N: quote {country: JP, min_gb: 5, min_days: 12}
  N-->>Ag: 3 ofertas, firmadas
  Ag->>U: "5 GB, 15 días, $6.40 — ¿compro?"
  U->>Ag: sí
  Ag->>N: pedido + x402 USDC
  N-->>Ag: código de activación, QR, enlace de instalación
  Ag->>U: código QR y pasos de instalación

3.2 Un revendedor existente añade el canal de agentes

Ya vendes eSIM en tu propio sitio, de tu propio suministro. Ejecutas el kit con SUPPLIER=http e implementas cinco endpoints en tu plataforma. Tu tienda sigue como está; la del kit puede quedarse apagada. Cada venta a un agente llega a tus sistemas como webhook agent_order.delivered y a tu monedero como USDC.

3.3 Un MVNO o una teleco expone sus propios perfiles

Tu SM-DP+ o tu API de aprovisionamiento crea los perfiles. POST /orders del proveedor HTTP reserva uno, GET /profiles devuelve su código de activación cuando está listo y cancel devuelve uno sin usar al stock. El kit añade el pago x402, las firmas y la federación.

3.4 Un asistente de viajes de empresa o de gastos

Un asistente que reserva viajes para empleados compra una eSIM por viaje, guarda esim_tran_no y status_token, y consulta esim.status antes de que el empleado vuelva: datos usados, días restantes. Finanzas concilia cada pago USDC con los eventos de webhook.

3.5 Una superapp o una mini app de Telegram

Una app centrada en el monedero (TON, Telegram) llama al nodo vendedor desde su backend: oferta, luego pedido con x402, o envía a sus usuarios a la tienda que acepta USDT en TON. El mismo nodo sirve a ambos.

3.6 Un operador nuevo con solo una cuenta mayorista

Una cuenta de eSIM Access, un servidor y un dominio: docker compose up da el nodo para agentes, el nodo de federación y la tienda. Así funciona esim-shop.modelmarket.dev, en modo demo.

4. Las cuatro formas de entrar

flowchart TB
  subgraph A["A · kit completo"]
    A1["Caddy"] --> A2["store"] & A3["rails"] & A4["node"]
    A2 & A3 --> A5["eSIM Access"]
  end
  subgraph B["B · proveedor HTTP"]
    B1["Caddy"] --> B2["store (opcional)"] & B3["rails"] & B4["node"]
    B2 & B3 -->|"HTTP firmado"| B5["Tu sistema<br/>/catalog /orders /profiles /balance"]
  end
  subgraph C["C · SDK"]
    C1["Tu servicio"] --> C2["createNode()"]
    C2 --> C3["tu objeto proveedor"]
  end
  subgraph D["D · contrato"]
    D1["Tu API para agentes<br/>cualquier lenguaje"] --> D2["esim-rails check"]
  end

Después, cada camino se anuncia a un hub de la misma forma (mira la guía del operador, sección 9): genera node.toml, arranca aimarket node, ejecuta aimarket doctor y luego aimarket node knock.

5. Cómo se comunican las partes

5.1 El pedido de un agente, de principio a fin

sequenceDiagram
  autonumber
  participant Ag as Agente
  participant N as Nodo vendedor
  participant F as Facilitador x402
  participant S as Proveedor
  participant CRM as Tus sistemas
  Ag->>N: POST /order {offer_id}
  N-->>Ag: 402 + PAYMENT-REQUIRED (exact, USDC, eip155:8453, precio, payTo)
  Ag->>N: POST /order + PAYMENT-SIGNATURE
  N->>F: verificar la autorización
  N->>S: pedido {transaction_id = hash(pagador, nonce), plan, coste}
  S-->>N: order_ref
  loop hasta que el perfil esté listo (≤ 45 s)
    N->>S: profiles {order_ref}
  end
  N->>F: liquidar
  F-->>N: liquidado (USDC en tu monedero)
  N-->>Ag: 200, entrega
  N-)CRM: agent_order.delivered (webhook firmado)

Si el perfil no está listo en 45 segundos, el agente recibe 503 allocation_pending y no se liquida nada; el mismo pago enviado de nuevo encuentra el mismo pedido. Si la liquidación falla, el nodo cancela el perfil y envía agent_order.cancelled.

5.2 Un pedido en la tienda

stateDiagram-v2
  [*] --> awaiting_payment: pedido creado (precio fijo 20 min)
  awaiting_payment --> delivered: pago encontrado, eSIM comprada
  awaiting_payment --> refund_due: pagado, el proveedor rechazó
  awaiting_payment --> underpaid: menos que el precio
  awaiting_payment --> expired: nada en 24 h
  delivered --> [*]
  refund_due --> [*]: tú reembolsas
  underpaid --> [*]: tú reembolsas o completas
  expired --> [*]

Cada cambio de estado es un webhook order.<status> a tus sistemas.

5.3 A dónde va el dinero

flowchart LR
  P["Viajero"] -->|"USDT · USDC · TON<br/>10 redes"| W["Tus monederos"]
  AG["Agente"] -->|"USDC en Base, x402"| W
  W -->|"tú recargas"| SUP["Tu saldo en el proveedor"]
  SUP -->|"coste por eSIM"| K["perfiles"]
  HUB["Hub de AIMarket"] -.->|"sin dinero, sin comisión"| W

5.4 Quién ve qué

6. Conectar tus sistemas

La referencia del SDK tiene cada endpoint, cuerpo y firma, con código.

7. Lista de incorporación para un operador existente

1. Lee la guía para agentes para ver qué llamarán los agentes.
2. Elige un camino (sección 4). Para B, implementa los cinco endpoints; rails/examples/operator-backend.mjs es una referencia.
3. Ejecuta el kit con DEMO_MODE=1 y tu proveedor; comprueba que el catálogo carga (/agents/healthz).
4. Apunta WEBHOOK_URL a un endpoint de prueba de tu CRM; haz un pedido de prueba (guía del operador, sección 10).
5. Ejecuta esim-rails check https://<tu dominio>/agents --country <un país que vendas> hasta que cada línea sea ✓.
6. Arranca el nodo de federación y anúncialo a un hub. Búscate con market_search.
7. Pon DEMO_MODE=0. Ya vendes a agentes.

8. Preguntas

¿Los hubs cobran comisión? No en las ventas directas: el agente paga a tu nodo por x402.

¿Puedo mantener mi tienda y mis precios? Sí. Camino B o C, con la tienda del kit apagada, o encendida con tu margen.

¿Qué agentes pueden comprar? Cualquier cliente que hable x402 v2 con USDC en Base, y cualquier cliente MCP conectado a un hub de AIMarket para el descubrimiento.

¿Y si el hub cae? Tu nodo sigue vendiendo a los agentes que conocen su URL; el descubrimiento vuelve cuando vuelve el hub.

¿Puedo vender pases por día o recargas? No en v1: esim.*@v1 vende planes fijos de un tamaño y una duración dados.

¿Necesito una empresa? El comerciante eres tú: tus condiciones, tus reembolsos, tus impuestos. Mira la guía del operador, sección 13.