Guía

Cómo integrar la API de eSIM de Atli en tu web o app

Sin clave de API: cada usuario recibe su cuenta de invitado de Atli. Cómo vincularla a tu código de socio, pedir presupuesto, cobrar y entregar la eSIM.

Una petición curl al endpoint de compra de la API de Atli junto a un móvil con la página de pago de Atli, y la mascota azul con alas de Atli con un móvil en la mano al lado de una maleta

Los socios pueden usar la misma API de eSIM de Atli sobre la que funcionan heyatli.com y el widget de Atli. Puedes crear tus propias interfaces de listado de destinos, selección de planes, proceso de pago e instalación para una web, una app o un bot. Atli proporciona el catálogo de planes, procesa los pagos a través de su cuenta de Stripe y emite las eSIM.

La API no usa claves de API a nivel de aplicación. La autenticación se basa en tokens individuales de cada usuario. Tu servidor inicia la sesión de cada usuario con un ID de dispositivo único o mediante OAuth y después hace las peticiones a la API en su nombre. Cada cuenta de invitado necesita su propio ID de dispositivo, que tu aplicación debe guardar de forma segura.

Sandbox, producción y el archivo OpenAPI

SandboxProducción
APIhttps://api-staging.heyatli.comhttps://api.heyatli.com
Archivo OpenAPIhttps://api-staging.heyatli.com/openapi.yamlhttps://api.heyatli.com/openapi.yaml
Página de pagohttps://staging.heyatli.com/payhttps://heyatli.com/pay

Sandbox usa cuentas separadas y pagos de prueba, por lo que no se hace ningún cargo real. Sus eSIM vienen de un operador de prueba, así que no se pueden instalar en un móvil, y las ventas en Sandbox nunca generan comisión. Todos los ejemplos de esta guía que crean cuentas o pedidos usan endpoints de Sandbox. En producción, cambia la URL base de la API a https://api.heyatli.com. La referencia de partners.heyatli.com/es/dev/api permite cambiar entre los dos entornos.

El mapa de los recorridos principales de la API de Atli: crear un usuario, pedir presupuesto, comprar y pagar, obtener la eSIM, instalarla y seguir el consumo, con ramas opcionales para una cuenta real, tarjetas guardadas y de grupo, recargas, descuentos y eSIM compartidas

Los errores de la API siguen siempre el mismo formato: un code, un message en inglés y un trace_id para resolver incidencias con el soporte de Atli. Usa code para decidir cómo gestiona el error tu aplicación y qué mensaje muestra. El campo message puede quedarse en tus logs.

El inicio de sesión, los presupuestos, el canje de cupones y la sincronización de eSIM tienen límite de peticiones, y una petición rechazada responde 429 con Retry-After en segundos.

Puedes generar un cliente tipado de la API a partir de la especificación OpenAPI en lugar de escribir cada petición HTTP:

Bash
docker run --rm -v "$PWD:/out" \
  openapitools/openapi-generator-cli generate \
  -i https://api.heyatli.com/openapi.yaml \
  -g typescript-fetch -o /out/atli-sdk

Cambia typescript-fetch por python, java, csharp, php o swift6. Para Go hace falta go --additional-properties=enumClassPrefix=true.

Paso 1: crea un usuario

Puedes crear una cuenta de invitado de Atli para cada usuario sin pedirle que se registre. Genera un UUID único para cada usuario, por ejemplo con crypto.randomUUID(), y guárdalo de forma segura en el registro de su cuenta.

Trata el ID de dispositivo como una credencial sensible, porque cualquiera que tenga acceso a él puede autenticarse como ese usuario.

Inicia sesión con él desde tu servidor. Un ID que Atli no ha visto nunca crea una cuenta de invitado, y uno que ya conoce vuelve a abrir la sesión de esa cuenta:

Bash
curl https://api-staging.heyatli.com/login \
  -H 'Content-Type: application/json' \
  -d '{ "device_id": "YOUR_DEVICE_ID" }'
