Pentru reselleri & dezvoltatori

API-ul eSIM pentru reselleri, agenții și aplicații

Vinde eSIM-uri de călătorie prepaid pentru 190+ destinații sub brandul tău. REST API cu livrare instant, consum live per ICCID, chei sandbox și facturare din portofel.

Solicită acces partener Vorbește cu noi

Ce poți face cu API-ul

Catalog complet de planuri

Preia toate planurile de călătorie cu prețurile tale B2B, acoperire și valabilitate.

Livrare instant a comenzii

Plasezi comanda și primești codul QR / string-ul LPA de activare în câteva secunde.

Consum live per ICCID

Verifici starea liniei, data activării, datele consumate și expirarea pentru orice eSIM vândut.

Mediu sandbox

Dezvolți și testezi cu chei mega_test_ — fără să consumi portofelul sau un eSIM real.

Facturare din portofel

Portofel prepaid, fără comisioane per apel. Alimentezi cu cardul (Stripe) sau bancar (Wise).

Webhooks

Ești notificat la evenimentele comenzii ca să-ți automatizezi propria livrare.

Documentație Partner API v1

Referință publică REST API. Creează un cont de partener ca să primești cheia live și cheia sandbox, apoi folosește exemplele de mai jos.

Base URL — browser

https://megaesim.us/api/v1

Test manual sau apeluri din browser autentificat.

Base URL — server

https://api.megaesim.us/api/v1

Recomandat pentru backend (Render, Node, Python) — ocolește verificarea Cloudflare anti-bot.

Autentificare: Authorization: Bearer mega_live_…

Endpoints

Method	Path	Descriere
GET	/me	Verifică cheia și returnează contul
GET	/plans	Catalog planuri (prețuri B2B per cont)
GET	/plans/{id}	Detaliu plan
GET	/wallet	Sold portofel + ultimele tranzacții
GET	/orders	Listă comenzi (?limit=25, max 100)
POST	/orders	Plasează comandă (debitează portofelul)
GET	/orders/{id}	Status comandă
GET	/orders/{id}/esim	Date eSIM după livrare (QR, LPA, ICCID)
GET	/esims/{iccid}/usage	Consum live per ICCID (activare, date, expirare)

Verificare cheie — GET /me▾

Răspuns 200: ok, accountEmail, apiKeyName, apiKeyId.

Request

GET https://megaesim.us/api/v1/me
Authorization: Bearer mega_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Catalog — GET /plans▾

Returnează plans[]: id, name, nameEn, dataDescription, coverage, priceEuro, priceCents, validityDays, carrier, hasInstantDelivery, available, outOfStock.

Request

GET https://megaesim.us/api/v1/plans
Authorization: Bearer mega_live_…

Portofel — GET /wallet▾

Returnează balanceCents, currency și transactions[]. Nu există endpoint de top-up în API — alimentarea e din portal: card (Stripe, cu comision) sau Wise (orice sumă de la €30, fără comision, credit 1:1).

Request

GET https://megaesim.us/api/v1/wallet
Authorization: Bearer mega_live_…

Plasare comandă — POST /orders▾

Răspuns: orderId, amountCents, fulfillmentStatus, autoDelivered, autoRefunded, manualPending, emailSent, esimId (dacă livrat automat).

Poll status: GET /orders/{id} — același obiect comandă ca în listă. Orange ES: LPA poate dura câteva minute — poll până delivered, apoi GET /orders/{id}/esim.

În GET /plans, planurile Orange ES au supportsActivationScheduling: true.

Câmp	Obligatoriu	Descriere
planId	da	ID plan din /plans
deliveryEmail	nu	Email client final; omit = contul tău
customerNote	nu	Notă internă (max 500 car.)
idempotencyKey	recomandat	Aceeași cheie → aceeași comandă
activation	nu	Doar Orange ES (7984–7986): startDate (YYYY-MM-DD, Europe/Bucharest) + durationMonths (1\|2\|3). Debit = priceCents × durationMonths. Implicit: azi + 1 lună.

