Referencia del SDK

Todo lo que un operador de eSIM existente necesita para poner sus sistemas sobre los rieles de AIMarket: los paquetes, la interfaz de proveedor, el proveedor HTTP para sistemas en cualquier lenguaje, el nodo vendedor, los webhooks, el contrato esim.*@v1 y la prueba de conformidad.

Otros documentos: resumen · incorporación · integraciones · guía del operador · guía para agentes

1. Paquetes

Node.js 20 o posterior. El SDK es ESM.

import {
  createNode, ed25519Signer, buildPaywall, fileStore,          // the seller node
  httpSupplier, esimAccessSupplier, airaloSupplier, esimGoSupplier, createEsimAccessClient,   // suppliers
  createWebhooks, verifyWebhook,                                // your systems
  validate, checkSeller,                                        // the contract
} from "@aimarket/esim-rails";

2. La interfaz de proveedor

Un proveedor es de donde salen las eSIM. La tienda y el nodo vendedor hablan con él solo mediante cinco métodos.

Plan     { id, name, countries: ["FR", …], kind?: "country" | "region" | "global", data_bytes, days,
           speed?, networks?, top_up?, unused_valid_days?, cost_usd }
Profile  { profileId, orderRef, activationCode, iccid?, qrCodeUrl?, installUrl?, apn?, expires?,
           state?, installed?, dataUsedBytes?, dataTotalBytes?, activated? }

Lanza SupplierError(code, message, { retryable }): retryable: true significa «ahora no» (una caída, un límite de peticiones); si no, «no» (un plan desconocido, un precio cambiado, un saldo vacío). Un «no» nunca se cobra al comprador.

Un proveedor en tu propio código:

import { SupplierError } from "@aimarket/esim-rails";

export const mySupplier = {
  async catalog() {
    return (await db.plans.active()).map((p) => ({
      id: p.sku, name: p.title, countries: p.countries, kind: p.region ? "region" : "country",
      data_bytes: p.gb * 1024 ** 3, days: p.days, cost_usd: p.cost }));
  },
  async order({ transactionId, planId, costUsd }) {
    const plan = await db.plans.get(planId);
    if (!plan || plan.cost !== costUsd) throw new SupplierError("price_changed", "the plan changed");
    const o = await db.orders.upsertByTransaction(transactionId, planId);   // the same id, the same order
    return { orderRef: o.id };
  },
  async profiles({ orderRef, profileId }) {
    const rows = orderRef ? await smdp.profilesOfOrder(orderRef) : [await smdp.profile(profileId)].filter(Boolean);
    return rows.map((r) => ({ profileId: r.id, orderRef: r.order, activationCode: r.lpa, iccid: r.iccid, state: r.state }));
  },
  async cancel({ profileId }) { await smdp.release(profileId); return true; },
  async balance() { return null; },                                       // your own stock: nothing to watch
};

Incluidos: esimAccessSupplier(createEsimAccessClient({ accessCode, secretKey })), airaloSupplier({ clientId, clientSecret }), esimGoSupplier({ apiKey }) y httpSupplier({ url, secret }) — configuración y advertencias en integraciones.

3. El proveedor HTTP: tu sistema, cualquier lenguaje

Ejecuta el kit con SUPPLIER=http, SUPPLIER_URL y SUPPLIER_SECRET_FILE, e implementa cinco endpoints en tu sistema. El contrato completo está en rails/spec/supplier-http.md.

Cada petición lleva X-Kit-Timestamp y X-Kit-Signature: v1=<hex HMAC-SHA256(secret, timestamp + "." + METHOD + " " + path + "." + body)>. Rechaza una firma incorrecta y todo lo que tenga más de cinco minutos.

sequenceDiagram
  participant K as El kit
  participant Y as Tu sistema
  K->>Y: GET /catalog (firmado)
  Y-->>K: planes con cost_usd
  K->>Y: POST /orders {transaction_id, plan_id, cost_usd}
  Y-->>K: {order_ref}   (el mismo transaction_id → el mismo order_ref)
  loop hasta que esté listo
    K->>Y: GET /profiles?order_ref=…
    Y-->>K: [] … luego [perfil con activation_code]
  end
  K->>Y: POST /profiles/{id}/cancel   (solo cuando un pago no se liquida)

Un receptor mínimo en Python (Flask), los dos endpoints que más importan:

import hashlib, hmac, json, time
from flask import Flask, request, jsonify, abort

SECRET = open("/run/secrets/kit_supplier").read().strip().encode()
app = Flask(__name__)

@app.before_request
def signed():
    ts, sig = request.headers.get("X-Kit-Timestamp", "0"), request.headers.get("X-Kit-Signature", "")
    path = request.full_path.rstrip("?")
    msg = f"{ts}.{request.method} {path}.".encode() + request.get_data()
    want = "v1=" + hmac.new(SECRET, msg, hashlib.sha256).hexdigest()
    if abs(time.time() * 1000 - int(ts)) > 300_000 or not hmac.compare_digest(want, sig):
        abort(401)

@app.get("/catalog")
def catalog():
    return jsonify(plans=[{"id": p.sku, "name": p.title, "countries": p.countries, "kind": "country",
                           "data_bytes": p.bytes, "days": p.days, "cost_usd": float(p.cost)} for p in active_plans()])