JSON
{
  "token": "eyJhbGci…",
  "refresh_token": "…",
  "expires_in": 900,
  "session_id": "…",
  "user": { "id": "…", "email": null }
}

Envía token como Authorization: Bearer YOUR_TOKEN en cada llamada que necesite un usuario. Dura 15 minutos. Renuévalo poco antes de que caduque con POST /refresh y el refresh_token. La respuesta de la renovación llama al token nuevo access_token, no token. Asegúrate de que tu integración lea el campo correcto para evitar fallos de autenticación cuando caduque el token inicial. Guarda el token de actualización cada vez, porque cada renovación devuelve uno nuevo y retira el anterior. Si pierdes los dos, vuelve a iniciar sesión con el ID de dispositivo.

Un invitado puede comprar y usar eSIM. Algunas eSIM compartidas y algunos cupones necesitan una cuenta real, y la API se los deniega a un invitado con un código como gift_sign_in_required. Para darle un correo al invitado, envía su token y su device_id a POST /auth/email/otp y confirma después con POST /auth/email/verify. El inicio de sesión con WhatsApp o Telegram también puede convertir a un invitado en cuenta real. En ambos casos, el invitado conserva las eSIM y los datos de cuenta que ya tenga. Si omites el device_id, o usas un correo que ya tiene cuenta de Atli, la persona acaba en otra cuenta.

Paso 2: vincula al usuario con tu código de socio

Vincula a cada usuario nuevo con tu código antes de su primer presupuesto:

Bash
curl https://api-staging.heyatli.com/user/referral/redeem \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "code": "YOUR_PARTNER_CODE" }'

El campo result indica el resultado: ok significa que el usuario se ha vinculado correctamente, already que ya está vinculado a alguien, notnew que ya ha hecho una compra antes, own que es tu propio código y notfound que no se ha encontrado el código. Solo se puede vincular a una persona que no esté vinculada a nadie y no haya comprado nunca, y solo una vez. Haz esta llamada justo después de crear el usuario.

El vínculo es permanente. Si tu código lleva descuento, se aplica a la primera eSIM del usuario sin que tengas que volver a enviar el código. La guía del programa de afiliados explica lo que te reporta ese vínculo.

Paso 3: muestra los planes y pide un presupuesto

GET /explore/plans devuelve el catálogo completo, que recoge los destinos disponibles, los paquetes, los precios y los datos incluidos. No necesita token, así que tu servidor puede listar planes antes de que nadie tenga cuenta. Llámalo desde tu servidor, porque la API rechaza con 403 las peticiones de navegador que llegan desde otras webs. Pasa currency y filtra con destination (JP, europe) o category (local, regional, global):

Bash
curl 'https://api-staging.heyatli.com/explore/plans?currency=EUR&destination=JP'

El id de un paquete es el product_id que compras. Pide su presupuesto con store: true para obtener un quote_id:

Bash
curl https://api-staging.heyatli.com/plan/quote \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "product_id": "THE_PACKAGE_ID",
        "currency": "EUR",
        "store": true }'
JSON
{
  "subtotal_cents": 1500,
  "total_discount_cents": 150,
  "net_total_cents": 1350,
  "currency": "EUR",
  "quote_id": "…",
  "expires_at": "…"
}

Muestra net_total_cents como precio final. Los presupuestos guardados caducan a los 30 minutos, así que genera el presupuesto cuando el usuario pase a la pantalla de pago. Cada usuario tiene un solo presupuesto guardado a la vez, y uno nuevo sustituye al anterior.

target_esim_id recarga una eSIM que el usuario ya tiene. Sin él, el plan va a la eSIM predeterminada del usuario. Si aún no tiene ninguna eSIM, o si la red de la predeterminada no vende ese plan, va a una eSIM nueva. Para alguien que ha iniciado sesión con su propia cuenta de Atli, el campo new_esim del presupuesto dice cuál de las dos será. Los presupuestos de invitados no lo incluyen. Con un invitado, compara la eSIM del pedido terminado con las que lista GET /esims antes de mostrar los pasos de instalación.

