Integrazione API

Guida rapida API

Dopo l’approvazione dell’account, il reparto vendite assegna i prezzi e abilita l’accesso API. Crea una chiave nella dashboard partner. Le chiavi di sola lettura non possono ordinare. Anche gli acquisti devono essere abilitati sull’account.

Usa una chiave bearer lato server per ogni richiesta. Non inserirla nel codice del browser o negli URL. Puoi revocarla nella dashboard partner.

Crea un ordine

Invia un UUID come Idempotency-Key. Riutilizza lo stesso UUID dopo un timeout o un errore di connessione. Invia il prezzo confermato dal cliente e conferma che il dispositivo supporta eSIM e non è bloccato dall’operatore. Le variazioni di prezzo effettivo restituiscono 409 PRICE_CHANGED. Questa è un’API operativa: gli acquisti accettati usano fondi reali del portafoglio.

POST /api/partner/v1/orders
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: 83c77d9f-395f-4ff0-8ed6-c461bda46559

{"productId":"PRODUCT_ID_FROM_CATALOG","expectedPrice":"2.25","deviceConfirmed":true}

Una risposta 201 contiene orderId ed esim; controlla esim.status ed esim.failure. Consulta l’ordine ogni 10 secondi. I fondi vengono prima riservati e poi addebitati alla consegna verificata. Una ripetizione può restituire anche un ordine non riuscito. Se l’esito del fornitore è incerto, i fondi restano riservati mentre si riconcilia l’ordine originale. I dati di installazione sono privati e appaiono solo dopo la consegna verificata.

Gli importi sono stringhe decimali in USD. Gli elenchi restituiscono items e nextCursor; continua finché nextCursor è null. Limiti: 120 richieste per chiave al minuto e 10 tentativi di acquisto per utente al minuto. Rispetta Retry-After in caso di 429. Errori comuni: 401 chiave non valida, 403 permesso negato, 402 fondi insufficienti, 404 ordine inaccessibile, 409 conflitto di prezzo o idempotenza, 503 servizio non disponibile. Consulta l’ordine originale prima di effettuare un altro acquisto.