Activación de eSIM

Descripción

Este método permite activar una eSIM (SIM digital) de Axios Mobile con una oferta seleccionada. A diferencia de una SIM física, la eSIM se provisiona de forma remota — el cliente recibe un código QR de activación que escanea desde su dispositivo compatible, sin necesidad de una tarjeta física.

---

URL API

BASE URLhttps://apidevstore.axiosmobile.mx/v2

¿Por qué /v2?

La versión /v2 agrupa los flujos transaccionales que incorporan lógica avanzada: reserva atómica de inventario, validación de saldo previa, confirmación resuelta del lado del servidor y envío asíncrono de recibo.

Todos los recursos documentados operan bajo /v2 y se autentican con tu API Key.

Sin conflicto con la autenticación

La misma API Key asignada a tu cuenta funciona en todos los recursos /v2. No necesitas una clave diferente ni una autenticación adicional.

---

Autenticación

Este endpoint se autentica mediante API Key.

Mecanismo	Header	Descripción
API Key	x-api-key: {{apiKey}}	Clave de API asignada a tu cuenta

Envía la clave en el header x-api-key en cada solicitud. No hay flujo de login previo. Solicita tu clave contactando al equipo de soporte Axios.

Situación	Código
Header x-api-key ausente	401
Clave inválida o no habilitada	403

Límite de peticiones (rate limit)

Este endpoint está protegido por un límite de 60 peticiones por minuto por usuario (tu API Key). Si lo superas, recibirás un 429 con el mensaje { "error": "Too many requests, please try again later" }.

---

Validación de Saldo

Validación automática de saldo

Antes de procesar la transacción, el sistema verifica automáticamente que tu cuenta tenga saldo suficiente. Si el saldo es insuficiente o no puede verificarse, la solicitud se rechaza antes de intentar la activación.

---

Parámetros de entrada

Parámetro	Tipo	Requerido	Descripción	Ejemplo
carrierCode	string	Sí	Código de carrier/SKU. Valores aceptados: 204, 212, 301, 303, 215.	"204"
amount	number	Sí	Monto de la transacción. Debe ser un número positivo.	150
fullName	string	No	Nombre completo del cliente.	"Juan Pérez"
contactPhone	string	No	Teléfono de contacto. Si se envía, el recibo se manda por WhatsApp.	"5512345678"
email	string	No	Correo del cliente. Si se envía, el recibo se manda por correo.	"juan@example.com"
channel	string	No	Canal de envío del recibo: whatsapp, email o vacío. Ver nota abajo.	"email"

Entrega de la eSIM gestionada por el integrador

fullName, contactPhone y email son opcionales. Esto te da control total sobre cómo entregas la eSIM a tu cliente:

• Si envías email, Axios manda el recibo por correo.
• Si envías contactPhone, Axios manda el recibo por WhatsApp.
• Si omites ambos, Axios no envía ningún recibo: la respuesta te devuelve todos los datos de la eSIM (ICCID, QR, PIN, PUK…) en simData para que tú la entregues por el medio que prefieras.

El campo channel acota además el canal cuando sí proporcionas datos de contacto (ver abajo).

Canal de envío del recibo (channel)

El campo channel controla por dónde se envía el recibo de activación cuando hay datos de contacto:

• whatsapp — se envía solo por WhatsApp (requiere contactPhone).
• email — se envía solo por correo (requiere email).
• vacío o ausente — se envía por ambos canales, según los datos de contacto disponibles.

El valor se normaliza (se ignoran mayúsculas y espacios). Cualquier otro valor distinto de whatsapp o email devuelve un error 400. Si el canal elegido no tiene su dato de contacto (p. ej. channel=email sin email), simplemente no se envía recibo por ese canal.

Idempotencia (Idempotency-Key)

Puedes enviar el header opcional Idempotency-Key con un valor único que tú generes. Si reintentas la operación con la misma clave, la API no crea una activación duplicada: reproduce la respuesta original (mismo folio y simData) e incluye el header Idempotent-Replayed: true.