auto_apply_best_voucher aplica el cupón válido de mayor valor que tenga el usuario, y points_to_redeem le permite canjear sus créditos Atli, que la API llama puntos. Un pedido admite un solo tipo de descuento. El descuento de referido de tu enlace va primero y se impone a cualquier cupón que el presupuesto elegiría por su cuenta. Un cupón indicado con voucher_code lo sustituye, e indicar a la vez un cupón y un referral_code falla con cannot_combine_voucher_and_referral. Los créditos solo se aplican cuando no hay ninguno de los dos descuentos.

Paso 4: crea el pedido y cobra

Haz la compra con el quote_id del presupuesto guardado. El pedido toma del presupuesto el plan, los descuentos y el precio. Si desde entonces el total se ha movido más de un 1 %, la compra falla con price_changed y tienes que pedir otro presupuesto.

Cada presupuesto sirve para un solo pedido. Si una petición de compra se envía otra vez por error o tras un timeout, la API devuelve el pedido existente en lugar de crear uno duplicado. La petición también tiene que incluir una idempotency_key, que evita pedidos duplicados cuando compras directamente con un product_id en lugar de un presupuesto guardado.

Bash
curl https://api-staging.heyatli.com/plan/purchase \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "quote_id": "THE_QUOTE_ID",
        "idempotency_key": "A_NEW_UUID" }'
JSON
{
  "order_id": "…",
  "client_secret": "pi_…_secret_…",
  "sealed_secret": "eyJhbGciOiJFQ0RILUVTIi…",
  "key_id": "…",
  "seal_signature": "…",
  "options": "{\"message\":\"Plan for Japan\",\"lang\":\"en\"}",
  "options_signature": "…",
  "total_amount_cents": 1350,
  "status": "pending_payment"
}

El client_secret pertenece a un PaymentIntent de Stripe en la cuenta de Atli. Monta con él el Payment Element de Stripe. Tu servidor lee la clave publicable de GET /stripe/config y se la pasa a la página junto con el client_secret. No escribas la clave en el código, porque cambia entre Sandbox y producción, y no la pidas desde la página, porque la API rechaza las peticiones de navegador que llegan desde otras webs:

JavaScript
const stripe = Stripe(publishable_key);

const elements = stripe.elements({ clientSecret: order.client_secret });
elements.create('payment').mount('#pay');

const { error } = await stripe.confirmPayment({
  elements,
  confirmParams: { return_url: window.location.href },
  redirect: 'if_required',
});

Pasa el client_secret solo a la sesión del usuario que paga y no lo dejes en tus logs. Cuando Stripe confirme el pago, dile a Atli que emita la eSIM:

Bash
curl https://api-staging.heyatli.com/plan/fulfill-payment \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "order_id": "THE_ORDER_ID" }'

Si esa llamada falla, no vuelvas a cobrar. Atli completa por su cuenta un pedido pagado.

El pago se cobra en la cuenta de Stripe de Atli, así que en el extracto de la tarjeta de tu cliente aparece el nombre de Atli, y los reembolsos y las disputas van a Atli. Para ofrecer Apple Pay y Google Pay en tu propio formulario, escribe a [email protected] cuando tu integración tenga ventas reales detrás. Las tarjetas guardadas funcionan con la misma compra: añade payment_method_id para cobrar a una, o save_card: true para guardar una tarjeta nueva para la próxima vez.

Cobrar con la página de pago de Atli

Los bots de WhatsApp y Telegram, las apps de voz y los asistentes de IA no pueden mostrar el formulario de pago de Stripe. En esas integraciones, puedes dirigir a los usuarios a la página de pago alojada por Atli. Construye el enlace con los tres valores sellados que devolvió la compra. Si la compra devuelve también options y options_signature, pásalos, y la página mostrará encima del formulario de la tarjeta una línea como «Plan for Japan» en el idioma que indicaste en la petición:

JavaScript
const link = new URL('https://staging.heyatli.com/pay');
link.search = new URLSearchParams({
  type: 'payment_intent',
  sealed_secret: order.sealed_secret,
  key_id: order.key_id,
  seal_signature: order.seal_signature,
  ...(order.options && {
    options: Buffer.from(order.options).toString('base64url'),
    options_signature: order.options_signature,
  }),
}).toString();

