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 API Keys.
Versión de la API
La API de Axios opera bajo la versión /v2:
| Versión | URL Base | Uso |
|---|---|---|
| v2 | https://apidevstore.axiosmobile.mx/v2 | Autenticación por API Key, activación de eSIM, recargas, saldo, productos |
Autenticación
La API se autentica mediante API Key.
API Key
Mecanismo 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. Tu clave está asociada a un usuario y a una aplicación, y el servidor resuelve ese contexto automáticamente. Solicítala contactando al equipo de soporte Axios.
| Situación | Código |
|---|---|
Header x-api-key ausente | 401 |
| Clave inválida o no habilitada | 403 |
Compatibilidad de Autenticación por Endpoint
Todos los recursos documentados viven bajo /v2 y aceptan tu API Key en el header x-api-key:
| Endpoint | Versión | API Key | Descripción |
|---|---|---|---|
POST /transactions | v2 | ✅ | Activación de eSIM |
POST /transactions/tae | v2 | ✅ | Recargas |
GET /transactions/check/:folio | v2 | ✅ | Consultar estado de recarga |
GET /balance | v2 | ✅ | Consultar saldo |
GET /products · /products/tae | v2 | ✅ | Consultar productos disponibles |
GET /compatibility/imei/:imei | v2 | — | Validar compatibilidad de IMEI (público) |
Endpoints Disponibles
Transacciones
| Recurso | Método | Endpoint | Descripción |
|---|---|---|---|
| Activación de eSIM | POST | /v2/transactions | Activar una eSIM digital con QR |
| Validar IMEI | GET | /v2/compatibility/imei/:imei | Validar compatibilidad de un dispositivo (sin autenticación) |
| Recargas | POST | /v2/transactions/tae | Realizar una recarga telefónica |
| Estado de recarga | GET | /v2/transactions/check/:folio | Verificar estado de una recarga |
Consultas
| Recurso | Método | Endpoint | Descripción |
|---|---|---|---|
| Saldo | GET | /v2/balance | Consultar saldo disponible |
| Productos | GET | /v2/products/tae | Listar productos y montos disponibles |
| Todos los productos | GET | /v2/products | Listar todos los productos (filtro opcional por tipo) |
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 el header x-api-key) |
403 | API Key inválida o no habilitada |
409 | Conflicto (ej: sin inventario de eSIM disponible) |
429 | Límite de peticiones excedido (rate limit) |
500 | Error interno del servidor |
Cada respuesta de error incluye un campo error o message con una descripción legible del problema. Consulta la documentación de cada endpoint para ver los bodies específicos de error.