Lista de verificación de la API de eSIM (2026): 12 funciones que una API de eSIM para viajes debe tener — y cómo probar cada una

Conectar una API de eSIM a tu aplicación, plataforma de viajes o motor de reservas no es difícil. Lo difícil es descubrir, después del lanzamiento, que la API realiza cargos dobles tras un tiempo de espera (timeout), que no puede avisarte cuando a un cliente se le acaban los datos, o que no te ofrece ninguna forma de probar fallos.

Esta lista de verificación cubre las 12 funciones que importan en producción y, para cada una, cómo probarla antes de contratarte. Utilizamos la API de TripoSIM Partner como ejemplo práctico, pero puedes usar la misma lista para comparar cualquier proveedor.

1. Autenticación de token segura

Qué buscar: Credenciales de cliente OAuth 2.0: intercambias un ID de cliente y un secreto por un token de acceso de corta duración. Los secretos nunca viajan con cada solicitud.

Cómo probarlo: solicita un token y luego comprueba que caduca. En la API de TripoSIM, POST /auth/token devuelve un token de acceso válido por 15 minutos. Asegúrate de que tu código lo refresque automáticamente antes de que expire.

2. Claves de idempotencia (sin cargos dobles)

Qué buscar: un encabezado Idempotency-Key en cada pedido y recarga. Si tu solicitud tiene un timeout y reintentas con la misma clave, la API debe devolver el resultado original en lugar de crear una segunda eSIM pagada.

Cómo probarlo: envía el mismo pedido dos veces con la misma clave y confirma que recibes un solo pedido. Luego, envía la misma clave con un cuerpo diferente; una buena API lo rechazará. TripoSIM requiere la clave en pedidos y recargas de producción y devuelve 409 IDEMPOTENCY_KEY_REUSED si se reutiliza una clave con una solicitud diferente.

3. Cotizaciones que bloquean el precio

Qué buscar: una forma de obtener un precio y mantenerlo por un corto tiempo, para que tu cliente pague exactamente lo que le mostraste.

Cómo probarlo: crea una cotización, espera y luego realiza el pedido con ella. Las cotizaciones de TripoSIM son válidas por 10 minutos; una cotización expirada devuelve 409 QUOTE_EXPIRED para que puedas volver a cotizar en lugar de cobrar un precio sorpresa.

4. Un feed de catálogo limpio

Qué buscar: un endpoint que enumere cada plan con su precio, datos, validez, países de cobertura, 5G, soporte para recargas y, para los planes ilimitados, el límite diario de velocidad completa.

Cómo probarlo: extrae el catálogo de un país y compáralo con el sitio web del propio proveedor. El endpoint /catalog de TripoSIM devuelve JSON o CSV, incluye planes regionales que cubren el país y añade los campos de uso justo (fup_daily_mb, fup_throttle_kbps) para planes ilimitados. Mira [cómo funcionan los límites diarios ilimitados](/blog/unlimited-esim-daily-limit-by-country-2026).

5. Entrega instantánea de pedidos y QR

Qué buscar: la respuesta del pedido (o un webhook segundos después) debe incluir el código de activación en el formato estándar LPA, por ejemplo, LPA:1$smdp.example.com$ACTIVATION_CODE, para que puedas mostrar un código QR o un enlace de instalación con un solo toque.

Cómo probarlo: realiza un pedido en el sandbox, genera el QR a partir de la cadena LPA y escanéalo con la cámara de un teléfono para comprobar que el formato es válido.

6. Webhooks firmados para cada evento

Qué buscar: notificaciones push para todo el ciclo de vida de la eSIM, firmadas para que los atacantes no puedan falsificarlas.

TripoSIM envía ocho tipos de eventos: order.completed, order.failed, esim.activated, esim.usage_80, esim.suspended, esim.resumed, esim.depleted y esim.expired. Cada solicitud lleva un encabezado X-TripoSIM-Signature: un HMAC-SHA256 de la marca de tiempo y el cuerpo bruto utilizando tu secreto de firma:

<pre><code>// reject requests older than 5 minutes (replay protection) if (Math.floor(Date.now() / 1000) - parseInt(timestamp) &gt; 300) throw new Error('Webhook too old'); const expected = crypto .createHmac('sha256', signingSecret) .update(timestamp + '.' + rawBody) .digest('hex'); if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) { throw new Error('Invalid webhook signature'); }</code></pre>

Cómo probarlo: registra un webhook, activa un pedido y verifica la firma en tu código. Luego, cambia un byte del cuerpo y asegúrate de que tu comprobación lo rechace.

7. Un sandbox que simula toda la vida de la eSIM

Qué buscar: las eSIM reales tardan días en activarse y usar datos. Un buen sandbox te permite acelerar el proceso.

Cómo probarlo: en el sandbox de TripoSIM, usa POST /sandbox/esims/{iccid}/simulate con una acción de activate, usage, deplete, expire o reset. Cada paso dispara el webhook correspondiente, por lo que puedes probar tu correo de "tus datos casi se han agotado" en minutos en lugar de días.