La página de pago muestra el total del pedido y admite pagos con tarjeta, Apple Pay y Google Pay. Después llama a POST /plan/fulfill-payment con el order_id y repite la llamada hasta que el pedido esté pagado. Solo esa llamada confirma el pago, porque la página muestra como correcto un pago que todavía se está procesando.

Sigue estos requisitos al generar enlaces de pago:

  • Pasa sealed_secret, key_id, seal_signature y options_signature exactamente como los devolvió la API, y URLSearchParams se encarga de la codificación. options es la excepción: codifícalo en base64url sin cambiar antes el JSON. Nunca pongas un client_secret en claro en un enlace.
  • Los valores de Sandbox solo se abren en staging.heyatli.com/pay, y los de producción solo en heyatli.com/pay.
  • El enlace paga el pedido de alguien. Envíalo solo al titular de la cuenta y mantenlo fuera de los logs.
  • No guardes enlaces para más tarde. Una compra nueva cancela el pedido pendiente anterior y su enlace.
  • brand=none oculta el logotipo de Atli. lang y theme fijan el idioma y el aspecto de la página. Los parámetros de redirección solo aceptan direcciones https de heyatli.com o sus subdominios, así que dile a la persona que vuelva a tu chat cuando haya pagado.
  • El botón Cancelar de la página deja el pedido abierto. Para cancelarlo, llama a POST /orders/{id}/cancel.

La misma página sirve para guardar una tarjeta sin cobrar nada: crea la configuración con POST /user/payment-methods/setup-intent, construye el enlace con type igual a setup_intent y después guarda la tarjeta con POST /user/payment-methods/confirm. partners.heyatli.com/es/dev/payment-widget puede abrir un pago de prueba con un invitado de Sandbox recién creado.

Paso 5: muestra la eSIM y sus enlaces de instalación

Puede que una eSIM no esté disponible para instalar justo después del pago. Consulta el estado del pedido hasta que el objeto esim contenga los datos de instalación. Mientras el pedido se procesa, muestra un mensaje de estado adecuado:

Bash
curl 'https://api-staging.heyatli.com/fulfillment/status-updates?order_id=THE_ORDER_ID' \
  -H 'Authorization: Bearer YOUR_TOKEN'
JSON
{
  "order_id": "…",
  "status": "completed",
  "esim": {
    "id": "…",
    "iccid": "…",
    "lpa_address": "…",
    "activation_code": "…",
    "qr_string": "…"
  }
}

El estado paid confirma el pago, y completed indica que la eSIM y su plan asociado se han aprovisionado. Muestra qr_string como código QR para instalarla desde un segundo dispositivo. Para los usuarios que instalan la eSIM directamente en su móvil, ofrece los enlaces de instalación para iPhone o Android, que abren la configuración de eSIM del propio sistema:

JavaScript
const lpa = `LPA:1$${esim.lpa_address}$${esim.activation_code}`;
const carddata = encodeURIComponent(lpa);

const iphone = `https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=${carddata}`;
const android = `https://esimsetup.android.com/esim_qrcode_provisioning?carddata=${carddata}`;

O dale a tu usuario un solo enlace que lo hace todo: https://heyatli.com/my/esim con lpa igual al qr_string en base64url e iccid igual al ICCID de la eSIM. La página muestra el código QR, los dos enlaces de un toque y los datos para la instalación manual, y con el ICCID muestra también los planes y los datos que quedan. No necesita cuenta de Atli. Pon un idioma en la ruta, como /ja/my/esim, y usa staging.heyatli.com para una eSIM de Sandbox. Cualquiera con el enlace puede instalar la eSIM, así que envíalo solo a la persona que la va a usar.

Nuestras guías para iPhone y Android explican lo que ve el usuario a continuación.

