Documentație Partner API v1

API REST pentru catalog, sold și comenzi eSIM. Cheie live mega_live_… sau sandbox mega_test_…. Nu există top-up prin API: portofelul se alimentează din portal (card sau Wise).

Autentificare: Authorization: Bearer mega_live_… · mega_test_…

Pornire rapidă

1. În portal: Dezvoltatori → cheie nouă. Sandbox-ul începe cu mega_test_ și nu debitează portofelul.

2. GET /plans și ia id-ul planului. 3. POST /orders cu idempotencyKey unic. 4. Dacă autoDelivered e false, poll GET /orders/{id} până la delivered, apoi GET /orders/{id}/esim. 5. QR-ul e câmpul qrCodeData (string LPA).

curl https://api.megaesim.us/api/v1/plans \
  -H "Authorization: Bearer mega_test_..."

curl -X POST https://api.megaesim.us/api/v1/orders \
  -H "Authorization: Bearer mega_test_..." \
  -H "Content-Type: application/json" \
  -d '{"planId":7985,"deliveryEmail":"[email protected]","idempotencyKey":"order-2026-001"}'

const res = await fetch("https://api.megaesim.us/api/v1/orders", {
  method: "POST",
  headers: {
    Authorization: "Bearer mega_test_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    planId: 7985,
    deliveryEmail: "[email protected]",
    idempotencyKey: "order-2026-001",
  }),
});
const order = await res.json();

Verificare cheie — GET /me

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

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.

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 (de la €100, fără comision, credit 1:1).

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.

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.

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.

Răspuns 200 → obiect usage: iccid, supported, status (active | inactive | paused | expired | unknown), dataPlanStatus, dataUsedMb, activatedAt, orderedAt, expiresAt, expiryKind (data_ends | install_by | after_activation), planValidityDays, dailyResetAt, refreshedAt.

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.

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.

Statusuri publice pe comandă: pending_delivery, processing, delivered, failed_refunded. Stările interne de furnizor apar ca processing.

const crypto = require("crypto");

function verifyMegaesim(secret, header, rawBody) {
  const t = String(header).match(/t=(\d+)/)?.[1];
  const v1 = String(header).match(/v1=([a-f0-9]+)/)?.[1];
  if (!t || !v1) return false;
  const expected = crypto.createHmac("sha256", secret).update(t + "." + rawBody).digest("hex");
  if (expected.length !== v1.length) return false;
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Sandbox — mega_test_

GET /me și GET /plans sunt reale (prețurile tale). GET /wallet răspunde cu balanceCents 0 și sandbox: true.

POST /orders nu debitează și nu cumpără eSIM. orderId = 900000000 + planId, fulfillmentStatus delivered, qrCodeData de test (nu se instalează).

GET /esims/{iccid}/usage pe cheie sandbox întoarce consum simulat, fără apel la furnizor.

Erori frecvente

Corpul e JSON: error (text), iar la eșecurile cunoscute și code. 402 poate include missingCents.

• 400 · bad_input — JSON invalid, planId lipsă sau activation greșit
• 401 — Cheie lipsă, invalidă, revocată sau acces API oprit
• 402 · insufficient_balance — Sold insuficient. missingCents = cât mai trebuie
• 404 · plan_not_found — Plan inexistent
• 404 · esim_not_ready — eSIM încă nelivrat — fă poll
• 404 · esim_not_found — ICCID-ul nu e în contul tău
• 404 · account_not_found — Contul cheii nu mai există
• 409 · out_of_stock — Plan fără stoc sau sold furnizor blocat
• 503 · jit_disabled — Livrarea automată e oprită temporar
• 410 · plan_inactive — Planul nu mai e de vânzare
• 409 · price_tbd — Planul nu are preț setat pe cont
• 429 — Rate limit. Răspunsul include retryAfterSec
• 503 · usage_upstream_unavailable — Consumul live 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

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

Postman

Colecția are toate endpoint-urile v1, cu variabile baseUrl și apiKey. Nu conține cheia ta.

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