API v1

Documentație de integrare API

Un singur API REST pentru a vinde eSIM-uri automat din propria ta platformă. Listezi planurile, plasezi comanda, primești instant codul QR de activare. Integrarea durează ~10 minute.

Pentru comenzile plasate prin API, platforma returnează datele de livrare în răspuns, dar nu trimite automat email către clientul final.

Base URL

https://reseller.esimnelimitat.com/api/v1

Autentificare

header x-api-key

Quick start — 3 pași

Ia planurile

GET /plans → folosește câmpul code (ex. 30nelimitat).

Plasează comanda

POST /orders cu { planId, quantity }. Se scade din wallet.

Livrează clientului

QR (câmpul qr) + PIN + APN (dacă e cazul) din răspunsul comenzii.

Autentificare

Cheia ta API o găsești în dashboard → API & Cont. Are formatul sk_live_.... Trimite-o la fiecare cerere prin header. Limită: 120 cereri / minut. Nu o publica niciodată în cod client-side.

# Varianta 1 — header dedicat
x-api-key: sk_live_xxxxxxxxxxxx

# Varianta 2 — Bearer token
Authorization: Bearer sk_live_xxxxxxxxxxxx

1. Listare planuri

GET/plans

Returnează planurile active cu stoc și preț.

curl https://reseller.esimnelimitat.com/api/v1/plans \
  -H "x-api-key: sk_live_xxxxxxxxxxxx"

Răspuns

{
  "success": true,
  "data": [
    {
      "code": "VODAFONE_400GB",
      "name": "Vodafone 400GB",
      "price": 43.99,
      "retailPrice": 43.99,
      "currency": "eur",
      "validityDays": 30,
      "dataAmount": "400GB",
      "countries": ["AT","BE","BG", "..."],
      "unlimited": true,
      "stock": null,
      "stockStatus": "in_stock",
      "requiresPin": true,
      "apn": "netmon.vodafone.it",
      "apnManual": true,
      "setupInstructions": [
        "La instalare vei fi solicitat codul PIN — este obligatoriu; fără PIN eSIM-ul nu se poate instala.",
        "Configurează manual APN-ul pe dispozitiv: netmon.vodafone.it"
      ]
    },
    {
      "code": "30nelimitat",
      "name": "eSIM nelimitat 30 zile",
      "price": 39.99,
      "dataAmount": "Nelimitat",
      "requiresPin": false,
      "apn": null,
      "apnManual": false,
      "setupInstructions": null
    }
  ]
}

Folosește câmpul code ca planId. Câmpurile requiresPin, apn și setupInstructions îți spun ce trebuie livrat clientului final înainte de cumpărare.

2. Verificare stoc

GET/stock?planId={code}

Verifică disponibilitatea înainte de a vinde (opțional).

curl "https://reseller.esimnelimitat.com/api/v1/stock?planId=30nelimitat" \
  -H "x-api-key: sk_live_xxxxxxxxxxxx"

Răspuns

{
  "success": true,
  "data": {
    "planId": "...",
    "name": "eSIM nelimitat 30 zile",
    "stock": null,
    "unlimited": true,
    "available": true,
    "status": "in_stock"
  }
}

3. Comandă eSIM

POST/orders

Cumpără unul sau mai multe eSIM-uri. Soldul din wallet se scade automat.

Body (JSON)

{
  "planId": "30nelimitat",   // codul public din /plans
  "quantity": 1               // 1–50, default 1
}

Răspuns (201)

{
  "success": true,
  "data": {
    "order": "ORD-7K3M9X",
    "quantity": 1,
    "total": 43.99,
    "walletBalance": 151.01,
    "esims": [
      {
        "iccid": "8985234202248615xxxx",
        "pin": "1234",
        "puk": null,
        "qr": "LPA:1$consumer.rsp.world$XXXXXXXX",
        "expiresAt": null,
        "requiresPin": true,
        "apn": "netmon.vodafone.it",
        "apnManual": true,
        "setupInstructions": [
          "La instalare vei fi solicitat codul PIN — este obligatoriu; fără PIN eSIM-ul nu se poate instala.",
          "Configurează manual APN-ul pe dispozitiv: netmon.vodafone.it"
        ]
      }
    ]
  }
}

Planurile Vodafone (150/200/300/400/500 GB) includ pin. Planurile 200/400/500 GB includ și apn pentru configurare manuală. Folosește aceste câmpuri în template-ul tău de livrare. Comenzile API nu declanșează email automat către clientul final.

PIN & APN — planuri Vodafone

Planurile Vodafone necesită cod PIN la instalare — fără PIN eSIM-ul nu se poate activa. Planurile 200/400/500 GB necesită și configurare manuală APN. Aceste informații apar atât în GET /plans (preview catalog), cât și în POST /orders (valori concrete per eSIM).

code	PIN obligatoriu	APN manual
VODAFONE_150GB	Da	—
VODAFONE_300GB	Da	—
VODAFONE_200GB	Da	netmon.vodafone.it
VODAFONE_400GB	Da	netmon.vodafone.it
VODAFONE_500GB	Da	netmon.vodafone.it

