Todo lo que un equipo de ingeniería necesita para planificar y lanzar una integración de eSIM: los cuatro bloques básicos que comparten todas las API de eSIM, cómo funciona la autenticación firmada, la diferencia entre aprovisionamiento síncrono y por webhook, qué evaluar antes de elegir un proveedor y los errores que solo aparecen en producción.
Toda integración de API de eSIM, sea cual sea el proveedor, se descompone en los mismos cuatro bloques. Dimensiona tu desarrollo a partir de ellos:
Los paquetes que puedes vender, con tus precios mayoristas. Guárdalo en caché, pero actualízalo periódicamente porque las tarifas de los operadores cambian. Filtra por país para construir páginas de destino.
Un POST autenticado convierte un código de paquete en una eSIM aprovisionada, descontada del saldo de tu cuenta. La respuesta incluye el paquete de instalación completo: imagen del código QR, enlace universal de Apple para instalar con un toque y la cadena LPA en bruto.
Consultas de consumo («80 % usado, ¿recargar?»), paquetes y pedidos de recarga, estado, suspensión/cancelación y eventos de red. Este bloque convierte una tienda de un solo uso en un producto con retención.
Peticiones firmadas, consultas de saldo, gestión de webhooks y límites de peticiones. Aburrido hasta que deja de serlo: la mayoría de las incidencias en producción viven aquí (ver los errores más abajo).
Un pedido de eSIM gasta dinero real de tu saldo, así que las API serias firman cada petición en lugar de confiar en una cabecera con clave estática. El esquema de eSIMfly es HMAC-SHA256: cuatro cabeceras (código de acceso, identificador de petición único, marca de tiempo en milisegundos y una firma sobre timestamp + requestId + accessCode + requestBody). Las peticiones con más de 5 minutos se rechazan, lo que elimina los ataques de repetición.
const BASE_URL = 'https://esimfly.net';
const ACCESS_CODE = process.env.ESIMFLY_ACCESS_CODE; // esf_...
const SECRET_KEY = process.env.ESIMFLY_SECRET_KEY; // sk_...
function hmacHeaders(requestBody = '') {
const timestamp = Date.now().toString();
const requestId = uuidv4();
// signData = Timestamp + RequestID + AccessCode + RequestBody
const signData = timestamp + requestId + ACCESS_CODE + requestBody;
const signature = crypto
.createHmac('sha256', SECRET_KEY)
.update(signData)
.digest('hex')
.toUpperCase();
return {
'RT-AccessCode': ACCESS_CODE,
'RT-RequestID': requestId,
'RT-Timestamp': timestamp,
'RT-Signature': signature,
'Content-Type': 'application/json'
};
}Las credenciales se obtienen en Panel de empresa → Ajustes → Claves de API. Guarda la clave secreta solo en el servidor: nunca la incluyas en una app móvil ni en el código del navegador.
El flujo mínimo son dos llamadas: catálogo y después pedido. Un prototipo que vende una eSIM real y muestra su código QR se construye en un día:
// The minimal happy path — two calls from catalog to installed eSIM
// 1. What can I sell, and at what wholesale price?
const catalog = await fetch(
BASE_URL + '/api/v1/business/esims/packages?country=TR',
{ headers: hmacHeaders() }
).then(r => r.json());
// 2. Buy one — returns the full installation payload
const order = await fetch(BASE_URL + '/api/v1/business/esims/order', {
method: 'POST',
headers: hmacHeaders(body),
body // { packageCode, quantity: 1 }
}).then(r => r.json());
// order.data: { orderReference, iccid, qrCodeUrl,
// lpaString, appleInstallUrl, newBalance, ... }La decisión de arquitectura importante es aprovisionamiento síncrono frente a asíncrono. La mayoría de los proveedores de eSIMfly aprovisionan de forma síncrona: la respuesta del pedido ya contiene la eSIM. Una minoría (KDDI en Japón, por ejemplo) devuelve pending_details y entrega la eSIM mediante un webhook firmado unos minutos después. Diseña tu flujo de pedido como «muestra la eSIM si viene en la respuesta; si no, muestra un estado de “preparando” y termina desde el webhook», y ambos casos quedan cubiertos.
Para el desarrollo completo (interfaz del catálogo, pedidos, entrega del QR) sigue el tutorial de tienda con Node.js (~30 min) y después recargas, seguimiento de consumo y webhooks.
Preguntas que conviene hacer a cualquier proveedor de API de eSIM antes de comprometer volumen, con las respuestas de eSIMfly por transparencia:
No solo cuántos países, sino qué redes locales hay en cada uno y si los planes cambian entre varias redes. eSIMfly: 200 países, más de 450 redes.
Cada operador asíncrono añade complejidad de webhooks a tu flujo. eSIMfly: la mayoría de los proveedores son síncronos; los asíncronos (p. ej. KDDI) se entregan mediante webhook firmado.
Quieres código QR + enlace universal de Apple + cadena LPA en bruto en una sola respuesta; cualquier cosa menos empeora la experiencia de instalación. eSIMfly: los tres.
Consulta de consumo, catálogo de recargas por ICCID, suspensión/cancelación, eventos de red. Sin datos de consumo no puedes generar ingresos por recargas.
Las peticiones firmadas (HMAC) superan a las claves estáticas en una API que gasta dinero. eSIMfly: HMAC-SHA256, 1000 peticiones/hora, ventana de 5 minutos para la marca de tiempo.
Si la documentación no incluye ejemplos para copiar y pegar en tu lenguaje, el tiempo de integración se duplica. eSIMfly: ejemplos en Node.js, Python y PHP, más un playground interactivo.
Las marcas de tiempo firmadas con más de 5 minutos se rechazan. Un servidor con el reloj desviado produce errores 401 intermitentes que parecen fallos aleatorios. Usa NTP y crea alertas sobre la tasa de fallos de autenticación.
Los usuarios borran correos y cambian de teléfono. Guarda orderReference, ICCID, QR y cadena LPA en tu sistema para poder reenviar la eSIM más adelante: volver a pedir cuesta dinero, volver a mostrar es gratis.
Los pedidos se descuentan de tu saldo prepago y fallan limpiamente si es insuficiente, pero eso sigue siendo una compra fallida para el cliente. Vigila el campo newBalance en cada pedido y avisa mucho antes de que se agote.
Los precios mayoristas cambian con las tarifas de los operadores. Un catálogo en caché desactualizado significa vender al coste de ayer. Guarda en caché, pero actualiza según un calendario y antes de grandes campañas.
Consultar el consumo de cada eSIM cada minuto agota rápido tu presupuesto de 1000 peticiones/hora a escala. Consulta cuando el usuario abre la app, programa comprobaciones en segundo plano con poca frecuencia y deja que los webhooks lleven los eventos asíncronos.
Cuatro bloques básicos: un catálogo de paquetes (qué puedes vender, con precios mayoristas), un endpoint de pedidos (convierte un código de paquete en una eSIM aprovisionada), la experiencia de entrega (código QR, enlaces de instalación con un toque y la cadena LPA en bruto) y la gestión del ciclo de vida (consultas de consumo, recargas, suspensión/cancelación, webhooks). Una tienda mínima solo necesita los tres primeros y se puede construir en un día; las funciones de ciclo de vida la convierten en un producto real.
Un prototipo funcional (autenticarse, obtener el catálogo, crear un pedido y mostrar el código QR) suele ser un trabajo de un día (el tutorial de Node.js de eSIMfly lo hace en unos 30 minutos sin SDK). Prepararlo para producción (webhooks, control del saldo, reenvío de eSIM almacenadas, gestión de errores) suele añadir unos días.
Las API de eSIM serias usan peticiones firmadas en lugar de una simple clave de API. eSIMfly usa HMAC-SHA256: cada petición lleva un código de acceso, un identificador de petición único, una marca de tiempo y una firma calculada sobre marca de tiempo + identificador + código de acceso + cuerpo con tu clave secreta. Las peticiones con más de 5 minutos se rechazan, lo que bloquea los ataques de repetición.
La mayoría de los proveedores de eSIMfly aprovisionan de forma síncrona: la respuesta del pedido ya contiene el código QR, así que el flujo principal no necesita webhook. Los webhooks importan para la minoría de operadores que aprovisionan de forma asíncrona (KDDI en Japón tarda unos minutos) y para evitar bucles de consulta de consumo a gran escala. Buena regla: lanza con el flujo síncrono y añade webhooks antes de escalar.
Cobertura (países Y qué redes locales), modelo de precios mayoristas y soporte de recargas, qué proporción de pedidos se aprovisiona de forma síncrona, integridad del paquete de entrega (QR + enlace universal de Apple + LPA en bruto), seguridad de la autenticación, límites de peticiones, endpoints de consumo y ciclo de vida, y si la documentación incluye ejemplos ejecutables. Prueba el sandbox con tu caso de uso real antes de comprometer volumen.
Crea una cuenta de empresa en eSIMfly y genera las credenciales de API (código de acceso + clave secreta) en Panel de empresa → Ajustes → Claves de API. La cobertura abarca 200 países y más de 450 redes, con un límite de 1000 peticiones por hora. Los niveles mayoristas dependen del volumen: contacta con ventas para conocer las tarifas.
Referencia completa de endpoints, ejemplos en Python y PHP y un playground interactivo en la documentación, o empieza por la visión general de la API y consigue tus claves.