API per rivenditori eSIMDual

Utilizza l'API per rivenditori di eSIMDual nel tuo sito web o nella tua app.

Questa documentazione riguarda le API di produzione e di prova: autenticazione, pacchetti pubblici, acquisti, consegna delle eSIM, utilizzo, ricariche compatibili, annullamento delle eSIM inutilizzate, rimborsi, dati del portafoglio e webhook firmati.

Scarica il file JSON di OpenAPI Visualizza il JSON non elaborato

Avvio rapido

1Inizia in sicurezza con POST /sandbox/login
2Invia i token Bearer su tutti gli endpoint protetti
3Usa Idempotency-Key per ogni acquisto, ricarica e annullamento
4Passa alla produzione solo dopo l’approvazione del rivenditore

URL di base https://esimdual.com/api/reseller/v1

URL dell’ambiente di prova https://esimdual.com/api/reseller/v1/sandbox

Autenticazione Authorization: Bearer <token>

Idempotenza Idempotency-Key: unique-order-key

Sicurezza dell’ambiente di prova

Gli ordini di prova utilizzano un saldo fittizio ed eSIM simulate. Non contattano mai un fornitore a monte e non addebitano mai il portafoglio di produzione. Usa l’endpoint di simulazione per provare gli stati installata, attiva e consumata, quindi verifica i flussi di rimborso accettato, rifiutato e sottoposto a revisione manuale.

curl --request POST 'https://esimdual.com/api/reseller/v1/sandbox/login' \
  --header 'Content-Type: application/json' \
  --data '{"email":"partner@example.com","password":"YOUR_PASSWORD","device_name":"sandbox-ci"}'

Esempio di richiesta di accesso

curl --request POST 'https://esimdual.com/api/reseller/v1/login' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "partner@example.com",
    "password": "StrongPassword123!",
    "device_name": "production-server",
    "expires_in_days": 90
  }'

Richiesta di ordine campione

curl --request POST 'https://esimdual.com/api/reseller/v1/orders' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Idempotency-Key: ORDER-2026-0001' \
  --header 'Content-Type: application/json' \
  --data '{
    "package_id": 1120,
    "external_order_id": "NOANET-2026-0001",
    "device_imei": "356938035643809"
  }'

Flusso di ricarica compatibile

GET /esims/{id}/topup-options

POST /topups
Idempotency-Key: TOPUP-2026-0001
{
  "esim_id": "{id}",
  "package_id": 456
}

Annullamento di un’eSIM inutilizzata

POST /esims/{id}/cancel
Idempotency-Key: CANCEL-2026-0001

Automatic refund only when the supplier confirms:
- zero usage
- never installed
- never activated
- no completed recharge exists
- original wallet debit is verified

Eventi Webhook

eSIMDual firma timestamp.raw_payload con HMAC SHA-256. Il segreto viene generato da eSIMDual e mostrato solo dopo la creazione o la rotazione. Rifiuta i timestamp più vecchi di cinque minuti ed elimina i duplicati tramite X-eSIMDual-Delivery.

ping order.completed order.processing order.failed topup.completed topup.processing topup.failed esim.cancelled refund.completed refund.failed

X-eSIMDual-Event

X-eSIMDual-Delivery

X-eSIMDual-Timestamp

X-eSIMDual-Signature: v1=…

Verifica della firma PHP

$rawBody = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_ESIMDUAL_TIMESTAMP'] ?? '';
$received = $_SERVER['HTTP_X_ESIMDUAL_SIGNATURE'] ?? '';
$fresh = ctype_digit($timestamp) && abs(time() - (int) $timestamp) <= 300;
$expected = 'v1=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $webhookSecret);

if (!$fresh || !hash_equals($expected, $received)) {
    http_response_code(401);
    exit('Invalid or stale signature');
}

Memorizza ogni valore X-eSIMDual-Delivery e rifiuta le consegne duplicate. Restituisci una risposta HTTP 2xx solo dopo aver accettato l’evento.