Telco API
API de telecomunicaciones de Mirlo — telefonia movil, portabilidad, eSIM de viaje, usuarios, ordenes y balance.
Probala en Postman
Todos los endpoints de esta seccion, en carpetas, con la autenticacion ya armada.
En Postman: Import > Link, y pega el link.
Introduccion
La API de Partners de Mirlo permite a empresas integrar servicios de telecomunicaciones en sus plataformas. A traves de esta API puedes:
- Gestionar usuarios y sus direcciones
- Consultar planes de telefonia movil y eSIM de viaje
- Crear ordenes (compra de linea, recargas, cambios de plan y de SIM)
- Dar de alta portabilidades, seguir su estado y cancelarlas
- Recibir webhooks de ciclo de vida de tus lineas
- Monitorear suscripciones y consumo de datos
- Verificar identidad (KYC)
- Consultar balance y debitos
Entornos
Hay dos entornos independientes. Cada uno tiene su propia base de datos y sus propias API keys.
| Entorno | URL base | Prefijo de key |
|---|---|---|
| Produccion | https://api.mirlo.com/v1 | sk_live_... |
| Sandbox (dev) | https://api-dev.mirlo.com/v1 | sk_test_... |
Las keys no cruzan de entorno
Una key creada en produccion no funciona en sandbox, y viceversa: cada gateway valida la key contra la base de su propio entorno. Para probar en sandbox necesitas una key emitida en sandbox — no alcanza con que tu organizacion exista en los dos lados.
El entorno de una key es un atributo de la key, no del prefijo. Produccion rechaza con
401 las keys de entorno test.
Autenticacion
Cada solicitud lleva tu API key en el header X-API-Key, con el valor tal cual, sin
Bearer:
X-API-Key: sk_live_xxxxxxxxxxxxxEjemplo
curl -X GET "https://api.mirlo.com/v1/partner/users" \
-H "X-API-Key: sk_live_xxxxxxxxxxxxx"No uses Authorization: Bearer
El header Authorization: Bearer esta reservado para JWTs ya firmados. Si mandas la API
key ahi, el gateway intenta validarla como JWT, falla la firma y responde 401 — aunque
la key sea valida.
Seguridad
- Nunca compartas tu API Key publicamente
- No incluyas el API Key en codigo del lado del cliente
- Usa variables de entorno para almacenar el API Key
Rutas
Todos los endpoints cuelgan de /v1/partner/.... La superficie publicada es:
Las acciones sobre una linea cuelgan del id de la suscripcion
(POST /v1/partner/subscriptions/{id}/suspend), no de un recurso orders.
| Recurso | Ruta base |
|---|---|
| Usuarios | /v1/partner/users |
| Planes moviles | /v1/partner/plans |
| Recargas | /v1/partner/topups |
| Ofertas de eSIM de viaje | /v1/partner/esim-offers |
| eSIM de viaje | /v1/partner/data_esims |
| Suscripciones (alta, acciones y consulta) | /v1/partner/subscriptions |
| Balance | /v1/partner/balance |
| Codigos de area | /v1/partner/area_codes |
| Portabilidad | /v1/partner/portings |
| Webhooks de eventos de linea | /v1/partner/lifecycle-webhooks |
Un 404 en una ruta /v1/... mientras las rutas hermanas responden 401 significa que
esa ruta no esta publicada, no que el recurso no exista. Escribinos si necesitas una.
Productos habilitados
Tu API key resuelve tu organizacion, y tu organizacion tiene habilitados los productos que figuran en tu contrato:
| Producto | Que habilita |
|---|---|
| SIM fisica | POST /partner/subscriptions con type: "SIM" |
| eSIM | POST /partner/subscriptions con type: "ESIM" |
| eSIM de viaje | El catalogo y la compra de esim-offers / data_esims |
Si intentas vender un producto que no tienes habilitado, la respuesta es 403. El catalogo
de eSIM de viaje devuelve una lista vacia en vez de error.
Formato de respuesta
Todas las respuestas se envian en formato JSON. Las fechas usan formato ISO 8601. Los montos monetarios se expresan en la moneda local (MXN para Mexico).
Versionado
La API actual es la version 1 (v1). Todos los endpoints incluyen el prefijo /v1/ en la URL.