Documentación Técnica: Consumo de API AXIOS

Introducción

Esta documentación técnica proporciona una guía detallada sobre cómo consumir una API REST. Ofrece una serie de servicios y recursos accesibles a través de solicitudes HTTP, y esta documentación está diseñada para asistir a los desarrolladores en la integración efectiva de estos servicios para el consumo de la plataforma AXIOS.

Objetivo

• Facilitar la integración: Proporcionar instrucciones claras y ejemplos prácticos para que los desarrolladores puedan integrar fácilmente los servicios de la API AXIOS.
• Explicar métodos y endpoints: Detallar los métodos HTTP y los endpoints proporcionados por la API, junto con ejemplos de uso para cada uno.

Requisitos previos

Para seguir esta guía y trabajar con la API, se asume que los desarrolladores tienen un conocimiento básico de los siguientes conceptos:

• Solicitudes HTTP: Comprender el uso de solicitudes HTTP utilizando algún recurso adecuado para la integración.
• JSON: Familiaridad con el formato de intercambio de datos utilizado en las solicitudes y respuestas.
• Autenticación: Conocimiento básico de tokens JWT y/o API Keys.

---

Versiones de la API

La API de Axios opera bajo dos versiones. Cada versión tiene su propia URL base:

Versión	URL Base	Uso
v1	https://apidevstore.axiosmobile.mx/v1	Autenticación, recargas, saldo, productos, portabilidad
v2	https://apidevstore.axiosmobile.mx/v2	Activación de eSIM

Sobre la versión v2

La versión /v2 fue creada exclusivamente para el endpoint de activación de eSIM, ya que incorpora lógica avanzada (reserva de inventario, validación de saldo previa). El resto de los recursos operan bajo /v1.

---

Autenticación

La API soporta dos mecanismos de autenticación independientes:

JWT Token

Flujo clásico de autenticación: obtienes un token mediante POST /v1/auth/:appId con tus credenciales, y lo envías en el header Authorization: Bearer {{token}} en las solicitudes siguientes.

API Key

Mecanismo simplificado para integraciones servidor-a-servidor: envías tu clave en el header x-api-key en cada solicitud, sin necesidad de un flujo de login previo. Solicítala contactando al equipo de soporte Axios.

---

Compatibilidad de Autenticación por Endpoint

No todos los endpoints soportan ambos mecanismos. Consulta la siguiente tabla para saber qué tipo de autenticación acepta cada recurso:

Endpoint	Versión	JWT	API Key	Descripción
POST /auth/:appId	v1	—	—	Obtener token JWT
POST /transactions	v1	✅	❌	Recargas
GET /transactions/check/:folio	v1	✅	❌	Consultar estado de recarga
GET /balance	v1	✅	❌	Consultar saldo
GET /products/tae	v1	✅	✅	Consultar productos disponibles
POST /transactions	v2	✅	✅	Activación de eSIM
POST /external/portability/start	v1	❌	✅	Iniciar portabilidad
GET /external/portability/status/:phone	v1	❌	✅	Consultar estado de portabilidad
POST /external/portability/cancel	v1	❌	✅	Cancelar portabilidad

Autenticación Híbrida

Los endpoints marcados con ✅ en ambas columnas (JWT y API Key) soportan autenticación híbrida: el sistema detecta automáticamente cuál mecanismo estás usando según la presencia del header x-api-key. No necesitas configuración adicional.

---

Endpoints Disponibles

Transacciones

Recurso	Método	Endpoint	Descripción
Activación de eSIM	POST	/v2/transactions	Activar una eSIM digital con QR
Recargas	POST	/v1/transactions	Realizar una recarga telefónica
Estado de recarga	GET	/v1/transactions/check/:folio	Verificar estado de una recarga

Consultas

Recurso	Método	Endpoint	Descripción
Saldo	GET	/v1/balance	Consultar saldo disponible
Productos	GET	/v1/products/tae	Listar productos y montos disponibles

Portabilidad

Recurso	Método	Endpoint	Descripción
Iniciar	POST	/v1/external/portability/start	Solicitar portabilidad de un número
Consultar estado	GET	/v1/external/portability/status/:phoneNumber	Verificar avance de la portabilidad
Cancelar	POST	/v1/external/portability/cancel	Cancelar una portabilidad en curso

---

Manejo de Respuestas y Errores

La API utiliza códigos HTTP estándar para indicar el resultado de cada solicitud:

Código	Significado
200	Solicitud exitosa
400	Error en los datos enviados (validación, saldo insuficiente, transacción rechazada)
401	No autenticado (falta token o API Key)
403	API Key inválida o no habilitada
409	Conflicto (ej: sin inventario de eSIM disponible)
500	Error interno del servidor

Cada respuesta de error incluye un campo error con una descripción legible del problema. Consulta la documentación de cada endpoint para ver los bodies específicos de error.