GET /esims lista las eSIM del usuario con sus datos de instalación, sus planes y el consumo registrado en la última sincronización. POST /esims/{id}/sync pide a la red las cifras actuales. Cada petición de sincronización consulta al operador de red y está sujeta a límites de peticiones. Pide datos de consumo actualizados cuando hagan falta, en lugar de consultarlos automáticamente a intervalos fijos.

Inicio de sesión con la propia cuenta de Atli

Para una app en la que la gente use su propia cuenta de Atli en lugar de un invitado, Atli ofrece OAuth 2.1: el flujo de código de autorización con PKCE (S256), tokens de actualización rotativos y revocación. Los usuarios se autentican y autorizan el acceso en heyatli.com, así que tu aplicación nunca maneja sus contraseñas de Atli.

Registra un cliente en partners.heyatli.com/es/dev/oauth/clients. Una cuenta puede tener hasta 10 clientes: public para apps móviles y confidential para un servidor capaz de guardar un secreto. Una página web no puede hacer por sí sola la llamada del token, porque la API rechaza las peticiones de navegador que llegan desde otras webs salvo que Atli haya marcado el cliente como de confianza, así que dale a una app web un servidor y un cliente confidencial. Solo un cliente tuyo puede obtener tokens para la API, y tu cuenta necesita una dirección de correo para tener uno.

Obtén los endpoints de OAuth de los metadatos del servidor de autorización en lugar de escribirlos en el código:

Bash
curl https://api.heyatli.com/.well-known/oauth-authorization-server

Los tokens de acceso duran 15 minutos. Cada renovación devuelve un token de actualización nuevo, que debe sustituir al anterior en el almacenamiento seguro de tu aplicación. Las personas que inician sesión con tu cliente pueden quedar vinculadas a ti automáticamente cuando Atli lo active en tu cuenta. Hasta entonces, vincúlalas tú con POST /user/referral/redeem y su token de acceso, como en el paso 2.

Compartir eSIM, cupones y grupos

Para comprar una eSIM que se pueda compartir, pide un presupuesto con is_gift: true y fija max_claims en un valor entre 1 y 20. Cuando el pedido se haya completado, obtén el claim_url en GET /gifts/sent. POST /rewards/voucher/redeem añade un cupón a la cuenta del usuario. Un miembro de un Atli Group puede pedir presupuesto con group_id y comprar con la tarjeta del grupo. partners.heyatli.com/es/dev/api explica cada uno de estos recorridos paso a paso y con código.

Preguntas frecuentes

¿La API de Atli tiene clave de API?
No. Los tokens identifican a una persona, no a una aplicación. Tu servidor inicia la sesión de cada usuario con un ID de dispositivo o mediante OAuth y luego llama a la API en nombre de ese usuario.
¿Necesito mi propia cuenta de Stripe?
No. Los pedidos se cobran en la cuenta de Stripe de Atli. Tu formulario usa la clave publicable de Atli que devuelve GET /stripe/config, y los datos de la tarjeta van directamente a Stripe, nunca a tus servidores ni a la API.
¿Los clientes pueden pagar con Apple Pay o Google Pay?
Sí. La página de pago de Atli ofrece los dos. Para tenerlos en tu propio formulario de Stripe, escribe a [email protected] cuando tu integración tenga ventas reales.
¿Cómo añado datos a una eSIM que el usuario ya tiene?
Pide el presupuesto del paquete nuevo con target_esim_id apuntando a esa eSIM y cómpralo como siempre. El plan va a la eSIM que el usuario ya tiene, así que no hay nada nuevo que instalar. Si la red de esa eSIM no vende el paquete, la API lo rechaza con incompatible_esim.
¿Y si el pago se completa pero falla mi llamada para emitir la eSIM?
No vuelvas a cobrar. Atli termina por su cuenta un pedido pagado, así que sigue consultando GET /fulfillment/status-updates hasta que aparezca la eSIM.
¿Dónde hago pruebas sin dinero real?
En Sandbox, en api-staging.heyatli.com, con la tarjeta de prueba de Stripe 4242 4242 4242 4242, cualquier fecha futura y cualquier código de seguridad. Sandbox tiene sus propias cuentas.