• La clave es única por cuenta (tu API Key), así que no colisiona con otros clientes.
• Si la operación previa con esa clave sigue en curso, recibirás 409 con Solicitud en proceso, reintente en unos segundos.
• Solo se conservan respuestas definitivas (2xx y 4xx). Ante un error transitorio (5xx), la clave se libera y un reintento con la misma clave puede volver a ejecutar la operación.
• Puedes consultar el estado por clave con Rastrear transacción por Idempotency-Key.

---

Ejemplo de Uso

Endpoint:

POSTapidevstore.axiosmobile.mx/v2/transactions

POST /v2/transactions HTTP/1.1
Host: apidevstore.axiosmobile.mx
x-api-key: {{apiKey}}
Content-Type: application/json
Idempotency-Key: esim-9f1c2b7e-3a44-4c1e-9b2a-7d5f1e8c0a22

{
  "carrierCode": "204",
  "amount": 150,
  "fullName": "Juan Pérez",
  "contactPhone": "5512345678",
  "email": "juan@example.com",
  "channel": "email"
}

Header Idempotency-Key opcional

El header Idempotency-Key es opcional. Si no lo envías, la activación funciona igual que siempre. Inclúyelo cuando quieras protegerte de duplicados ante reintentos de red.

---

Respuestas

200 — Transacción Exitosa Success

La activación se completó correctamente. Los datos de la eSIM y el QR de activación se incluyen en la respuesta.

{
  "status": "COMPLETED",
  "folio": "100036a358d5f64d032661114acfc",
  "description": "TRANSACCIÓN EXITOSA",
  "simData": {
    "imsi": "334140179156088",
    "iccid": "8952140062227833246F",
    "msisdn": "5632158420",
    "pin": "1234",
    "puk": "63011475",
    "serie": "00361",
    "product": "ESIM",
    "qrLink": "https://axios-mobile.s3.us-east-2.amazonaws.com/esims/8952140062227833246F.png"
  }
}

---

400 — Errores de Validación Client Error

Se retornan cuando los datos de entrada son inválidos o están incompletos.

carrierCode requerido

{ "error": "carrierCode es requerido" }

amount requerido

{ "error": "amount es requerido" }

monto inválido

{ "error": "monto inválido" }

channel inválido

{ "error": "channel inválido. Valores permitidos: \"whatsapp\", \"email\" o vacío." }

carrierCode no permitido

{ "error": "CarrierCode no permitido." }

---

400 — Error de Saldo Client Error

Se retorna cuando el saldo no puede verificarse o es insuficiente.

No se pudo verificar

{ "error": "No fue posible verificar el saldo, intente nuevamente." }

Saldo insuficiente

{ "error": "No hay saldo suficiente para realizar esta transacción." }

---

400 — Transacción Fallida Client Error

Se retorna cuando la transacción fue rechazada por el proveedor o falló la comunicación.

{
  "status": "FAILED",
  "folio": "100036a358d5f64d032661114acfc",
  "description": "Transacción fallida, intente nuevamente",
  "simData": {}
}

Posibles causas

• El proveedor rechazó la transacción (código no aceptado).
• Error de comunicación con el servicio de activación.

En todos estos casos, la eSIM reservada se libera automáticamente y no se descuenta saldo.

---

409 — Sin Inventario Conflict

No hay eSIMs disponibles en el inventario para procesar la activación.

{ "error": "No hay inventario disponible" }

---

409 — Idempotencia en proceso Conflict

Se retorna cuando ya existe una operación en curso con el mismo Idempotency-Key (aún sin respuesta definitiva). Espera unos segundos y reintenta con la misma clave, o consulta el estado con Rastrear transacción por Idempotency-Key.

{
  "error": "Solicitud en proceso, reintente en unos segundos",
  "folio": "100036a358d5f64d032661114acfc"
}

---

500 — Error Interno de Saldo Server Error

Error inesperado al intentar verificar el saldo.

{
  "error": "Error al verificar saldo.",
  "details": "Error: [mensaje del error]"
}

---

429 — Demasiadas peticiones Client Error

Se retorna cuando se supera el límite de 60 peticiones por minuto por usuario (tu API Key).

{ "error": "Too many requests, please try again later" }

---

Parámetros de salida (Respuesta Exitosa)