8. Simulación de fallos

Qué buscar: una forma de forzar errores a propósito, para que sepas que tu aplicación los gestiona correctamente.

Cómo probarlo: envía el encabezado X-Sandbox-Simulate con modos como insufficient_balance, price_changed, rate_limit, provider_unavailable o timeout, y comprueba que tu aplicación muestra un mensaje claro y solo reintenta cuando debe hacerlo.

9. Recargas en la misma eSIM

Qué buscar: los clientes que se quedan sin datos deberían poder añadir más sin tener que instalar una nueva eSIM.

Cómo probarlo: llama a POST /esims/{iccid}/topup en el sandbox (con una clave de idempotencia) y luego comprueba el nuevo saldo de datos. También comprueba qué planes admiten recargas; el catálogo debería indicártelo.

10. Datos de uso y estado

Qué buscar: un endpoint para los datos usados, los datos restantes y la expiración, para que tu equipo de soporte y tu aplicación puedan responder "¿cuántos datos me quedan?".

Cómo probarlo: llama a GET /esims/{iccid}/usage después de un evento de uso simulado. TripoSIM almacena en caché el uso durante 5 minutos, así que usa webhooks (esim.usage_80, esim.depleted) para alertas en tiempo real.

11. Suspender y reanudar

Qué buscar: una forma de pausar una eSIM —por ejemplo, cuando se disputa un pago o un cliente informa de la pérdida de un teléfono— y reanudarla más tarde.

Cómo probarlo: suspende una eSIM en el sandbox, confirma que llega el webhook esim.suspended, luego reanúdala y confirma esim.resumed.

12. Límites de velocidad, códigos de error y registro de cambios claros

Qué buscar: límites documentados, códigos de error que te indiquen si debes reintentar y un registro de cambios (changelog) público para que las actualizaciones nunca te sorprendan.

Cómo probarlo: lee la lista de errores y asigna cada código a "reintentar" o "no reintentar" en tu código. TripoSIM permite 120 solicitudes por minuto por cuenta de partner (puedes establecer límites más bajos en claves API individuales), devuelve un encabezado Retry-After en las respuestas 429, marca cada código de error como reintentable o no, y publica un endpoint de changelog.

Un plan de lanzamiento sencillo

1. Día 1: obtén las claves del sandbox, autentícate y extrae el catálogo.
2. Día 2: realiza pedidos en el sandbox con claves de idempotencia y muestra códigos QR.
3. Día 3: añade webhooks, ejecuta los simuladores de ciclo de vida y de fallos.
4. Día 4: añade recargas y uso, luego prueba en un teléfono real con una eSIM en vivo.
5. Día 5: lánzate.

La mayoría de los equipos se conectan en menos de una semana. Lee la [documentación de la API](https://docs.triposim.com) completa o consulta nuestra [guía de integración de la API de eSIM paso a paso](/blog/esim-reseller-api-how-to-integrate-travel-esim-sales-into-your-platform).

Preguntas frecuentes

¿Qué debería incluir una API de eSIM para viajes?

Como mínimo: autenticación por token, claves de idempotencia, cotizaciones de precios, un feed de catálogo, códigos de activación/QR instantáneos, webhooks firmados, un sandbox con simuladores de ciclo de vida y fallos, recargas, datos de uso, suspensión/reanudación, y límites de velocidad y códigos de error documentados.

¿Por qué son importantes las claves de idempotencia para una API de eSIM?

Cada pedido de eSIM cuesta dinero real. Si una solicitud tiene un timeout y tu sistema reintenta, una clave de idempotencia asegura que el reintento devuelva el primer resultado en lugar de comprar una segunda eSIM.

¿Cómo pruebo una API de eSIM sin comprar eSIMs?

Usa el sandbox. Un buen sandbox simula pedidos, activación, uso de datos, agotamiento y expiración —y te permite forzar errores— sin cargar tu billetera.

¿Cuánto tiempo tarda la integración de una API de eSIM?

Con una API bien documentada y un sandbox completo, la mayoría de los equipos se lanzan en 3 a 5 días laborables.

¿La API de TripoSIM admite la entrega de marca blanca (white-label)?

Sí. Recibes el código de activación y los datos del QR, por lo que puedes entregar la eSIM dentro de tu propia aplicación o correos electrónicos bajo tu marca. Consulta el [programa de la API](/api-program).

Conclusión

El precio importa, pero para una API de eSIM, la verdadera diferencia se nota después del lanzamiento: reintentos que nunca generan cargos dobles, webhooks en los que puedes confiar y un sandbox que te permite probarlo todo primero. Aplica esta lista de verificación a cualquier proveedor antes de comprometerte, y [comienza con nuestro sandbox](/api-program) para ver cómo puntúa la API de TripoSIM Partner.