API documentation · Solution Telecom Mobile

API de eSIM mayorista

One integration, several carriers. You keep the customer; we provision the line. Base URL https://solutiontelecommobile.com/v1 — OpenAPI 3.0.

Empieza en sandbox. A key that begins with stm_sandbox_ walks the exact same code path — same validation, same idempotency, same response shape — but it never contacts a carrier and never touches your balance. Integrate with it while your account is being onboarded.

Autenticación

curl https://solutiontelecommobile.com/v1/balance \
  -H "Authorization: Bearer stm_sandbox_your_key_here"

Buying — and the one header that matters

curl -X POST https://solutiontelecommobile.com/v1/orders \
  -H "Authorization: Bearer $STM_KEY" \
  -H "Idempotency-Key: your-order-4711" \
  -H "Content-Type: application/json" \
  -d '{"sku":"PFRQ8FIBC","quantity":1,"reference":"your-order-4711"}'

La compra de eSIM no tiene reembolso. If your request times out and you retry without the same Idempotency-Key, you buy twice and pay twice. Send the key, reuse it on every retry, and we return the original response — same body, same status. Reusing a key with a different body returns 409, because that means you meant a different purchase.

Endpoints

Método	Ruta	Qué hace
GET	/v1/catalog	Planes disponibles para ti, ya a tu precio
GET	/v1/catalog/{sku}	Un plan
POST	/v1/orders	Buy — requires Idempotency-Key
GET	/v1/orders	Tus pedidos, del más nuevo al más antiguo
GET	/v1/orders/{id}	Un pedido, con ICCID, LPA y el contenido del QR
POST	/v1/orders/{id}/topup	Agrega datos a un eSIM ya vendido — el QR no cambia
GET	/v1/balance	Saldo prepago
GET	/v1/usage/{iccid}	Datos usados, restantes y vencimiento de un eSIM

Cómo se ve un pedido

{
  "data": {
    "id": 5,
    "environment": "sandbox",
    "status": "delivered",
    "sku": "PFRQ8FIBC",
    "quantity": 1,
    "unit_price_usd": "0.3750",
    "total_price_usd": "0.3750",
    "currency": "USD",
    "reference": null,
    "topup_of": 4,
    "esims": [{
      "iccid": "8955...",
      "activation_code": "LPA:1$smdp.example$MATCHINGID",
      "qrcode": "LPA:1$smdp.example$MATCHINGID"
    }]
  }
}

La recarga mantiene el mismo QR. POST /v1/orders/{id}/topup returns a new order with topup_of pointing at the original — the traveller installs nothing again, the data simply lands on the same eSIM.

Límites

Two of them, and the second is the one that protects you: a cap on requests per minute, and a cap on how much balance can be spent per hour. A loop without a sleep can otherwise drain your account in seconds. When you hit either, we answer 429 with Retry-After — retry with the same key, never a new one.

Errores

Estado	Código	Significado
400	missing_idempotency_key	Los endpoints de compra lo exigen
401	invalid_token	Clave incorrecta o revocada
402	insufficient_balance	Recarga tu cuenta
403	account_not_live	Alta aún sin concluir — usa una clave de sandbox
404	not_found	Plan o pedido no disponible para tu cuenta
409	idempotency_key_reuse	Misma clave, cuerpo diferente
429	rate_limit	Demasiadas peticiones, o tope de gasto por hora
502	carrier_error	El operador falló — el saldo se devolvió automáticamente

Versionado, en una frase

We add fields freely; we never rename or remove one without publishing /v2 and keeping /v1 running. Write your parser to ignore unknown fields and your integration will not break.

Habla con nosotros para obtener una clave