@app.post("/orders")
def orders():
    body = request.get_json()
    plan = find_plan(body["plan_id"])
    if plan is None or float(plan.cost) != body["cost_usd"]:
        return jsonify(error="price_changed"), 409
    order = upsert_order(body["transaction_id"], plan)          # idempotent by transaction_id
    return jsonify(order_ref=order.ref)

La referencia en JavaScript con los cinco endpoints: rails/examples/operator-backend.mjs.

4. El nodo vendedor

const node = createNode({
  supplier,                         // a supplier (section 2) or an eSIM Access client
  store: fileStore("/data/orders.json", fs),     // or your own {get, put}: order records, never codes
  secret: statusSecret,             // 16+ characters: the key of the buyers' status tokens
  signer: ed25519Signer(pem),       // your node's identity: signs every free answer
  publicUrl: "https://esim.example.com/agents",
  paywall,                          // buildPaywall(...) below, or null to quote without selling
  events,                           // createWebhooks(...) or { emit() {} }
  pricing: { marginPct: 100, minMarginUsd: 1 },
  sellerName: "My eSIM", productId: "esim-mine", demo: false,
});
const paywall = await buildPaywall({
  cdpKeyFile: "/run/secrets/cdp_api_key.json", payTo: "0xYourBaseAddress", publicUrl: "https://esim.example.com/agents",
  priceOf: (offerId) => node.priceOf(offerId), onSettleFailure: (p) => node.settleFailed(p),
});
node.app.listen(9490);

Rutas: POST /quote y POST /status (también /quote/invoke, /status/invoke para los hubs), POST /order (x402), GET /listing.json, GET /healthz. Las rutas gratuitas responden a cualquier página web (CORS); el pedido no.

5. Webhooks

Define WEBHOOK_URL y WEBHOOK_SECRET_FILE (16+ caracteres), o pasa createWebhooks({ url, secret }).

POST /hooks/esim HTTP/1.1
Content-Type: application/json
X-Kit-Event: order.delivered
X-Kit-Timestamp: 1765432100000
X-Kit-Signature: v1=5d41402abc4b2a76b9719d911017c592…

{"id": "3f1c…", "type": "order.delivered", "created_at": "2026-10-14T10:46:24.000Z",
 "data": {"order_id": "Qh3…", "status": "delivered", "offer_id": "JP_5_30", "offer_name": "Japan 5GB 30Days",
          "price_usd": "6.40", "cost_usd": 3.2, "method": "tron",
          "payment": {"ref": "tron:…", "payer": "T…", "units": "6400042"}, "esim_tran_no": "26101410460022",
          "error": null, "created_at": "2026-10-14T10:45:58.000Z"}}

La firma cubre timestamp + "." + body. La entrega es al menos una vez (tres intentos en medio minuto aproximadamente): elimina duplicados por id. Un evento nunca lleva un código de activación, un enlace QR ni un token de pedido.

import { verifyWebhook } from "@aimarket/esim-rails";
app.post("/hooks/esim", express.text({ type: "*/*" }), (req, res) => {
  const ok = verifyWebhook({ secret, timestamp: req.get("x-kit-timestamp"), signature: req.get("x-kit-signature"), body: req.body });
  if (!ok) return res.sendStatus(401);
  crm.record(JSON.parse(req.body));
  res.sendStatus(204);
});

def kit_event_ok(secret: bytes, timestamp: str, signature: str, body: bytes) -> bool:
    want = "v1=" + hmac.new(secret, timestamp.encode() + b"." + body, hashlib.sha256).hexdigest()
    return abs(time.time() * 1000 - int(timestamp)) < 300_000 and hmac.compare_digest(want, signature)

6. El contrato: esim.*@v1

Esquemas: rails/spec/esim-v1. Las respuestas gratuitas son {"success": true, "result": …} con X-Provider-Signature: Ed25519, base64, sobre el JSON canónico de {capability_id, product_id, input_sha256, result} (claves ordenadas, sin espacios, no ASCII tal cual; input_sha256 es el SHA-256 en hex de la entrada canónica). El pedido responde 402 con una cabecera x402 v2 PAYMENT-REQUIRED: esquema exact, red eip155:8453, USDC, el precio de la oferta con 6 decimales, tu dirección.

Valida en tus propias pruebas: import { validate } from "@aimarket/esim-rails"; validate("offer", o) devuelve [] o la lista de problemas.

7. La prueba de conformidad

Apúntala a cualquier nodo vendedor, el del kit o uno que hayas escrito:

npx esim-rails check https://esim.example.com/agents --country JP

Lo que imprimió para el nodo demo:

✓ listing.json — esim.quote@v1, esim.status@v1; order at https://modelmarket.dev/providers/esim/order
✓ esim.quote@v1 answer — 5 offers for JP, all valid
✓ cheapest first
✓ signature — Ed25519 over the request-bound canonical, key from listing.json
✓ bad input is a 400
✓ unknown eSIM is a 404 not_found
✓ unknown offer is a 400 before any price
⚠ x402 terms — a demo node: it sells nothing (demo_mode)
✓ CORS on the free routes

Conforms to esim.*@v1.

Solo llama a rutas gratuitas y pregunta al pedido su precio; nunca paga.

8. Entorno

9. Versiones

esim.*@v1 solo crece: pueden aparecer campos opcionales nuevos, los existentes conservan su significado. Un cambio que rompa a un cliente pasa a ser esim.*@v2, publicado junto a v1. El SDK sigue semver; el contrato del proveedor HTTP es la versión 1.