Câmpuri per eSIM (POST /orders)

pin — cod PIN concret (ex. "1234")
requiresPin — true pentru Vodafone
apn — APN de setat (null dacă nu e cazul)
apnManual — true = setare manuală pe telefon
setupInstructions — texte gata de afișat

Template livrare recomandat

Include în email/pagina de confirmare: cod QR (din qr) sau link de activare (din activationLink), cod PIN (din pin), și APN (din apn) când apnManual este true.

4. Livrare către clientul final

Din răspunsul POST /orders, construiește pagina sau emailul de livrare cu toate informațiile necesare instalării. Livrarea către clientul final rămâne responsabilitatea integratorului.

// Exemplu Node.js — livrare completă (QR + PIN + APN)
const esim = data.esims[0];

// 1. Generează QR din string LPA
import QRCode from "qrcode";
const qrImage = await QRCode.toDataURL(esim.qr);

// 2. Linkuri instalare directă — carddata = codul LPA brut din QR
const iosLink =
  "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=" + esim.qr;
const androidLink =
  "https://esimsetup.android.com/esim_qrcode_provisioning/?carddata=" + esim.qr;

// 3. Template livrare — include tot ce e necesar
const emailBody = `
  Scanează codul QR pentru a instala eSIM-ul.
  ${esim.requiresPin ? `Cod PIN (obligatoriu): ${esim.pin}` : ""}
  ${esim.apnManual ? `Configurează APN manual: ${esim.apn}` : ""}
  ${esim.setupInstructions?.map(l => `- ${l}`).join("\n") ?? ""}
`;

Alte endpoint-uri

GET/wallet

Soldul curent din wallet.

curl https://reseller.esimnelimitat.com/api/v1/wallet -H "x-api-key: sk_live_xxxxxxxxxxxx"
# -> { "success": true, "data": { "balance": 151.01, "currency": "eur" } }

GET/orders

Istoricul comenzilor (ultimele 200).

curl https://reseller.esimnelimitat.com/api/v1/orders -H "x-api-key: sk_live_xxxxxxxxxxxx"

GET/orders/{reference}

Detalii complete ale unei comenzi, inclusiv datele de livrare per eSIM.

curl https://reseller.esimnelimitat.com/api/v1/orders/ORD-MRGK2H4M-NVS6Z \
  -H "x-api-key: sk_live_xxxxxxxxxxxx"

Utilizare

Folosește acest endpoint pentru retry după timeout webhook sau pentru retrimiterea emailului către client, fără să mai plasezi o comandă nouă.

POST/esims/activate

Confirmă activarea unui eSIM vândut (opțional).

curl -X POST https://reseller.esimnelimitat.com/api/v1/esims/activate \
  -H "x-api-key: sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"iccid":"8985234202248615xxxx","status":"ACTIVE"}'

Coduri de eroare

La eroare răspunsul are forma { "success": false, "error": "...", "code": "..." }.

HTTP	Semnificație
401	API key lipsă sau invalidă
403	Cont blocat sau email neconfirmat
404	Plan / eSIM inexistent (PLAN_NOT_FOUND)
402	Fonduri insuficiente în wallet
409	Stoc insuficient / epuizat
422	Date invalide în request
429	Prea multe cereri (limită 120/min)

Exemplu complet — cumpărare eSIM

Cod gata de copiat — exemplu cu plan Vodafone (PIN + APN). Înlocuiește cheia cu cea proprie.

curl -X POST https://reseller.esimnelimitat.com/api/v1/orders \
  -H "x-api-key: sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"planId":"VODAFONE_400GB","quantity":1}'

Coduri de plan curente

Valoarea pe care o trimiți ca planId. Lista completă, mereu actualizată, vine din GET /plans.

code (planId)	Plan	PIN	APN
nelimitatplus	eSIM Nelimitat Plus (1Gbps+ / apoi 512Kbps)	—	—
50orange	Orange 50GB — 31 zile	—	—
100orange	Orange 100GB — 31 zile	—	—
200orange	Orange 200GB — 31 zile	—	—
300proximus	EU 300GB Proximus	—	—
VDF200GBNL	Vodafone 200GB TR,CH,UK	0000 + cod confirmare	—
30nelimitat	eSIM nelimitat 30 zile	—	—
20nelimitat	eSIM nelimitat 20 zile	—	—
10nelimitat	eSIM nelimitat 10 zile	—	—
3nelimitat	eSIM nelimitat 3 zile	—	—
VODAFONE_150GB	Vodafone 150 GB	Da	—
VODAFONE_200GB	Vodafone 200 GB	Da	netmon.vodafone.it
VODAFONE_300GB	Vodafone 300 GB	Da	—
VODAFONE_400GB	Vodafone 400 GB	Da	netmon.vodafone.it
VODAFONE_500GB	Vodafone 500 GB	Da	netmon.vodafone.it

Gata de integrare

Pentru testare interactivă folosește referința Swagger.

Swagger Cheia mea API