NovitàAPI REST con file OpenAPI 3.1
API eSIM per agenzie di viaggio, OTA e rivenditori
Vendi eSIM da viaggio con una sola API REST. Elenca i pacchetti dati per paese con i prezzi nella valuta della tua agenzia, ordinane uno per il viaggiatore, consegnagli il codice QR, segui i consumi e ricarica. Un solo URL di base serve sandbox e live. Inizia con una chiave sandbox gratuita; le chiavi live funzionano dopo l’approvazione della tua agenzia.
La documentazione è scritta in inglese.
- URL di base
https://api.fx-port.com/api/v1- Autenticazione
Authorization: Bearer fxp_test_...- Prefissi delle chiavi
fxp_test_ / fxp_live_- Endpoint
- 12
- Paesi con pacchetti
- 190+
- Linguaggi degli esempi
- 9
L’API eSIM, chiamata per chiamata
Segui la vendita di una eSIM passo dopo passo, mentre ogni richiesta viene costruita, inviata e riceve risposta. Le sessioni coprono la vendita di una eSIM, la connessione del viaggiatore, la verifica di dispositivi e prenotazioni e gli errori da gestire. Richieste e risposte sono esempi tratti dalla documentazione e questa pagina non chiama mai l’API.
3 richieste: Elenca i pacchetti, Ordina la eSIM, Leggi i dati di configurazione.
Sessione illustrativa: i body sono esempi tratti dalla documentazione, le date sono spostate in avanti per restare successive a oggi e i tempi sono indicativi. Questa pagina non invia alcuna richiesta.
Trova un pacchetto, ordinalo, leggi i dati di configurazione
Parti dai pacchetti di un paese, ordinane uno per un viaggiatore, poi leggi i dati di configurazione dell’ordine. La sandbox crea una eSIM di prova con un codice di attivazione fittizio e non addebita nulla, e la console mostra una copia ridotta della risposta del catalogo.
Elenca i pacchetti
La chiamata del catalogo accetta
countryetypee restituisce i pacchetti corrispondenti, con prezzi nella valuta della tua agenzia. Conserva ilpackage_iddi quello scelto dal viaggiatore.Richiesta GET /esims/packages curl 'https://api.fx-port.com/api/v1/esims/packages?country=france&type=local' \ -H "Authorization: Bearer fxp_test_YOUR_KEY"Risposta 200 OK · 180 ms · 3.6 KB 200 OK Content-Type: application/json Cache-Control: private, no-store X-Environment: sandbox ratelimit-limit: 6000 ratelimit-policy: 6000;w=60 { "environment": "sandbox", "success": true, "endpoint": "/packages", "data": [ { "id": "france-in-7days-1gb", "package_id": "france-in-7days-1gb", "type": "sim", "price": 402.5, "base_price": 402.5, "amount": 1024, "day": 7, "is_unlimited": false, "title": "1 GB - 7 days", "is_fair_usage_policy": false, "fair_usage_policy": null, "data": "1 GB", "voice": null, "text": null, "country_name": "France", "country_code": "FR", "country_slug": "france", // ... "operator_name": "KPN France Data only", "operator_id": 1704, // ... "operator_type": "local", "operator_is_prepaid": false, "operator_esim_type": "Prepaid", "operator_warning": null, "operator_apn_type": "automatic", "operator_is_roaming": true, // ... "operator_plan_type": "data", "operator_activation_policy": "first-usage", "operator_is_kyc_verify": false, "operator_rechargeability": true, // ... // ... 1 more // ... "is_regional": false, // ... 10 more }, // ... ], "meta": { "total_packages": 12, "filters_applied": { // ... 2 more }, "locale": "en", "agency_currency": "DZD", "currency": "DZD", "supplier_currency": "USD", "exchange_rate": 250, "commission_percentage": "12 %", "commission_rate": 12 } }Esempio abbreviato per la visualizzazione
- PASS Il codice di stato è 200
- PASS $.success è uguale a true
- PASS $.data[0].package_id esiste
- PASS $.data[0].balance_debit_amount esiste
Ordina la eSIM
Per creare un ordine servono il
package_id, l’indirizzo email e il numero di telefono del viaggiatore. Conservabooking_idedata.icciddella risposta. Nella sandbox,balanceDebited,transactionCreatedepayoutCreatedsono tuttifalse.Richiesta POST /esims/orders curl https://api.fx-port.com/api/v1/esims/orders \ -H "Authorization: Bearer fxp_test_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "package_id": "france-in-7days-1gb", "first_name": "John", "last_name": "Smith", "email": "[email protected]", "phone": "+15555550123", "description": "Order for John Smith" }'Risposta 200 OK · 900 ms · 1.5 KB 200 OK Content-Type: application/json Cache-Control: private, no-store X-Environment: sandbox ratelimit-limit: 1200 ratelimit-policy: 1200;w=60 x-fx-limit-class: booking { "environment": "sandbox", "success": true, "data": { "order": { "code": "20261101-106852", "order_id": "20261101-106852", "package_id": "france-in-7days-1gb", "type": "sim", "description": "Order for John Smith", "esim_type": "local", "created_at": "2026-11-09 15:23:22", "package": "KPN France Data only-1 GB - 7 days", "data": "1 GB", "validity": 7, "price": 468.84, "currency": "DZD", "total_price": 468.84, "retail_price": 468.84, "agency_currency": "DZD", "supplier_currency": "USD", "exchange_rate": 250, "voice": null, "text": null, "coverage": "" }, "sim": { "iccid": "8900000540463077957", "created_at": "2026-11-09 15:23:22", "lpa": "lpa.airalo.com", "imsis": null, "qrcode": "LPA:1$lpa.airalo.com$DUMMY-2610301358-iKFxr-44741", // ... "direct_apple_installation_url": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$lpa.airalo.com$DUMMY-2610301358-iKFxr-44741", "apn_type": "automatic", "apn_value": "N/A", "apn": { // ... 2 more }, "is_roaming": true, "confirmation_code": null, "msisdn": null, "sharing": { "access_code": 8803, "link": "https://esims.cloud/v8hy7-usgkq6wg" } }, "iccid": "8900000540463077957" }, "booking_id": "FX-1793546602916", "message": "eSIM order placed successfully", "balanceDebited": false, "balance_debited": false, "transactionCreated": false, "transaction_created": false, "payoutCreated": false, "payout_created": false }Esempio abbreviato per la visualizzazione
- PASS Il codice di stato è 200
- PASS $.environment è uguale a sandbox
- PASS $.balance_debited è uguale a false
- PASS $.data.iccid esiste
Leggi i dati di configurazione
La chiamata dei dati di configurazione accetta il
booking_ide restituisce il codice QR, i dati di attivazione, i link di installazione e i passaggi di installazione dell’ordine. Mostrali solo al viaggiatore proprietario della eSIM.Richiesta GET /esims/bookings/{booking_id}/setup-instructions curl https://api.fx-port.com/api/v1/esims/bookings/FX-1793546602916/setup-instructions \ -H "Authorization: Bearer fxp_test_YOUR_KEY"Risposta 200 OK · 210 ms · 1.8 KB 200 OK Content-Type: application/json Cache-Control: private, no-store X-Environment: sandbox ratelimit-limit: 6000 ratelimit-policy: 6000;w=60 { "environment": "sandbox", "success": true, "data": { "code": "20261101-106852", "order_id": "20261101-106852", "currency": "DZD", "package_id": "france-in-7days-1gb", "quantity": 1, "type": "sim", "description": "Order for John Smith", "esim_type": "local", "validity": 7, "package": "KPN France Data only-1 GB - 7 days", "data": "1 GB", "price": 468.84, "created_at": "2026-11-09 15:23:22", // ... "installation_guides": { "en": "https://www.airalo.com/help/getting-started-with-airalo" }, "text": null, "voice": null, "sims": [ { "created_at": "2026-11-09 15:23:22", "iccid": "8900000540463077957", "lpa": "lpa.airalo.com", "imsis": null, "qrcode": "LPA:1$lpa.airalo.com$DUMMY-2610301358-iKFxr-44741", // ... "apn_type": "automatic", "apn_value": "N/A", "is_roaming": true, "confirmation_code": null, "apn": { "ios": { "apn_type": "automatic", "apn_value": "N/A" }, "android": { "apn_type": "automatic", "apn_value": "N/A" } }, "msisdn": null, "direct_apple_installation_url": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$lpa.airalo.com$DUMMY-2610301358-iKFxr-44741", "direct_android_installation_url": "https://esimsetup.android.com/esim_qrcode_provisioning?carddata=LPA:1$lpa.airalo.com$DUMMY-2610301358-iKFxr-44741", "sharing": { "access_code": 8803, "link": "https://esims.cloud/v8hy7-usgkq6wg" } } ], "total_price": 468.84, "retail_price": 468.84, "agency_currency": "DZD" } }Esempio abbreviato per la visualizzazione
- PASS Il codice di stato è 200
- PASS $.data.package_id è uguale a france-in-7days-1gb
- PASS $.data.sims[0].iccid esiste
Riferimento di GET /esims/bookings/{booking_id}/setup-instructions nella documentazione
Leggi i consumi, poi ricarica
Quando un viaggiatore ha una eSIM, leggi quanti dati restano, chiedi quali pacchetti si possono aggiungere proprio a quella eSIM, poi crea la ricarica. I consumi sono in cache, quindi un valore può essere vecchio di alcuni minuti. Lo storico delle ricariche si trova nella barra laterale e nella trascrizione.
Leggi i consumi
La chiamata dei consumi accetta l’ICCID dell’ordine e restituisce
remainingetotalin megabyte, lostatuse la scadenza. La risposta viene da una cache eforce=trueinterroga di nuovo il fornitore.Richiesta GET /esims/usage/{iccid} curl https://api.fx-port.com/api/v1/esims/usage/8900000540463077957 \ -H "Authorization: Bearer fxp_test_YOUR_KEY"Risposta 200 OK · 160 ms · 261 B 200 OK { "environment": "sandbox", "success": true, "data": { "data": { "remaining": 1024, "total": 1024, "expired_at": "2026-11-16 15:23:29", "is_unlimited": false, "status": "ACTIVE", "remaining_voice": 0, "remaining_text": 0, "total_voice": 0, "total_text": 0 }, "meta": { "message": "success" } } }- PASS Il codice di stato è 200
- PASS $.data.data.status è uguale a ACTIVE
- PASS $.data.data.remaining esiste
Riferimento di GET /esims/usage/{iccid} nella documentazione
Elenca i pacchetti di ricarica
Questa chiamata elenca i pacchetti che oggi si possono aggiungere proprio a questa eSIM. Un elenco vuoto significa che la eSIM ora non può essere ricaricata. Prendi il
package_iddella ricarica da questo elenco, mai dall’ordine originale.Richiesta GET /esims/topup-packages/{iccid} curl https://api.fx-port.com/api/v1/esims/topup-packages/8900000540463077957 \ -H "Authorization: Bearer fxp_test_YOUR_KEY"Risposta 200 OK · 240 ms · 1.1 KB 200 OK { "environment": "sandbox", "success": true, "data": { "data": [ { "id": "france-in-7days-1gb-topup", "package_id": "france-in-7days-1gb-topup", "type": "topup", "price": 468.84, "amount": 1024, "day": 7, "is_unlimited": false, "title": "1 GB - 7 days", "data": "1 GB", "short_info": null, // ... 12 more }, { // ... 22 more } ] } }Esempio abbreviato per la visualizzazione
- PASS Il codice di stato è 200
- PASS $.data.data contiene 2 elementi
- PASS $.data.data[0].type è uguale a topup
Riferimento di GET /esims/topup-packages/{iccid} nella documentazione
Crea la ricarica
Per creare una ricarica servono il
package_iddi quell’elenco e l’ICCID. Su live il saldo viene addebitato solo dopo che il fornitore l’ha accettata. Nella sandbox ilbalancedella risposta è zero e non viene addebitato nulla.Richiesta POST /esims/topups curl https://api.fx-port.com/api/v1/esims/topups \ -H "Authorization: Bearer fxp_test_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "package_id": "france-in-7days-1gb-topup", "iccid": "8900000540463077957", "first_name": "John", "last_name": "Smith", "email": "[email protected]", "phone": "+15555550123" }'Risposta 200 OK · 900 ms · 682 B 200 OK { "environment": "sandbox", "success": true, "data": { "topup": { "code": "20261101-106853", "order_id": "20261101-106853", "package_id": "france-in-7days-1gb-topup", // ... 10 more }, "iccid": "8900000540463077957", "balance": { // ... 3 more } }, "booking_id": "FX-1793546625391", "message": "eSIM topup completed successfully", "balanceDebited": false, "balance_debited": false, "transactionCreated": false, "transaction_created": false, "payoutCreated": false, "payout_created": false }- PASS Il codice di stato è 200
- PASS $.environment è uguale a sandbox
- PASS $.balance_debited è uguale a false
- PASS $.data.balance.current è uguale a 0
Leggi lo storico delle ricariche
Lo storico delle ricariche elenca le ricariche di una eSIM, dalla più recente. Le ricariche non sono nell’elenco delle prenotazioni, quindi è qui che le trovi.
Richiesta GET /esims/bookings/{iccid}/topup-history curl https://api.fx-port.com/api/v1/esims/bookings/8900000540463077957/topup-history \ -H "Authorization: Bearer fxp_test_YOUR_KEY"Risposta 200 OK · 130 ms · 615 B 200 OK { "environment": "sandbox", "success": true, "data": [ { "id": "bd6ff7d7-392f-4d56-8dea-4f0f3dff0af9", "booking_id": "FX-1793546625391", "order_id": "20261101-106853", "status": "confirmed", "currency": "DZD", "total_price": 468.84, "agency_commission": 50.24, "type": "topup", "package_name": "1 GB - 7 days", "iccid": "8900000540463077957", "customer_email": "[email protected]", "customer_first_name": "John", "customer_last_name": "Smith", "customer_phone": "+15555550123", "provider_name": "Airalo", // ... 4 more } ] }- PASS Il codice di stato è 200
- PASS $.data[0].type è uguale a topup
Riferimento di GET /esims/bookings/{iccid}/topup-history nella documentazione
Controlla un dispositivo, poi leggi le prenotazioni
Prima della vendita, verifica che il telefono del viaggiatore supporti la eSIM. Dopo la vendita, leggi le tue prenotazioni e verifica che un riferimento di prenotazione sia tuo. I consumi in blocco sono elencati nella barra laterale.
Controlla l’elenco dei dispositivi
La chiamata dei dispositivi compatibili restituisce i dispositivi noti per supportare la eSIM, con
brand,modeleos. Cerca il telefono del viaggiatore prima di vendere.Richiesta GET /esims/compatible-devices curl https://api.fx-port.com/api/v1/esims/compatible-devices \ -H "Authorization: Bearer fxp_test_YOUR_KEY"Risposta 200 OK · 120 ms · 283 B 200 OK { "environment": "sandbox", "success": true, "data": [ { "model": "T803D", "os": "android", "brand": "Alcatel", "name": "V3 Ultra" }, { "model": "iPhone15,2", "os": "ios", "brand": "Apple", "name": "iPhone 14 Pro" } ], "meta": { "total_devices": 631, "cached_at": "2026-11-09T15:07:43.957236", "cache_age_days": 0.01 } }- PASS Il codice di stato è 200
- PASS $.success è uguale a true
- PASS $.data[0].model esiste
Riferimento di GET /esims/compatible-devices nella documentazione
Elenca le prenotazioni
L’elenco delle prenotazioni restituisce gli ordini eSIM della tua agenzia, dal più recente. Questa richiesta chiede una prenotazione con
limit, epaginationindica quanti ordini corrispondono e se segue un’altra pagina.Richiesta GET /esims/bookings curl 'https://api.fx-port.com/api/v1/esims/bookings?limit=1' \ -H "Authorization: Bearer fxp_test_YOUR_KEY"Risposta 200 OK · 150 ms · 714 B 200 OK { "environment": "sandbox", "success": true, "data": [ { "id": "639417b4-b103-4ece-bd5d-850315322278", "booking_id": "FX-1793546602916", "order_id": "20261101-106852", "status": "confirmed", "currency": "DZD", // ... 4 more "iccid": "8900000540463077957", // ... 9 more } ], "pagination": { "total": 61, "page": 1, "limit": 1, "pages": 61, "total_pages": 61, "has_more": true } }- PASS Il codice di stato è 200
- PASS $.data contiene 1 elemento
- PASS $.pagination.has_more è uguale a true
Verifica la proprietà
La verifica di proprietà risponde
is_ownertrue quando la prenotazione appartiene alla tua agenzia. Una prenotazione di un’altra agenzia e una inesistente ricevono la stessa risposta, quindi la chiamata non serve a scoprire riferimenti.Richiesta GET /esims/bookings/{booking_id}/verify curl https://api.fx-port.com/api/v1/esims/bookings/FX-1793546602916/verify \ -H "Authorization: Bearer fxp_test_YOUR_KEY"Risposta 200 OK · 90 ms · 167 B 200 OK { "environment": "sandbox", "isOwner": true, "is_owner": true, "userAgencyId": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d", "bookingAgencyId": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d" }- PASS Il codice di stato è 200
- PASS $.is_owner è uguale a true
Riferimento di GET /esims/bookings/{booking_id}/verify nella documentazione
Leggi i consumi in blocco
Una chiamata legge i consumi di più eSIM elencate in
iccidse restituisce una voce per ICCID, ciascuna con il propriostatus. Invia sempreiccids.Richiesta GET /esims/usage/bulk curl 'https://api.fx-port.com/api/v1/esims/usage/bulk?iccids=8900000540463077957' \ -H "Authorization: Bearer fxp_test_YOUR_KEY"Risposta 200 OK · 220 ms · 321 B 200 OK { "environment": "sandbox", "success": true, "data": [ { "iccid": "8900000540463077957", "data": { "data": { "remaining": 1024, "total": 1024, "expired_at": "2026-11-16 15:23:29", "is_unlimited": false, "status": "ACTIVE", "remaining_voice": 0, // ... 3 more }, "meta": { "message": "success" } }, "status": "success" } ] }- PASS Il codice di stato è 200
- PASS $.data[0].status è uguale a success
Gli errori e come reagire a ciascuno
Tutti gli errori condividono un unico corpo e la prima voce di errors ha un code stabile. Queste chiamate d’ordine falliscono di proposito, ciascuna per un motivo diverso e con una reazione diversa.
Chiave Lettura su un ordine
Una chiave Lettura sulla chiamata dell’ordine viene rifiutata con
403eread_write_permission_required, prima che il corpo venga letto. Passa a una chiave Lettura + scrittura.Richiesta POST /esims/orders curl https://api.fx-port.com/api/v1/esims/orders \ -H "Authorization: Bearer fxp_test_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "package_id": "france-in-7days-1gb", "first_name": "John", "last_name": "Smith", "email": "[email protected]", "phone": "+15555550123", "description": "Order for John Smith" }'Risposta 403 Forbidden · 90 ms · 456 B 403 Forbidden { "environment": "sandbox", "success": false, "errors": [ { "code": "read_write_permission_required", "type": "permission_error", "title": "Read write permission required", "message": "This endpoint requires an API key with read_write permission.", "field": null, "details": {}, "documentation_url": "https://fx-port.com/docs/errors#read_write_permission_required" } ], "meta": { "request_id": "req_7f0c2e9a41b84d6e8a35c1d2", "status": 403 }, "request_id": "req_7f0c2e9a41b84d6e8a35c1d2" }- PASS Il codice di stato è 403
- PASS Il codice di errore è read_write_permission_required
- PASS $.errors[0].type è uguale a permission_error
Indirizzo email non valido
Un valore che non è un indirizzo email viene rifiutato con
400einvalid_email, efieldindicaemail. Correggi il valore prima di inviare di nuovo l’ordine: la stessa richiesta fallisce allo stesso modo.Richiesta POST /esims/orders curl https://api.fx-port.com/api/v1/esims/orders \ -H "Authorization: Bearer fxp_test_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "package_id": "france-in-7days-1gb", "first_name": "John", "last_name": "Smith", "email": "traveler-at-example.com", "phone": "+15555550123", "description": "Order for John Smith" }'Risposta 400 Bad Request · 100 ms · 381 B 400 Bad Request { "environment": "sandbox", "success": false, "errors": [ { "code": "invalid_email", "type": "validation_error", "title": "Invalid email", "message": "email is not a valid email address", "field": "email", "details": {}, "documentation_url": "https://fx-port.com/docs/errors#invalid_email" } ], "meta": { "request_id": "req_7f0c2e9a41b84d6e8a35c1d2", "status": 400 }, "request_id": "req_7f0c2e9a41b84d6e8a35c1d2" }- PASS Il codice di stato è 400
- PASS Il codice di errore è invalid_email
- PASS $.errors[0].field è uguale a email
Ordine duplicato
Un ordine per un pacchetto già in elaborazione viene rifiutato con
409eduplicate_request. Non inviarlo subito di nuovo: cerca prima la prenotazione e ordina di nuovo solo se non ne è stata creata nessuna.Richiesta POST /esims/orders curl https://api.fx-port.com/api/v1/esims/orders \ -H "Authorization: Bearer fxp_test_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "package_id": "france-in-7days-1gb", "first_name": "John", "last_name": "Smith", "email": "[email protected]", "phone": "+15555550123", "description": "Order for John Smith" }'Risposta 409 Conflict · 110 ms · 423 B 409 Conflict { "environment": "sandbox", "success": false, "errors": [ { "code": "duplicate_request", "type": "conflict", "title": "Duplicate request", "message": "An identical order is already being processed. Please wait before retrying.", "field": null, "details": {}, "documentation_url": "https://fx-port.com/docs/errors#duplicate_request" } ], "meta": { "request_id": "req_7f0c2e9a41b84d6e8a35c1d2", "status": 409 }, "request_id": "req_7f0c2e9a41b84d6e8a35c1d2" }- PASS Il codice di stato è 409
- PASS Il codice di errore è duplicate_request
- PASS $.errors[0].type è uguale a conflict
Troppe richieste
Oltre il limite al minuto, la chiamata viene rifiutata con
429erate_limit_exceeded, e l’headerRetry-Afterindica quanti secondi attendere. Poi riprova con backoff.Richiesta POST /esims/orders curl https://api.fx-port.com/api/v1/esims/orders \ -H "Authorization: Bearer fxp_test_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "package_id": "france-in-7days-1gb", "first_name": "John", "last_name": "Smith", "email": "[email protected]", "phone": "+15555550123", "description": "Order for John Smith" }'Risposta 429 Too Many Requests · 80 ms · 504 B 429 Too Many Requests Retry-After: 12 { "environment": "sandbox", "success": false, "errors": [ { "code": "rate_limit_exceeded", "type": "rate_limit_error", "title": "Rate limit exceeded", "message": "Too many requests hit the API too quickly. Please retry your request after the time specified in the `ratelimit-reset` header.", "field": null, "details": { "retry_after": 12 }, "documentation_url": "https://fx-port.com/docs/errors#rate_limit_exceeded" } ], "meta": { "request_id": "req_7f0c2e9a41b84d6e8a35c1d2", "status": 429 }, "request_id": "req_7f0c2e9a41b84d6e8a35c1d2" }- PASS Il codice di stato è 429
- PASS Il codice di errore è rate_limit_exceeded
- PASS L’header Retry-After è presente
- PASS $.errors[0].details.retry_after è uguale a 12
Dal catalogo al viaggiatore connesso in cinque passaggi
Un’integrazione è un percorso breve: leggi il catalogo, crea l’ordine, consegna la eSIM al viaggiatore, segui i consumi e ricarica quando i dati finiscono. Solo l’ordine e la ricarica modificano qualcosa. Ogni altra chiamata si limita a leggere.
Leggi il catalogo di una destinazione
Elenca i pacchetti di un paese, con i prezzi già nella valuta della tua agenzia, e conserva il package_id di quello scelto dal viaggiatore. Invia sempre country: l’intero catalogo è una risposta molto grande e senza paginazione. Leggi gli id dei pacchetti dalla risposta invece di scriverli nel codice, perché il catalogo cambia.
Richiesta
curl 'https://api.fx-port.com/api/v1/esims/packages?country=france&type=local' \
-H "Authorization: Bearer fxp_test_YOUR_KEY"Risposta 200 OK
{
"environment": "sandbox",
"success": true,
"endpoint": "/packages",
"data": [
{
"id": "france-in-7days-1gb",
"package_id": "france-in-7days-1gb",
"type": "sim",
"price": 402.5,
"base_price": 402.5,
// ... 28 more
"total_price": 468.84,
"balance_debit_amount": 418.6,
"b2b_price": 418.6,
"agency_commission": "12 %",
"commission_rate": 12,
"currency": "DZD",
// ... 2 more
},
// ...
],
"meta": {
"total_packages": 12,
"filters_applied": {
// ... 2 more
},
"locale": "en",
"agency_currency": "DZD",
"currency": "DZD",
"supplier_currency": "USD",
"exchange_rate": 250,
"commission_percentage": "12 %",
"commission_rate": 12
}
}Crea l’ordine
Invia il package_id con l’indirizzo email e il numero di telefono del viaggiatore. Un ordine crea esattamente una eSIM e, su live, addebita il saldo della tua agenzia. Conserva il booking_id e l’ICCID della risposta, perché ogni chiamata successiva ne richiede uno.
Richiesta
curl https://api.fx-port.com/api/v1/esims/orders \
-H "Authorization: Bearer fxp_test_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"package_id": "france-in-7days-1gb",
"first_name": "John",
"last_name": "Smith",
"email": "[email protected]",
"phone": "+15555550123",
"description": "Order for John Smith"
}'Risposta 200 OK
{
"environment": "sandbox",
"success": true,
"data": {
"order": {
"code": "20261101-106852",
"order_id": "20261101-106852",
"package_id": "france-in-7days-1gb",
// ... 17 more
},
"sim": {
// ... 4 more
"qrcode": "LPA:1$lpa.airalo.com$DUMMY-2610301358-iKFxr-44741",
// ... 7 more
"sharing": {
"access_code": 8803,
"link": "https://esims.cloud/v8hy7-usgkq6wg"
}
},
"iccid": "8900000540463077957"
},
"booking_id": "FX-1793546602916",
"message": "eSIM order placed successfully",
"balanceDebited": false,
"balance_debited": false,
"transactionCreated": false,
"transaction_created": false,
"payoutCreated": false,
"payout_created": false
}| Campo | Che cosa contiene |
|---|---|
booking_id | Il riferimento FX-Port dell’ordine. Conservalo per i dati di configurazione, la verifica di proprietà e i tuoi registri. |
data.iccid | L’identificativo della eSIM. Consumi, ricariche e istruzioni di installazione si richiedono tutti tramite ICCID. |
data.sim.qrcode data.sim.qrcode_url | La stringa di attivazione codificata nel codice QR e un link all’immagine del codice QR. |
data.sim.direct_apple_installation_url data.sim.sharing | Un link che avvia l’installazione su iPhone e una pagina di condivisione in cui il viaggiatore può aprire la eSIM con il suo codice di accesso. La chiamata dei dati di configurazione aggiunge il link per Android. |
PENDING- e i dati sono disponibili dalla chiamata dei dati di configurazione appena il fornitore li ha.Consegna la eSIM al viaggiatore
La risposta contiene il codice QR e la sua stringa di attivazione, così puoi mostrarli nelle tue schermate. FX-Port chiede inoltre al fornitore di inviare per email il codice QR e un link di condivisione all’indirizzo del viaggiatore, quindi non devi inoltrarlo tu. La chiamata dei dati di configurazione restituisce gli stessi dati anche in seguito, con i passaggi di installazione.
Richiesta
curl https://api.fx-port.com/api/v1/esims/bookings/FX-1793546602916/setup-instructions \
-H "Authorization: Bearer fxp_test_YOUR_KEY"Risposta 200 OK
{
"environment": "sandbox",
"success": true,
"data": {
"code": "20261101-106852",
"order_id": "20261101-106852",
"currency": "DZD",
"package_id": "france-in-7days-1gb",
"quantity": 1,
"type": "sim",
"description": "Order for John Smith",
"esim_type": "local",
"validity": 7,
"package": "KPN France Data only-1 GB - 7 days",
"data": "1 GB",
// ... 5 more
"sims": [
{
"created_at": "2026-11-09 15:23:22",
"iccid": "8900000540463077957",
// ... 2 more
"qrcode": "LPA:1$lpa.airalo.com$DUMMY-2610301358-iKFxr-44741",
// ... 6 more
"direct_apple_installation_url": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$lpa.airalo.com$DUMMY-2610301358-iKFxr-44741",
// ... 2 more
}
],
// ... 3 more
}
}Segui i consumi
Leggi i dati residui e la scadenza di una eSIM tramite il suo ICCID. La risposta è in cache fino a 15 minuti: usala per una schermata o un promemoria, non come contatore.
Richiesta
curl https://api.fx-port.com/api/v1/esims/usage/8900000540463077957 \
-H "Authorization: Bearer fxp_test_YOUR_KEY"Risposta 200 OK
{
"environment": "sandbox",
"success": true,
"data": {
"data": {
"remaining": 1024,
"total": 1024,
"expired_at": "2026-11-16 15:23:29",
"is_unlimited": false,
"status": "ACTIVE",
"remaining_voice": 0,
"remaining_text": 0,
"total_voice": 0,
"total_text": 0
},
"meta": {
"message": "success"
}
}
}Ricarica quando i dati finiscono
Elenca i pacchetti che si possono aggiungere proprio a questa eSIM, poi crea la ricarica con uno di essi. Se l’elenco è vuoto, la eSIM non può essere ricaricata ora e il viaggiatore ha bisogno di una nuova.
Richiesta
curl https://api.fx-port.com/api/v1/esims/topups \
-H "Authorization: Bearer fxp_test_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"package_id": "france-in-7days-1gb-topup",
"iccid": "8900000540463077957",
"first_name": "John",
"last_name": "Smith",
"email": "[email protected]",
"phone": "+15555550123"
}'Risposta 200 OK
{
"environment": "sandbox",
"success": true,
"data": {
"topup": {
"code": "20261101-106853",
"order_id": "20261101-106853",
"package_id": "france-in-7days-1gb-topup",
"package": "KPN France Data only-1 GB - 7 days",
"data": "1 GB",
"validity": 7,
"price": 468.84,
// ... 6 more
},
"iccid": "8900000540463077957",
"balance": {
"previous": 0,
"current": 0,
"currency": "DZD"
}
},
"booking_id": "FX-1793546625391",
"message": "eSIM topup completed successfully",
"balanceDebited": false,
"balance_debited": false,
"transactionCreated": false,
"transaction_created": false,
"payoutCreated": false,
"payout_created": false
}Prezzi, commissione e saldo
Ogni pacchetto riporta i propri campi monetari, calcolati sul server nella valuta della tua agenzia. Un prezzo nel corpo della richiesta viene ignorato, quindi un ordine viene sempre creato al prezzo calcolato dal server.
| Campo | Che cosa contiene |
|---|---|
base_price price | Il prezzo del pacchetto prima della tua commissione. Non è l’importo addebitato sul tuo saldo. |
total_price retail_price | Il prezzo da far pagare al viaggiatore, con la tua commissione inclusa. |
balance_debit_amount b2b_price | Ciò che esce dal saldo della tua agenzia quando ordini il pacchetto su live. Leggilo, non calcolarlo. |
agency_commission commission_rate | La tua percentuale di commissione, come testo e come numero. Le prenotazioni restituiscono invece la tua commissione come importo. |
Nell’esempio del catalogo il viaggiatore paga 468.84 DZD. Un ordine su live addebita 418.60 DZD sul tuo saldo e la differenza, 50.24 DZD, è la tua commissione.
La percentuale appartiene alla tua agenzia
La percentuale di commissione torna con ogni pacchetto e non è uguale per tutte le agenzie. Un’agenzia corporate con contratto può avere una percentuale pari a zero e allora il prezzo totale coincide con l’addebito.
Leggi i campi, non ricostruirli
L’addebito può essere superiore al prezzo base, perché ne fanno parte importi specifici della tua agenzia. Leggi quindi balance_debit_amount e non calcolarlo mai da base_price. La parola price è il prezzo base nel catalogo, ma il prezzo al pubblico negli ordini, nei pacchetti di ricarica e nei dati di configurazione: usa base_price e total_price ovunque e l’ambiguità sparisce.
Prezzi nella valuta della tua agenzia
Ogni importo è già convertito nella valuta della tua agenzia, qualunque sia la valuta del fornitore. La risposta mostra anche la valuta del fornitore e il tasso di cambio, così puoi verificare il tasso da solo e non devi più convertire nulla.
Dopo la vendita: consumi, ricariche e dati di configurazione
Una vendita non finisce con l’ordine. Queste chiamate mantengono il viaggiatore connesso e funzionano solo sulle eSIM ordinate dalla tua agenzia nello stesso ambiente della tua chiave.
Leggere i consumi e quanto sono aggiornati
I consumi restituiscono i dati residui, il totale incluso, lo stato e la scadenza di una eSIM, oppure di un massimo di 50 eSIM in una sola chiamata. FX-Port conserva l’ultima risposta fino a 15 minuti per proteggere i rate limit del fornitore, quindi un valore può avere quell’età. Passa force=true per interrogare di nuovo il fornitore, per esempio subito dopo una ricarica. Non farlo a ogni richiesta, perché il fornitore limita la frequenza di lettura dei consumi. Se il fornitore non risponde, ricevi l’ultimo valore noto contrassegnato come non aggiornato.
Ricariche: prima chiedi, poi crea
Una ricarica richiede due chiamate. Prima elenca i pacchetti che si possono aggiungere proprio a questa eSIM, poi crea la ricarica con uno degli id restituiti. Non riutilizzare mai l’id del pacchetto dell’ordine originale e non conservare un pacchetto di ricarica per dopo: chiedi di nuovo quando il viaggiatore vuole ricaricare. Una ricarica aggiunge dati alla eSIM e non sostituisce quelli rimasti, quindi leggi il risultato dai consumi con force=true.
Quando una ricarica non è possibile
I fornitori scelgono quali operatori mobili servono un paese e, in rari casi, ne cambiano uno. La eSIM può allora continuare a funzionare fino alla scadenza, mentre il suo pacchetto non può più essere ricaricato. L’elenco dei pacchetti di ricarica torna vuoto. Se un fornitore rifiuta una ricarica, il tuo saldo non viene toccato e il tentativo viene salvato come prenotazione non riuscita. La risposta è un supplier_error a cui puoi reagire.
Dati di configurazione e passaggi di installazione
La chiamata dei dati di configurazione restituisce, quando ti servono, il codice QR, i dati di attivazione, i link di installazione e i passaggi di installazione di un ordine. La chiamata delle istruzioni restituisce i passaggi per sistema operativo, nella lingua richiesta. I passaggi sono un testo generico del fornitore, quindi mostrali accanto al codice QR dell’ordine. Mostra entrambi solo al viaggiatore proprietario della eSIM.
Prenotazioni, storico delle ricariche e proprietà
L’elenco delle prenotazioni restituisce gli ordini eSIM della tua agenzia nell’ambiente della tua chiave, dal più recente. Puoi cercare per id prenotazione, nome del viaggiatore, indirizzo email, nome del pacchetto o ICCID. Le ricariche non sono in quell’elenco: leggile con lo storico delle ricariche di una eSIM. Prima di costruire un link o una schermata attorno a un id prenotazione, la verifica di proprietà ti dice se è tuo. Una prenotazione di un’altra agenzia e una inesistente ricevono la stessa risposta.
Tutti gli endpoint eSIM, con OpenAPI, Postman ed esempi di codice
L’API eSIM ha 12 endpoint sotto un solo URL di base. Ogni riga apre la pagina di riferimento di quella chiamata, con campi della richiesta, risposte, errori ed esempi in 9 linguaggi.
| Endpoint | Cosa fa | Chiave |
|---|---|---|
GET /api/v1/esims/packages | Elenca i pacchetti di un paese o di una regione, con prezzi già nella valuta della tua agenzia. Invia sempre un paese: l’intero catalogo è molto grande e senza paginazione. | Lettura |
GET /api/v1/esims/compatible-devices | I dispositivi noti per supportare la eSIM, per un controllo prima dell’acquisto del viaggiatore. | Lettura |
POST /api/v1/esims/orders | Crea una eSIM da un pacchetto per un viaggiatore e la attiva presso il fornitore. Su live addebita il saldo della tua agenzia. | Lettura+Scrittura |
GET /api/v1/esims/topup-packages/{iccid} | I pacchetti che oggi si possono aggiungere a una eSIM precisa. Un elenco vuoto significa che ora non può essere ricaricata. | Lettura |
POST /api/v1/esims/topups | Aggiunge un pacchetto di ricarica a una eSIM esistente. Su live il saldo viene addebitato solo dopo che il fornitore l’ha accettato. | Lettura+Scrittura |
GET /api/v1/esims/usage/{iccid} | I dati residui, il totale incluso, lo stato e la scadenza di una eSIM. La risposta può essere vecchia fino a 15 minuti. | Lettura |
GET /api/v1/esims/usage/bulk | I consumi di un massimo di 50 eSIM in una sola chiamata, una voce per ICCID, ciascuna con il proprio stato. | Lettura |
GET /api/v1/esims/bookings | Gli ordini eSIM della tua agenzia, dal più recente, con ricerca e paginazione. Le ricariche non sono in questo elenco. | Lettura |
GET /api/v1/esims/bookings/{iccid}/topup-history | Le ricariche di una eSIM, dalla più recente. L’elenco è vuoto se la eSIM non ne ha. | Lettura |
GET /api/v1/esims/bookings/{booking_id}/verify | Verifica che un riferimento di prenotazione appartenga alla tua agenzia, prima di costruire un link o una schermata attorno ad esso. | Lettura |
GET /api/v1/esims/bookings/{booking_id}/setup-instructions | Il codice QR, i dati di attivazione, i link di installazione e i passaggi di installazione di un ordine, in JSON. | Lettura |
GET /api/v1/esims/instructions/{iccid} | Istruzioni di installazione passo dopo passo per un ICCID, per sistema operativo, nella lingua richiesta. | Lettura |
OpenAPI 3.1
Un solo file descrive ogni endpoint e ogni campo. Generaci un client, importalo in uno strumento per API o consegnalo a un assistente di programmazione.
Collection Postman
La collection eSIM copre tutti i 12 endpoint in cartelle che seguono le fasi di una vendita. Non contiene chiavi, quindi aggiungi le tue.
Esempi di codice in 9 linguaggi
Ogni pagina di riferimento riporta la propria richiesta in cURL, Node.js, Python, PHP, Go, Java, C#, Swift e Kotlin, generata dalla descrizione OpenAPI. Ogni richiesta eSIM è disponibile in tutti.
Documentazione per assistenti IA
llms.txt e llms-full.txt offrono agli assistenti IA la documentazione come testo semplice, e ogni pagina della documentazione si legge in Markdown aggiungendo .md al suo indirizzo.
Pronta per la produzione: chiavi, errori, nuovi tentativi e cache
Un’integrazione eSIM si valuta in produzione su autenticazione, errori, nuovi tentativi, cache e rate limit. Ecco che cosa sapere su ciascuno.
Un solo URL di base, due tipi di chiave
Ogni richiesta porta una chiave come bearer token nell’header Authorization. Il prefisso indica dove funziona la chiave: fxp_test_ per la sandbox e fxp_live_ per live. Entrambe usano lo stesso URL di base e ogni risposta JSON indica in environment l’ambiente da cui proviene. Le chiavi vanno tenute sul tuo server, mai in un browser o in un’app. FX-Port conserva solo un hash di ogni chiave, quindi una chiave persa non può essere mostrata di nuovo. Una modifica a una chiave può richiedere alcuni minuti per essere applicata.
Quale chiave fa quale chiamata
Una chiave Lettura può elencare i pacchetti, controllare i dispositivi, leggere i consumi e leggere le prenotazioni. Creare un ordine o una ricarica richiede una chiave Lettura + scrittura, e una chiave Lettura che ci prova riceve read_write_permission_required. Qualsiasi chiave può essere vincolata a un elenco di indirizzi IP e una chiamata da un altro indirizzo riceve ip_not_allowed. Usa una chiave Lettura ovunque il codice si limiti a mostrare risultati.
Un unico formato per tutti gli errori
Una chiamata fallita restituisce un array errors. La prima voce ha un code stabile, un type che indica come reagire e il field in errore. Verifica il codice, mai il messaggio. L’elenco di errori condiviso da voli, hotel, eSIM e account contiene 180 codici. Quando il fornitore rifiuta un ordine o una ricarica, la risposta è un supplier_error con lo stato HTTP del fornitore stesso. Nulla viene addebitato e viene salvata una prenotazione non riuscita. Subito dopo un riavvio, il catalogo e l’elenco dei dispositivi possono rispondere 202 con success impostato a false: attendi qualche secondo e riprova.
Riprovare senza ordinare due volte
FX-Port non ha una chiave di idempotenza, quindi non esiste un header Idempotency-Key da inviare. Le letture si possono ripetere senza rischi; creare un ordine o una ricarica no. FX-Port rifiuta un duplicato evidente con 409 e duplicate_request: un ordine per un pacchetto ancora in elaborazione. Su live rifiuta anche lo stesso pacchetto ordinato di nuovo entro 60 secondi dall’ultimo ordine confermato della tua agenzia, chiunque sia il viaggiatore. Gli ordini di solito rispondono in pochi secondi, ma un fornitore lento può impiegare molto di più. Se una chiamata va in timeout o la connessione cade, non inviare subito di nuovo l’ordine, perché la eSIM potrebbe esistere. Cercala con il parametro search dell’elenco delle prenotazioni, usando l’indirizzo email del viaggiatore, e ordina di nuovo solo se non è stato creato nulla.
Nessun webhook: chiedi quando ti serve
FX-Port non chiama alcun URL tuo, né in sandbox né su live. Un ordine risponde con la eSIM, oppure con un segnaposto PENDING- finché il fornitore non l’ha restituita. Tutto il resto lo chiedi tu quando ti serve: i dati di configurazione, i consumi o l’elenco delle prenotazioni.
Cache e velocità
I consumi vengono conservati fino a 15 minuti e l’elenco dei pacchetti di ricarica per alcuni minuti, mentre force=true salta la cache. Il catalogo senza filtri è una risposta molto grande e senza paginazione, quindi invia country e accetta la compressione con Accept-Encoding: gzip. I titoli dei pacchetti tornano nella lingua del parametro locale; la prima richiesta in una lingua diversa dall’inglese è più lenta, perché il testo viene recuperato in quel momento e poi messo in cache.
Rate limit
I limiti sono conteggiati per chiave e al minuto in due gruppi, e ogni risposta contiene ratelimit-limit e ratelimit-remaining, così puoi rallentare prima di essere rifiutato. Dopo un 429, attendi i secondi indicati in Retry-After e riprova con backoff esponenziale e jitter. Troppi ordini o ricariche della stessa chiave o della stessa agenzia in esecuzione contemporaneamente possono ricevere come risposta concurrency_limit_exceeded.
| Tipo di chiamata | Al minuto |
|---|---|
| Creazione di ordini e ricariche | 1,200 |
| Ogni altro endpoint eSIM | 6,000 |
Per ora il limite agli ordini e alle ricariche in esecuzione contemporaneamente è in modalità di osservazione: viene conteggiato ma non applicato, quindi per ora nulla viene rifiutato a causa sua, e il changelog annuncia il giorno in cui verrà applicato. Considera questi numeri come la politica attuale e non come una promessa. Le chiavi sandbox hanno gli stessi contatori al minuto delle chiavi live, quindi pianifica i test di carico invece di eseguirli in un ciclo.
Nomi e versioni
I campi della richiesta sono in snake_case, come first_name e agent_id. Le grafie precedenti funzionano ancora: user_id viene letto come agent_id e aggiunge una voce in warnings, mentre customer_email viene accettato come email senza alcun avviso. Molte risposte mantengono una chiave più vecchia accanto al suo gemello in snake_case con lo stesso valore, come order_id accanto a code, e ?naming=snake restituisce solo chiavi in snake_case. La versione sta nel percorso, /api/v1: una modifica non retrocompatibile avrebbe un nuovo prefisso, mentre nuovi campi e grafie sono aggiunte compatibili.
Inizia nella sandbox gratuita, poi passa a live
Tutto ciò che c’è in questa pagina oggi funziona nella sandbox. Una chiave sandbox è gratuita e si crea in autonomia, e non tocca mai il tuo saldo reale.
Crea un account
Registra un account FX-Port. Le chiavi sandbox sono gratuite e le prenotazioni sandbox non comportano addebiti reali.
Crea una chiave sandbox
Nella pagina API della tua dashboard crea una chiave che inizia con
fxp_test_. Una chiave di lettura può cercare e leggere; una chiave di lettura e scrittura può anche creare prenotazioni di prova.Invia la prima richiesta
Esiste un solo URL di base e la chiave va nell’header
Authorizationcome bearer token. La guida rapida illustra una prima chiamata.Passa a Live quando sei pronto
Sostituisci la chiave con una
fxp_live_. Live funziona quando la tua agenzia è stata approvata; fino ad allora l’API risponde403 agency_not_active. Le prenotazioni reali si pagano da un saldo ricaricato.
Una prima richiesta al catalogo in cURL. La documentazione riporta la stessa richiesta in tutti i linguaggi supportati.
Richiesta
curl 'https://api.fx-port.com/api/v1/esims/packages?country=france&type=local' \
-H "Authorization: Bearer fxp_test_YOUR_KEY"Guida rapida: prima chiamata sandbox
Che cosa fa la sandbox
Un ordine nella sandbox crea una vera eSIM di prova presso il fornitore, con un codice di attivazione fittizio, quindi non si può installare su un telefono. Nulla viene addebitato e le risposte lo dicono: balanceDebited, transactionCreated e payoutCreated sono tutti false. Una ricarica risponde con un saldo pari a zero. I consumi sono statici: una nuova eSIM mostra tutto il totale incluso e lo stato ACTIVE. Le prenotazioni sandbox sono visibili solo alle chiavi sandbox.
Che cosa si può provare solo su live
Il controllo del saldo, il controllo dei duplicati e il blocco del saldo funzionano solo su live. Quindi le risposte 402 con insufficient_balance, 409 per lo stesso pacchetto ordinato di nuovo entro 60 secondi e 503 con balance_lock_timeout non compaiono mai nella sandbox. Scrivi la loro gestione partendo dall’elenco dei codici di errore.
Passare a live
Le chiavi live sono legate all’approvazione dell’agenzia: finché la tua agenzia non è approvata, una chiave live risponde agency_not_active e la tua chiave sandbox continua a funzionare. Gli ordini live si pagano da un saldo agenzia con fondi disponibili. Passare a live cambia la chiave, non il codice, perché sandbox e live condividono lo stesso URL di base.
Chi costruisce sull’API eSIM
Ogni tipo di cliente si appoggia a una parte diversa delle stesse chiamate.
Agenzie che vendono viaggi
Le agenzie vendono una eSIM insieme al volo e all’hotel. Ordinano con l’indirizzo email del viaggiatore, così il fornitore invia il codice QR e un link di condivisione, e leggono i consumi quando un viaggiatore lo chiede. La percentuale di commissione torna con ogni pacchetto e agent_id registra quale utente della tua agenzia ha effettuato un ordine.
OTA e marketplace
I marketplace costruiscono prima la pagina di consultazione: un paese alla volta, pacchetti locali o regionali, le reti e i dati inclusi di ogni pacchetto, e un controllo del dispositivo prima dell’acquisto del viaggiatore. Una schermata che elenca le eSIM di un viaggiatore può leggere in una sola chiamata i consumi di un massimo di 50 eSIM.
Team travel-tech e aziendali
I team travel-tech e i reparti viaggi aziendali costruiscono i propri strumenti di prenotazione. Tutto ciò che serve per iniziare è pubblico: il file OpenAPI, la collection Postman e una documentazione in testo semplice che un assistente IA di programmazione può leggere, così il primo prototipo parte dal contratto reale.
API eSIM: domande frequenti
Che cos’è l’API eSIM di FX-Port e a chi è rivolta?
È un’API REST che permette a un’agenzia di viaggio, a una OTA o a un rivenditore di vendere eSIM dati da viaggio con una sola integrazione. Elenchi i pacchetti di una destinazione con prezzi nella valuta della tua agenzia e ne ordini uno per un viaggiatore. Consegni al viaggiatore il codice QR, segui i consumi e ricarichi. Tutto è JSON su HTTPS e un file OpenAPI descrive ogni endpoint.
Esiste una sandbox gratuita e come si ottiene una chiave?
Sì. Crea un account FX-Port, apri la pagina API della tua dashboard e crea una chiave sandbox: puoi farlo in autonomia e senza costi. Un ordine nella sandbox crea una eSIM di prova con un codice di attivazione fittizio, quindi non si può installare su un telefono. Dal tuo saldo non viene addebitato nulla. Sandbox e live condividono lo stesso URL di base, quindi il codice che provi è il codice che pubblichi.
Che cosa serve per passare a live?
La tua agenzia deve essere approvata prima che una chiave live funzioni. Fino ad allora una chiave live viene rifiutata e la tua chiave sandbox continua a funzionare. Gli ordini live si pagano da un saldo agenzia con fondi disponibili, che la sandbox non tocca mai, e ogni chiave può essere vincolata a un elenco di indirizzi IP. Il passaggio consiste solo nel cambiare la chiave; ogni risposta indica l’ambiente da cui proviene.
In quali paesi e con quali pacchetti posso vendere?
I pacchetti sono disponibili in almeno 190 paesi e i bundle regionali compaiono sotto la loro regione. I pacchetti differiscono per dati inclusi, validità, reti e possibilità di ricarica. Leggi questi campi e l’id del pacchetto dalla risposta del catalogo invece di scriverli nel codice. Chiedi un paese alla volta, perché l’intero catalogo è una risposta molto grande. Un elenco separato dei dispositivi permette di controllare il telefono del viaggiatore prima della vendita.
Come riceve la eSIM il viaggiatore?
La risposta dell’ordine contiene il codice QR, la sua stringa di attivazione, un link di installazione per iPhone e una pagina di condivisione. Puoi mostrarli nelle tue schermate. FX-Port chiede inoltre al fornitore di inviare per email il codice QR e un link di condivisione all’indirizzo del viaggiatore appena la eSIM viene creata. Se il fornitore non ha ancora restituito la eSIM, l’ordine esiste comunque e i dati sono disponibili in seguito dalla chiamata dei dati di configurazione.
Come si combinano prezzi, commissione e saldo?
Ogni pacchetto riporta questi campi monetari nella valuta della tua agenzia: il prezzo base prima della commissione, il prezzo totale da far pagare al viaggiatore, l’importo addebitato sul tuo saldo e la tua percentuale di commissione. La tua commissione è il prezzo totale meno l’addebito. Leggi questi campi invece di ricostruirli, perché l’addebito è specifico della tua agenzia. Nella sandbox non viene addebitato nulla; su live l’addebito esce dal saldo della tua agenzia.
Posso ricaricare una eSIM e come vedo quanto resta?
Sì, in due chiamate: elenca i pacchetti che si possono aggiungere a quella eSIM, poi crea la ricarica con uno di essi. Una ricarica non è sempre possibile, perché un fornitore può cambiare l’operatore di un paese. Un elenco vuoto significa allora che il viaggiatore ha bisogno di una nuova eSIM. I consumi sono in cache fino a 15 minuti, quindi considerali un valore recente, e una chiamata legge fino a 50 eSIM.
Come vengono segnalati gli errori e ci sono webhook?
Un errore torna in un unico formato con un codice di errore stabile, ed è quel codice che il tuo programma deve verificare, non il testo del messaggio. Le letture si possono ripetere in sicurezza con backoff. Creare un ordine o una ricarica è diverso: non c’è una chiave di idempotenza, quindi dopo un timeout cerca la prenotazione prima di riprovare. FX-Port rifiuta un duplicato evidente, come lo stesso pacchetto ordinato due volte entro 60 secondi su live. Non ci sono webhook.
Posso annullare o rimborsare un ordine eSIM tramite l’API?
No. L’API non ha un endpoint per annullare o rimborsare un ordine eSIM. Ogni ordine crea esattamente una eSIM, quindi controlla il pacchetto e i dati del viaggiatore prima di inviarlo. Se il fornitore rifiuta un ordine, non viene addebitato nulla e viene salvata una prenotazione non riuscita. Per un problema su un ordine specifico, scrivi al team sviluppatori indicando il suo id prenotazione.
Che cosa serve per iniziare e quali strumenti aiutano?
Servono una chiave sandbox e un client HTTP. La documentazione aggiunge un file OpenAPI 3.1, una collection Postman, esempi di codice in 9 linguaggi ed esportazioni in testo semplice per gli assistenti IA. Tieni le chiavi sul tuo server, mai in un browser o in un’app. La parte che richiede più tempo è il tuo checkout, la consegna del codice QR al viaggiatore e la gestione degli errori.
Altre API di FX-Port
Una eSIM di solito accompagna un viaggio. Voli e hotel usano le stesse chiavi, lo stesso corpo di errore e le stesse convenzioni delle eSIM, e le loro prenotazioni si trovano nello stesso storico dell’account.
Cerca, calcola il prezzo e prenota voli, paga gli ordini in attesa, annulla e leggi i biglietti.
Trova hotel, verifica le tariffe, effettua la pre-prenotazione e la prenotazione, leggi i voucher e annulla.
- API TransferAnteprima
Richiedi preventivi, prenota, segui e annulla i transfer aeroportuali.
Preferisci non scrivere codice? Le agenzie possono vendere eSIM anche dalla dashboard di FX-Port. Vendi eSIM dalla dashboard
Esegui il tuo primo ordine eSIM nella sandbox
Crea un account, genera una chiave sandbox, elenca i pacchetti, crea un ordine e leggi i consumi oggi stesso. Le chiavi live seguono quando la tua agenzia è approvata.
Chiedi a un assistente IA di questa API
Apri questa pagina in un assistente e chiedi un piano di integrazione passo per passo.