Request

POST https://megaesim.us/api/v1/orders
Authorization: Bearer mega_live_…
Content-Type: application/json

{
  "planId": 7985,
  "deliveryEmail": "[email protected]",
  "customerNote": "Ref. internă #12345",
  "idempotencyKey": "your-unique-key-2026-001",
  "activation": {
    "startDate": "2026-10-05",
    "durationMonths": 2
  }
}

Poll eSIM — GET /orders/{id}/esim▾

După livrare: esim cu iccid, activationCode, qrCodeData, smdpAddress, deliveredAt.

Dacă eSIM-ul nu e gata: 404 cu code esim_not_ready.

Request

GET https://megaesim.us/api/v1/orders/123456/esim
Authorization: Bearer mega_live_…

Consum live — GET /esims/{iccid}/usage▾

Interoghează consumul și starea liniei folosind ICCID-ul primit din /orders/{id}/esim.

Datele sunt cache-uite ~3 minute per eSIM. Adaugă ?refresh=1 pentru citire live (folosește cu moderație).

Câmpurile de date sunt disponibile doar pentru eSIM-urile pe rețele cu raportare de consum; altfel supported:false și câmpurile de consum sunt null. Consumul rămas nu este expus — doar dataUsedMb (total).

ICCID necunoscut în cont → 404 esim_not_found. Furnizor de consum indisponibil temporar → 503 usage_upstream_unavailable.

Request

GET https://megaesim.us/api/v1/esims/8939104610004735215/usage
Authorization: Bearer mega_live_…

Webhooks — evenimente către URL-ul tău▾

Înregistrezi un URL HTTPS în Developers → Webhooks. Trimitem POST JSON la order.placed, order.delivered, order.refunded, wallet.topup.

Header: x-megaesim-signature = t=<unix>,v1=<hmac-sha256(secret, timestamp.body)>.

Câmpul id din payload identifică evenimentul. Dacă serverul tău e picat, retrimitem ACELAȘI id (1 min, 5 min, 30 min, 2 h) — nu se creează o comandă nouă și nu se debitează din nou portofelul.

Pentru POST /orders folosește mereu idempotencyKey, ca un retry al tău să nu plaseze două comenzi.

Erori frecvente

401 — Cheie invalidă, revocată sau acces API dezactivat
402 · insufficient_balance — Sold portofel insuficient
404 · plan_not_found — Plan inexistent
404 · esim_not_ready — eSIM încă nelivrat
404 · esim_not_found — Niciun eSIM cu acest ICCID în cont
409 · out_of_stock — Plan indisponibil
429 — Rate limit depășit (vezi mai jos)
503 · usage_upstream_unavailable — Furnizorul de consum e temporar indisponibil

Rate limits (per cheie API)

Citiri (GET): 120 / minut · Comenzi (POST /orders): 30 / minut. La depășire: HTTP 429 + retryAfterSec.

Securitate

Păstrează cheia doar server-side — nu o expune în frontend public.
Folosește idempotencyKey la fiecare comandă (retry-safe).
Revocă imediat cheile compromise din secțiunea de mai sus.
Răspunsurile nu expun detalii interne de aprovisionare.

Flux recomandat

GET /plans — afișează catalogul cu prețurile tale B2B.
GET /wallet — verifică soldul înainte de comandă.
POST /orders cu idempotencyKey — plasează comanda.
Dacă autoDelivered: false, poll GET /orders/{id} până fulfillmentStatus = delivered.
GET /orders/{id}/esim — preia QR / LPA / ICCID pentru client.
GET /esims/{iccid}/usage — verifică oricând consumul, activarea și expirarea liniei.

Suport: Întrebări tehnice sau comerciale: [email protected]

Gata să integrezi?

Solicită acces partener — după aprobare activezi cheia sandbox și pe cea live.

Despre programul de parteneri

Întrebări tehnice sau comerciale: [email protected]