STMobile

API de eSIM no atacado

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

Comece em 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.

Autenticação

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"}'
Compra de eSIM não tem estorno. 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étodoCaminhoO que faz
GET /v1/catalogPlanos disponíveis para você, já no seu preço
GET /v1/catalog/{sku}Um plano
POST /v1/ordersBuy — requires Idempotency-Key
GET /v1/ordersSeus pedidos, do mais novo para o mais antigo
GET /v1/orders/{id}Um pedido, com ICCID, LPA e o conteúdo do QR
POST /v1/orders/{id}/topupAdiciona dados a um eSIM já vendido — o QR não muda
GET /v1/balanceSaldo pré-pago
GET /v1/usage/{iccid}Dados usados, restantes e validade de um eSIM

Como é um 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"
    }]
  }
}

Recarga mantém o mesmo 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.

Limites

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.

Erros

StatusCódigoSignificado
400missing_idempotency_keyOs endpoints de compra exigem
401invalid_tokenChave errada ou revogada
402insufficient_balanceCarregue a sua conta
403account_not_liveEntrada ainda não concluída — use uma chave de sandbox
404not_foundPlano ou pedido indisponível para a sua conta
409idempotency_key_reuseMesma chave, corpo diferente
429rate_limitRequisições demais, ou teto de gasto por hora
502carrier_errorA operadora falhou — o saldo voltou automaticamente

Versionamento, em uma 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.

Fale com a gente para receber uma chave