Parámetro	Tipo	Descripción	Ejemplo
status	string	Estado final de la transacción.	"COMPLETED"
folio	string	Identificador único de la transacción.	"100036a358d5f64d032661114acfc"
description	string	Descripción del resultado.	"TRANSACCIÓN EXITOSA"
simData.imsi	string	Identificador IMSI de la SIM.	"334140179156088"
simData.iccid	string	ICCID de la eSIM.	"8952140062227833246F"
simData.msisdn	string	Número telefónico asignado.	"5632158420"
simData.pin	string	PIN de la SIM.	"1234"
simData.puk	string	Código PUK.	"63011475"
simData.serie	string	Serie de la SIM.	"00361"
simData.product	string	Tipo de producto.	"ESIM"
simData.qrLink	string	URL pública del QR de activación de la eSIM.	"https://axios-mobile.s3..."

---

Resumen de Códigos de Respuesta

Código HTTP	Status Body	Significado
200	COMPLETED	Activación exitosa. eSIM lista para usar.
400	—	Datos de entrada inválidos (validación).
400	—	Saldo insuficiente o no verificable.
400	FAILED	Transacción rechazada o error en confirmación.
409	—	Sin inventario de eSIMs disponible.
429	—	Límite de 60 peticiones por minuto excedido.
500	—	Error interno al verificar saldo.

---

Diagrama de flujo

flowchart TD A([El cliente solicita activar una eSIM]) --> AUTH{¿API Key válida?} AUTH -->|No| UNAUTH[401 / 403 - No autorizado] AUTH -->|Sí| BAL{¿Saldo suficiente?} BAL -->|No verificable| BALERR[400 - No fue posible verificar saldo] BAL -->|Insuficiente| BALLOW[400 - Saldo insuficiente] BAL -->|Sí| B{¿Datos completos\ny válidos?} B -->|No| X[400 - Datos inválidos] B -->|Sí| C{¿Hay eSIM\ndisponible?} C -->|No| Y[409 - Sin inventario] C -->|Sí| D[Se procesa la activación] D --> E{¿El proveedor\naceptó?} E -->|No| Z[400 - FAILED + rollback SIM] E -->|Sí| F[Confirmación de activación] F --> G{¿Confirmación\nexitosa?} G -->|Error| CFAIL[400 - FAILED + rollback SIM] G -->|Timeout| TIMEOUT[200 - COMPLETED\neSIM asignada, pendiente confirmación interna] G -->|Sí| H[200 - COMPLETED] H --> I([Se envía recibo por email/WhatsApp])

---

Notas Importantes

Comportamiento del Timeout

En casos excepcionales donde la confirmación interna tarda más de lo esperado, la API responde igualmente 200 COMPLETED con los datos de la eSIM. La eSIM ya fue asignada al usuario y el saldo ya fue descontado. La confirmación final se resuelve internamente sin acción del integrador.

Envío de Recibo

El recibo se envía de forma asíncrona después de responder al cliente, solo si proporcionaste datos de contacto: por correo si enviaste email, por WhatsApp si enviaste contactPhone (acotado por channel). Si no enviaste datos de contacto, no se envía recibo y la entrega queda de tu lado. Si el envío del recibo falla, la transacción sigue siendo exitosa. Puedes reenviar el recibo con POST /v2/transactions/:folio/resend-receipt, indicando opcionalmente un email y/o phone destino (si la venta se hizo sin datos de contacto, deberás proporcionarlos en el reenvío).

Carrier Codes Permitidos

Solo se aceptan los siguientes valores para carrierCode: 204, 212, 301, 303, 215. Cualquier otro valor retornará un error 400.

Valida el IMEI antes de activar

Antes de invocar este endpoint, se recomienda validar la compatibilidad del dispositivo del cliente con Validar Compatibilidad de IMEI. Esto evita reservar inventario y descontar saldo en un dispositivo que no podrá operar en la red AXIOS.

---

Probar Endpoint

POSThttps://apidevstore.axiosmobile.mx/v2/transactionsEnviar

Activación de eSIM — Requiere API Key en el header x-api-key. El header Idempotency-Key es opcional (déjalo vacío si no lo usas).

Headers+ Agregar

×

×

×

BodyFormatear

{ "carrierCode": "204", "amount": 150, "fullName": "Juan Pérez", "contactPhone": "5512345678", "email": "juan@example.com", "channel": "email" }