NouAPI REST cu fișier OpenAPI 3.1
API eSIM pentru agenții de turism, OTA și revânzători
Vinde eSIM-uri de călătorie printr-un singur API REST. Listează pachetele de date pe țări, cu prețuri în moneda agenției tale, comandă unul pentru un călător, dă-i codul QR, urmărește consumul și reîncarcă. Un singur URL de bază servește sandbox și live. Începe cu o cheie sandbox gratuită; cheile live funcționează după ce agenția ta este aprobată.
Documentația este scrisă în limba engleză.
- URL de bază
https://api.fx-port.com/api/v1- Autentificare
Authorization: Bearer fxp_test_...- Prefixe de chei
fxp_test_ / fxp_live_- Endpoint-uri
- 12
- Țări cu pachete
- 190+
- Limbaje pentru exemple de cod
- 9
API-ul eSIM, apel cu apel
Urmărește pas cu pas vânzarea unui eSIM, pe măsură ce fiecare cerere este construită, trimisă și primește răspuns. Sesiunile acoperă vânzarea unui eSIM, menținerea călătorului conectat, verificarea dispozitivelor și a rezervărilor, precum și erorile care merită tratate. Cererile și răspunsurile sunt exemple din documentație, iar această pagină nu apelează niciodată API-ul.
3 cereri: Listează pachetele, Comandă eSIM-ul, Citește datele de configurare.
Sesiune ilustrativă: corpurile cererilor și ale răspunsurilor sunt exemple din documentație, datele sunt mutate în viitor ca să rămână după ziua de azi, iar duratele sunt orientative. Această pagină nu trimite nicio cerere.
Găsește un pachet, comandă-l, citește datele de configurare
Începe cu pachetele unei țări, comandă unul pentru un călător, apoi citește datele de configurare ale comenzii. Sandbox-ul creează un eSIM de test cu un cod de activare fictiv și nu debitează nimic, iar consola arată o copie redusă a răspunsului din catalog.
Listează pachetele
Apelul pentru catalog primește
countryșitypeși returnează pachetele potrivite, cu prețuri în moneda agenției tale. Păstreazăpackage_idal pachetului ales de călător.Cerere GET /esims/packages curl 'https://api.fx-port.com/api/v1/esims/packages?country=france&type=local' \ -H "Authorization: Bearer fxp_test_YOUR_KEY"Răspuns 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 } }Exemplu scurtat pentru afișare
- PASS Codul de stare este 200
- PASS $.success este egal cu true
- PASS $.data[0].package_id există
- PASS $.data[0].balance_debit_amount există
Comandă eSIM-ul
Crearea unei comenzi primește
package_idîmpreună cu adresa de email și numărul de telefon ale călătorului. Păstreazăbooking_idșidata.icciddin răspuns. În sandbox,balanceDebited,transactionCreatedșipayoutCreatedsunt toatefalse.Cerere 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" }'Răspuns 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 }Exemplu scurtat pentru afișare
- PASS Codul de stare este 200
- PASS $.environment este egal cu sandbox
- PASS $.balance_debited este egal cu false
- PASS $.data.iccid există
Citește datele de configurare
Apelul pentru datele de configurare primește
booking_idși returnează codul QR, datele de activare, linkurile de instalare și pașii de instalare ai comenzii. Arată-le doar călătorului care deține eSIM-ul.Cerere 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"Răspuns 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" } }Exemplu scurtat pentru afișare
- PASS Codul de stare este 200
- PASS $.data.package_id este egal cu france-in-7days-1gb
- PASS $.data.sims[0].iccid există
Referința pentru GET /esims/bookings/{booking_id}/setup-instructions în documentație
Citește consumul, apoi reîncarcă
După ce un călător are un eSIM, citește cât din date a rămas, întreabă ce pachete pot fi adăugate exact acelui eSIM, apoi creează reîncărcarea. Consumul este păstrat în cache, așa că o cifră poate avea câteva minute vechime. Istoricul reîncărcărilor este în bara laterală și în cererile și răspunsurile scenariului.
Citește consumul
Apelul de consum primește ICCID-ul comenzii și returnează
remainingșitotalîn megabyți,statusși data de expirare. Răspunsul vine dintr-un cache, iarforce=trueîntreabă din nou furnizorul.Cerere GET /esims/usage/{iccid} curl https://api.fx-port.com/api/v1/esims/usage/8900000540463077957 \ -H "Authorization: Bearer fxp_test_YOUR_KEY"Răspuns 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 Codul de stare este 200
- PASS $.data.data.status este egal cu ACTIVE
- PASS $.data.data.remaining există
Listează pachetele de reîncărcare
Acest apel listează pachetele care pot fi adăugate astăzi exact acestui eSIM. O listă goală înseamnă că eSIM-ul nu poate fi reîncărcat acum. Ia
package_idal reîncărcării din această listă, niciodată din comanda inițială.Cerere GET /esims/topup-packages/{iccid} curl https://api.fx-port.com/api/v1/esims/topup-packages/8900000540463077957 \ -H "Authorization: Bearer fxp_test_YOUR_KEY"Răspuns 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 } ] } }Exemplu scurtat pentru afișare
- PASS Codul de stare este 200
- PASS $.data.data are 2 elemente
- PASS $.data.data[0].type este egal cu topup
Referința pentru GET /esims/topup-packages/{iccid} în documentație
Creează reîncărcarea
Crearea unei reîncărcări primește
package_iddin lista aceea și ICCID. Pe live, soldul tău este debitat doar după ce furnizorul acceptă. În sandbox,balancedin răspuns este zero și nu se debitează nimic.Cerere 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" }'Răspuns 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 Codul de stare este 200
- PASS $.environment este egal cu sandbox
- PASS $.balance_debited este egal cu false
- PASS $.data.balance.current este egal cu 0
Citește istoricul reîncărcărilor
Istoricul reîncărcărilor listează reîncărcările unui eSIM, cele mai noi primele. Reîncărcările nu apar în lista rezervărilor, deci aici le găsești.
Cerere 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"Răspuns 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 Codul de stare este 200
- PASS $.data[0].type este egal cu topup
Referința pentru GET /esims/bookings/{iccid}/topup-history în documentație
Verifică un dispozitiv, apoi citește rezervările
Înainte de vânzare, verifică dacă telefonul călătorului este compatibil eSIM. După vânzare, citește rezervările și verifică dacă o referință de rezervare este a ta. Consumul în bloc este listat în bara laterală.
Verifică lista de dispozitive
Apelul pentru dispozitive compatibile returnează dispozitivele cunoscute ca fiind compatibile eSIM, cu
brand,modelșios. Caută telefonul călătorului înainte de a vinde.Cerere GET /esims/compatible-devices curl https://api.fx-port.com/api/v1/esims/compatible-devices \ -H "Authorization: Bearer fxp_test_YOUR_KEY"Răspuns 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 Codul de stare este 200
- PASS $.success este egal cu true
- PASS $.data[0].model există
Referința pentru GET /esims/compatible-devices în documentație
Listează rezervările
Lista rezervărilor returnează comenzile eSIM ale agenției tale, cele mai noi primele. Această cerere cere o singură rezervare cu
limit, iarpaginationarată câte comenzi se potrivesc și dacă urmează o altă pagină.Cerere GET /esims/bookings curl 'https://api.fx-port.com/api/v1/esims/bookings?limit=1' \ -H "Authorization: Bearer fxp_test_YOUR_KEY"Răspuns 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 Codul de stare este 200
- PASS $.data are 1 element
- PASS $.pagination.has_more este egal cu true
Verifică apartenența
Verificarea apartenenței răspunde cu
is_ownertrue când rezervarea aparține agenției tale. O rezervare a altei agenții și una inexistentă primesc același răspuns, deci apelul nu poate fi folosit pentru a descoperi referințe.Cerere 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"Răspuns 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 Codul de stare este 200
- PASS $.is_owner este egal cu true
Referința pentru GET /esims/bookings/{booking_id}/verify în documentație
Citește consumul în bloc
Un singur apel citește consumul mai multor eSIM-uri listate în
iccidsși returnează o intrare pe ICCID, fiecare cu propriulstatus. Trimite mereuiccids.Cerere GET /esims/usage/bulk curl 'https://api.fx-port.com/api/v1/esims/usage/bulk?iccids=8900000540463077957' \ -H "Authorization: Bearer fxp_test_YOUR_KEY"Răspuns 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 Codul de stare este 200
- PASS $.data[0].status este egal cu success
Eșecuri și cum reacționezi la fiecare
Toate eșecurile au același corp, iar prima intrare din errors are un code stabil. Aceste apeluri de comandă eșuează intenționat, fiecare dintr-un alt motiv și cu o altă reacție.
Cheie de citire pe o comandă
O cheie de citire pe apelul de comandă este refuzată cu
403șiread_write_permission_required, înainte ca corpul să fie citit. Treci la o cheie Citire+scriere.Cerere 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" }'Răspuns 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 Codul de stare este 403
- PASS Codul de eroare este read_write_permission_required
- PASS $.errors[0].type este egal cu permission_error
Adresă de email invalidă
O valoare care nu este o adresă de email este refuzată cu
400șiinvalid_email, iarfieldindicăemail. Corectează valoarea înainte să trimiți din nou comanda: aceeași cerere eșuează la fel.Cerere 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" }'Răspuns 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 Codul de stare este 400
- PASS Codul de eroare este invalid_email
- PASS $.errors[0].field este egal cu email
Comandă duplicată
O comandă pentru un pachet care este deja în procesare este refuzată cu
409șiduplicate_request. Nu o trimite din nou imediat: caută întâi rezervarea și comandă din nou doar dacă nu s-a creat niciuna.Cerere 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" }'Răspuns 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 Codul de stare este 409
- PASS Codul de eroare este duplicate_request
- PASS $.errors[0].type este egal cu conflict
Prea multe cereri
Peste limita pe minut, apelul este refuzat cu
429șirate_limit_exceeded, iar antetulRetry-Afterspune câte secunde să aștepți. Apoi reîncearcă cu backoff.Cerere 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" }'Răspuns 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 Codul de stare este 429
- PASS Codul de eroare este rate_limit_exceeded
- PASS Antetul Retry-After este prezent
- PASS $.errors[0].details.retry_after este egal cu 12
De la catalog la un călător conectat, în cinci pași
O integrare înseamnă un parcurs scurt: citești catalogul, creezi comanda, îi dai călătorului eSIM-ul, urmărești consumul și reîncarci când se termină datele. Doar comanda și reîncărcarea schimbă ceva. Orice alt apel doar citește.
Citește catalogul pentru o destinație
Listează pachetele unei țări, cu prețurile deja în moneda agenției tale, și păstrează package_id al pachetului ales de călător. Trimite mereu country: catalogul întreg este un răspuns foarte mare, fără paginare. Citește id-urile pachetelor din răspuns în loc să le scrii fix în cod, pentru că se schimbă catalogul.
Cerere
curl 'https://api.fx-port.com/api/v1/esims/packages?country=france&type=local' \
-H "Authorization: Bearer fxp_test_YOUR_KEY"Răspuns 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
}
}Creează comanda
Trimite package_id împreună cu adresa de email și numărul de telefon ale călătorului. O comandă creează exact un eSIM și, pe live, îți debitează soldul agenției. Păstrează booking_id și ICCID din răspuns, pentru că fiecare apel următor are nevoie de unul dintre ele.
Cerere
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"
}'Răspuns 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
}| Câmp | Ce conține |
|---|---|
booking_id | Referința FX-Port a comenzii. Păstrează-o pentru datele de configurare, verificarea apartenenței și evidențele tale. |
data.iccid | Identificatorul eSIM-ului. Consumul, reîncărcările și instrucțiunile de instalare se cer toate după ICCID. |
data.sim.qrcode data.sim.qrcode_url | Șirul de activare codificat de codul QR și un link către imaginea codului QR. |
data.sim.direct_apple_installation_url data.sim.sharing | Un link care pornește instalarea pe iPhone și o pagină de partajare în care călătorul poate deschide eSIM-ul cu codul lui de acces. Apelul pentru datele de configurare adaugă linkul pentru Android. |
PENDING-, iar datele sunt disponibile din apelul pentru datele de configurare imediat ce le are furnizorul.Dă-i călătorului eSIM-ul
Răspunsul conține codul QR și șirul lui de activare, așa că le poți afișa în propriile ecrane. FX-Port îi cere și furnizorului să trimită prin email codul QR și un link de partajare la adresa călătorului, deci nu trebuie să le retransmiți tu. Apelul pentru datele de configurare returnează ulterior aceleași date, împreună cu pașii de instalare.
Cerere
curl https://api.fx-port.com/api/v1/esims/bookings/FX-1793546602916/setup-instructions \
-H "Authorization: Bearer fxp_test_YOUR_KEY"Răspuns 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
}
}Urmărește consumul
Citește datele rămase și data de expirare a unui eSIM după ICCID. Răspunsul este păstrat în cache cel mult 15 min, așa că folosește-l pentru un ecran sau o notificare, nu ca pe un contor.
Cerere
curl https://api.fx-port.com/api/v1/esims/usage/8900000540463077957 \
-H "Authorization: Bearer fxp_test_YOUR_KEY"Răspuns 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"
}
}
}Reîncarcă atunci când se termină datele
Listează pachetele care pot fi adăugate exact acestui eSIM, apoi creează reîncărcarea cu unul dintre ele. Dacă lista este goală, eSIM-ul nu poate fi reîncărcat acum, iar călătorul are nevoie de unul nou.
Cerere
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"
}'Răspuns 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
}Prețuri, comision și soldul tău
Fiecare pachet are câmpurile lui financiare, calculate pe server în moneda agenției tale. Un preț trimis în corpul cererii este ignorat, așa că o comandă este creată întotdeauna la prețul calculat de server.
| Câmp | Ce conține |
|---|---|
base_price price | Prețul pachetului înainte de comisionul tău. Nu este suma debitată din soldul tău. |
total_price retail_price | Prețul de încasat de la călător, cu comisionul tău inclus. |
balance_debit_amount b2b_price | Ce iese din soldul agenției tale când comanzi pachetul pe live. Citește-l, nu îl calcula. |
agency_commission commission_rate | Rata comisionului tău, ca text și ca număr. Rezervările returnează în schimb comisionul tău ca sumă. |
În exemplul din catalog, călătorul plătește 468.84 DZD. O comandă pe live îți debitează soldul cu 418.60 DZD, iar diferența, 50.24 DZD, este comisionul tău.
Rata aparține agenției tale
Rata comisionului vine cu fiecare pachet și nu este aceeași pentru toate agențiile. O agenție corporativă cu contract poate avea rata zero, iar atunci prețul total este egal cu debitul.
Citește câmpurile, nu le reconstrui
Debitul poate fi mai mare decât prețul de bază, deoarece din el fac parte sume specifice agenției tale. Așadar citește balance_debit_amount și nu îl calcula niciodată din base_price. Cuvântul price înseamnă prețul de bază în catalog, dar prețul cu amănuntul în comenzi, în pachetele de reîncărcare și în datele de configurare: folosește peste tot base_price și total_price și ambiguitatea dispare.
Prețuri în moneda agenției tale
Fiecare sumă este deja convertită în moneda agenției tale, indiferent de moneda furnizorului. Răspunsul arată și moneda furnizorului, și cursul de schimb, deci poți verifica singur cursul și nu mai ai nevoie să convertești încă o dată.
După vânzare: consum, reîncărcări și date de configurare
O vânzare nu se termină cu comanda. Aceste apeluri țin călătorul conectat și funcționează doar pe eSIM-urile comandate de agenția ta în același mediu ca al cheii tale.
Citirea consumului și cât de proaspăt este
Consumul returnează datele rămase, volumul total, starea și data de expirare a unui eSIM sau a cel mult 50 eSIM-uri într-un singur apel. FX-Port păstrează ultimul răspuns cel mult 15 min, pentru a proteja limitele de rată ale furnizorului, așa că o cifră poate fi chiar atât de veche. Trimite force=true pentru a întreba din nou furnizorul, de exemplu imediat după o reîncărcare. Nu o face la fiecare cerere, pentru că furnizorul limitează cât de des poate fi citit consumul. Dacă furnizorul nu poate răspunde, primești ultima cifră cunoscută, marcată ca învechită.
Reîncărcări: întreabă întâi, apoi creează
O reîncărcare înseamnă două apeluri. Întâi listezi pachetele care pot fi adăugate exact acestui eSIM, apoi creezi reîncărcarea cu unul dintre id-urile de pachet returnate. Nu refolosi niciodată id-ul pachetului comenzii inițiale și nu păstra un pachet de reîncărcare pentru mai târziu: întreabă din nou când călătorul vrea să reîncarce. O reîncărcare adaugă date eSIM-ului și nu înlocuiește ce a rămas, așa că citește rezultatul din consum cu force=true.
Când o reîncărcare nu este posibilă
Furnizorii aleg operatorii mobili care deservesc o țară și, în cazuri rare, schimbă unul. eSIM-ul poate continua atunci să funcționeze până expiră, în timp ce pachetul lui nu mai poate fi reîncărcat. Lista pachetelor de reîncărcare vine goală. Dacă un furnizor respinge o reîncărcare, soldul tău nu este atins, iar încercarea este salvată ca rezervare eșuată. Răspunsul este un supplier_error la care poți reacționa.
Date de configurare și pași de instalare
Apelul pentru datele de configurare returnează oricând ai nevoie codul QR, datele de activare, linkurile de instalare și pașii de instalare ai unei comenzi. Apelul de instrucțiuni returnează pașii pe sisteme de operare, în limba pe care o ceri. Pașii sunt text generic de la furnizor, așa că arată-i lângă codul QR al comenzii. Arată-le pe ambele doar călătorului care deține eSIM-ul.
Rezervări, istoric de reîncărcări și apartenență
Lista rezervărilor returnează comenzile eSIM ale agenției tale din mediul cheii tale, cele mai noi primele. O poți căuta după id-ul rezervării, numele călătorului, adresa de email, numele pachetului sau ICCID. Reîncărcările nu apar în lista aceea: citește-le din istoricul de reîncărcări al unui eSIM. Înainte să construiești un link sau un ecran în jurul unui id de rezervare, verificarea apartenenței îți spune dacă este al tău. O rezervare a altei agenții și una inexistentă primesc același răspuns.
Toate endpoint-urile eSIM, cu OpenAPI, Postman și exemple de cod
API-ul eSIM are 12 endpoint-uri sub un singur URL de bază. Fiecare rând deschide pagina de referință a apelului respectiv, cu câmpurile cererii, răspunsurile, erorile și exemplele în 9 limbaje.
| Endpoint | Ce face | Cheie |
|---|---|---|
GET /api/v1/esims/packages | Listează pachetele unei țări sau regiuni, cu prețurile deja în moneda agenției tale. Trimite mereu o țară: catalogul întreg este foarte mare și nu are paginare. | Citire |
GET /api/v1/esims/compatible-devices | Dispozitivele cunoscute ca fiind compatibile eSIM, pentru o verificare înainte ca călătorul să cumpere. | Citire |
POST /api/v1/esims/orders | Creează un eSIM dintr-un pachet pentru un călător și îl provizionează la furnizor. Pe live, îți debitează soldul agenției. | Citire+scriere |
GET /api/v1/esims/topup-packages/{iccid} | Pachetele care pot fi adăugate astăzi exact unui eSIM. O listă goală înseamnă că nu poate fi reîncărcat acum. | Citire |
POST /api/v1/esims/topups | Adaugă un pachet de reîncărcare unui eSIM existent. Pe live, soldul tău este debitat doar după ce furnizorul acceptă. | Citire+scriere |
GET /api/v1/esims/usage/{iccid} | Datele rămase, volumul total, starea și data de expirare ale unui eSIM. Răspunsul poate avea până la 15 min vechime. | Citire |
GET /api/v1/esims/usage/bulk | Consumul a cel mult 50 eSIM-uri într-un singur apel, o intrare pe ICCID, fiecare cu starea ei. | Citire |
GET /api/v1/esims/bookings | Comenzile eSIM ale agenției tale, cele mai noi primele, cu căutare și paginare. Reîncărcările nu apar în această listă. | Citire |
GET /api/v1/esims/bookings/{iccid}/topup-history | Reîncărcările unui eSIM, cele mai noi primele. Lista este goală dacă eSIM-ul nu are niciuna. | Citire |
GET /api/v1/esims/bookings/{booking_id}/verify | Verifică dacă o referință de rezervare aparține agenției tale, înainte să construiești un link sau un ecran în jurul ei. | Citire |
GET /api/v1/esims/bookings/{booking_id}/setup-instructions | Codul QR, datele de activare, linkurile de instalare și pașii de instalare ai unei comenzi, ca JSON. | Citire |
GET /api/v1/esims/instructions/{iccid} | Instrucțiuni de instalare pas cu pas pentru un ICCID, pe sisteme de operare, în limba pe care o ceri. | Citire |
OpenAPI 3.1
Un singur fișier descrie fiecare endpoint și fiecare câmp. Generează din el un client, importă-l într-un instrument pentru API-uri sau dă-l unui asistent de programare.
Colecție Postman
Colecția eSIM acoperă toate cele 12 endpoint-uri, în foldere care urmează etapele unei vânzări. Nu conține chei, așa că adaugă-le pe ale tale.
Exemple de cod în 9 limbaje
Fiecare pagină de referință afișează cererea în cURL, Node.js, Python, PHP, Go, Java, C#, Swift și Kotlin, generată din descrierea OpenAPI. Fiecare cerere eSIM este disponibilă în toate.
Documentație pentru asistenți AI
llms.txt și llms-full.txt oferă asistenților AI documentația ca text simplu, iar orice pagină din documentație poate fi citită ca Markdown adăugând .md la adresa ei.
Gândit pentru producție: chei, erori, reîncercări și cache
O integrare eSIM se judecă în producție după autentificare, erori, reîncercări, cache și limite de rată. Iată ce trebuie să știi despre fiecare.
Un URL de bază, două feluri de chei
Fiecare cerere poartă o cheie ca token bearer în antetul Authorization. Prefixul arată unde funcționează cheia: fxp_test_ pentru sandbox și fxp_live_ pentru live. Ambele ajung la același URL de bază, iar fiecare răspuns JSON precizează în environment mediul din care provine. Cheile își au locul pe serverul tău, niciodată într-un browser sau într-o aplicație. FX-Port păstrează doar un hash al fiecărei chei, deci o cheie pierdută nu mai poate fi afișată. O modificare a unei chei poate dura câteva minute până se aplică.
Ce cheie face ce apel
O cheie de citire poate lista pachete, verifica dispozitive, citi consumul și citi rezervările. Crearea unei comenzi sau a unei reîncărcări cere o cheie Citire+scriere, iar o cheie de citire care încearcă asta primește read_write_permission_required. Orice cheie poate fi blocată pe o listă de adrese IP, iar un apel de la altă adresă primește ip_not_allowed. Folosește o cheie de citire oriunde codul doar afișează rezultate.
Un singur format de eroare pentru orice eșec
Un apel eșuat returnează un tablou errors. Prima lui intrare are un code stabil, un type care spune cum să reacționezi și field, câmpul în cauză. Testează codul, niciodată mesajul. Lista de erori comună pentru zboruri, hoteluri, eSIM-uri și cont conține 180 de coduri. Când furnizorul refuză o comandă sau o reîncărcare, răspunsul este un supplier_error cu statusul HTTP al furnizorului. Nu se debitează nimic și se salvează o rezervare eșuată. Imediat după o repornire, catalogul și lista de dispozitive pot răspunde cu 202 și success setat pe false: așteaptă câteva secunde și întreabă din nou.
Reîncercări fără a comanda de două ori
FX-Port nu are cheie de idempotență, deci nu există un antet Idempotency-Key de trimis. Citirile pot fi repetate fără risc; crearea unei comenzi sau a unei reîncărcări nu. FX-Port refuză un duplicat evident cu 409 și duplicate_request: o comandă pentru un pachet care este încă în procesare. Pe live refuză și același pachet comandat din nou în cel mult 60 s de la ultima comandă confirmată a agenției tale, indiferent de călător. Comenzile răspund de obicei în câteva secunde, dar un furnizor lent poate dura mult mai mult. Dacă un apel expiră sau conexiunea se întrerupe, nu trimite imediat comanda din nou, pentru că eSIM-ul poate exista deja. Caută-l cu parametrul search al listei de rezervări, folosind adresa de email a călătorului, și comandă din nou doar dacă nu s-a creat nimic.
Fără webhook-uri: întrebi când ai nevoie
FX-Port nu apelează niciun URL al tău, nici în sandbox, nici pe live. O comandă răspunde cu eSIM-ul sau cu un înlocuitor PENDING- cât timp furnizorul nu l-a returnat încă. Orice altceva ceri când ai nevoie: datele de configurare, consumul sau lista de rezervări.
Cache și viteză
Consumul este păstrat cel mult 15 min, lista pachetelor de reîncărcare câteva minute, iar force=true sare peste cache. Catalogul nefiltrat este un răspuns foarte mare, fără paginare, așa că trimite country și acceptă comprimarea cu Accept-Encoding: gzip. Titlurile pachetelor vin în limba parametrului locale; prima cerere într-o altă limbă decât engleza este mai lentă, pentru că textul este preluat atunci și apoi păstrat în cache.
Limite de rată
Limitele se numără pe cheie și pe minut, în două grupuri, iar fiecare răspuns conține ratelimit-limit și ratelimit-remaining, deci poți încetini înainte să fii refuzat. După un 429, așteaptă secundele din Retry-After și reîncearcă cu backoff exponențial și jitter. Prea multe comenzi sau reîncărcări simultane ale aceleiași chei sau agenții pot primi răspunsul concurrency_limit_exceeded.
| Tip de apel | Pe minut |
|---|---|
| Crearea comenzilor și a reîncărcărilor | 1,200 |
| Orice alt endpoint eSIM | 6,000 |
Deocamdată plafonul pentru comenzile și reîncărcările simultane este în modul de observare: este numărat, dar nu aplicat, deci nimic nu este refuzat din acest motiv, iar jurnalul de modificări anunță ziua în care va fi aplicat. Citește aceste cifre ca politica actuală, nu ca pe o promisiune. Cheile sandbox au aceleași contoare pe minut ca cheile live, așa că programează testele de încărcare în loc să le rulezi într-o buclă.
Nume și versiuni
Câmpurile cererii sunt snake_case, de exemplu first_name și agent_id. Denumirile mai vechi încă funcționează: user_id este citit ca agent_id și adaugă o intrare warnings, în timp ce customer_email este acceptat ca email, fără avertisment. Multe răspunsuri păstrează o cheie mai veche alături de gemenul ei snake_case, cu aceeași valoare, de exemplu order_id lângă code, iar ?naming=snake returnează doar chei snake_case. Versiunea este în cale, /api/v1: o schimbare incompatibilă ar primi un prefix nou, în timp ce câmpurile și denumirile noi sunt doar adăugiri.
Începe în sandbox-ul gratuit, apoi treci pe live
Tot ce se află pe această pagină funcționează astăzi în sandbox. O cheie sandbox este gratuită, o creezi singur și nu atinge niciodată soldul tău real.
Creează un cont
Înregistrează-te pentru un cont FX-Port. Cheile sandbox sunt gratuite, iar rezervările din sandbox nu generează costuri reale.
Creează o cheie sandbox
Pe pagina API din panoul tău de control, creează o cheie care începe cu
fxp_test_. O cheie de citire poate căuta și citi; o cheie Citire+scriere poate crea și rezervări de test.Trimite prima cerere
Există un singur URL de bază, iar cheia se trimite în antetul
Authorizationca token Bearer. Ghidul de start rapid parcurge un prim apel.Treci pe Live când ești gata
Înlocuiește cheia cu una
fxp_live_. Live funcționează după ce agenția ta este aprobată; până atunci API-ul răspunde403 agency_not_active. Rezervările reale se plătesc dintr-un sold alimentat.
O primă cerere pentru catalog în cURL. Documentația afișează aceeași cerere în fiecare limbaj acceptat.
Cerere
curl 'https://api.fx-port.com/api/v1/esims/packages?country=france&type=local' \
-H "Authorization: Bearer fxp_test_YOUR_KEY"Ghid de start rapid: primul apel sandbox
Ce face sandbox-ul
O comandă în sandbox creează la furnizor un eSIM de test real, cu un cod de activare fictiv, deci nu poate fi instalat pe un telefon. Nu se debitează nimic, iar răspunsurile o spun: balanceDebited, transactionCreated și payoutCreated sunt toate false. O reîncărcare răspunde cu un sold zero. Consumul este static: un eSIM nou arată tot volumul și starea ACTIVE. Rezervările din sandbox sunt vizibile doar pentru cheile sandbox.
Ce se poate testa doar pe live
Verificarea soldului, verificarea duplicatelor și blocarea soldului rulează doar pe live. De aceea răspunsurile 402 cu insufficient_balance, 409 pentru același pachet comandat din nou în cel mult 60 s și 503 cu balance_lock_timeout nu apar niciodată în sandbox. Scrie tratarea lor pornind de la lista codurilor de eroare.
Trecerea pe live
Cheile live sunt legate de aprobarea agenției: până când agenția ta este aprobată, o cheie live răspunde cu agency_not_active, iar cheia ta sandbox continuă să funcționeze. Comenzile live se plătesc dintr-un sold de agenție alimentat. Trecerea pe live schimbă cheia, nu codul, pentru că sandbox și live folosesc același URL de bază.
Cine construiește pe API-ul eSIM
Fiecare public se sprijină pe o altă parte a acelorași apeluri.
Agenții care vând călătorii
Agențiile vând un eSIM alături de zbor și de hotel. Comandă cu adresa de email a călătorului, astfel încât furnizorul trimite codul QR și un link de partajare, și citesc consumul când un călător întreabă. Rata comisionului vine cu fiecare pachet, iar agent_id înregistrează care utilizator al agenției tale a plasat o comandă.
OTA și marketplace-uri
Marketplace-urile construiesc mai întâi pagina de răsfoire: o țară pe rând, pachete locale sau regionale, rețelele și volumul de date al fiecărui pachet și o verificare a dispozitivului înainte ca călătorul să cumpere. Un ecran care listează eSIM-urile unui călător poate citi consumul a cel mult 50 dintre ele într-un singur apel.
Echipe de tehnologie pentru turism și echipe corporative
Echipele de tehnologie pentru turism și departamentele de călătorii corporative își construiesc propriile instrumente de rezervare. Tot ce le trebuie pentru a începe este public: fișierul OpenAPI, colecția Postman și documentația în text simplu pe care o poate citi un asistent AI de programare, astfel încât primul prototip pornește de la contractul real.
API eSIM: întrebări frecvente
Ce este API-ul eSIM FX-Port și cui se adresează?
Este un API REST cu ajutorul căruia o agenție de turism, un OTA sau un revânzător vinde eSIM-uri de date pentru călătorii dintr-o singură integrare. Listezi pachetele unei destinații, cu prețuri în moneda agenției tale, și comanzi unul pentru un călător. Îi dai călătorului codul QR, urmărești consumul și reîncarci. Totul este JSON peste HTTPS, iar un fișier OpenAPI descrie fiecare endpoint.
Există un sandbox gratuit și cum obțin o cheie?
Da. Creează un cont FX-Port, deschide pagina API din panoul de control și creează o cheie sandbox; o poți face singur, fără costuri. O comandă în sandbox creează un eSIM de test cu un cod de activare fictiv, deci nu poate fi instalat pe un telefon. Nu se debitează nimic din soldul tău. Sandbox și live folosesc același URL de bază, așa că codul pe care îl testezi este codul pe care îl lansezi.
Ce este necesar pentru a trece pe live?
Agenția ta trebuie să fie aprobată înainte ca o cheie live să funcționeze. Până atunci o cheie live este refuzată, iar cheia sandbox continuă să funcționeze. Comenzile live se plătesc dintr-un sold de agenție alimentat, pe care sandbox-ul nu îl atinge niciodată, iar orice cheie poate fi blocată pe o listă de adrese IP. Trecerea înseamnă doar schimbarea cheii; fiecare răspuns indică mediul din care provine.
Ce țări și ce pachete pot vinde?
Pachetele sunt disponibile pentru peste 190 de țări, iar pachetele regionale apar la regiunea lor. Pachetele diferă prin volumul de date, valabilitate, rețele și prin faptul că pot fi reîncărcate sau nu. Citește aceste câmpuri și id-ul pachetului din răspunsul catalogului, în loc să le scrii fix în cod. Cere câte o țară pe rând, pentru că întregul catalog este un răspuns foarte mare. O listă separată de dispozitive îți permite să verifici telefonul călătorului înainte de vânzare.
Cum primește călătorul eSIM-ul?
Răspunsul comenzii conține codul QR, șirul lui de activare, un link de instalare pentru iPhone și o pagină de partajare. Le poți afișa în propriile ecrane. FX-Port îi cere și furnizorului să trimită prin email codul QR și un link de partajare la adresa călătorului, imediat ce eSIM-ul este creat. Dacă furnizorul nu a returnat încă eSIM-ul, comanda există oricum, iar datele sunt disponibile ulterior din apelul pentru datele de configurare.
Cum se leagă prețurile, comisionul și soldul meu?
Fiecare pachet conține aceste câmpuri financiare în moneda agenției tale: prețul de bază înainte de comision, prețul total de încasat de la călător, suma debitată din soldul tău și rata comisionului tău. Comisionul tău este prețul total minus debitul. Citește aceste câmpuri în loc să le reconstruiești, pentru că debitul este specific agenției tale. În sandbox nu se debitează nimic; pe live, debitul iese din soldul agenției tale.
Pot reîncărca un eSIM și cum văd ce a rămas?
Da, în două apeluri: listezi pachetele care pot fi adăugate exact acelui eSIM, apoi creezi reîncărcarea cu unul dintre ele. O reîncărcare nu este mereu posibilă, deoarece un furnizor poate schimba operatorul unei țări. O listă goală înseamnă atunci că ai nevoie de un eSIM nou pentru călător. Consumul este păstrat în cache cel mult 15 min, deci tratează-l ca pe o cifră recentă, iar un apel citește cel mult 50 eSIM-uri.
Cum sunt raportate erorile și există webhook-uri?
Un eșec vine într-un singur format, cu un cod de eroare stabil, iar programul tău trebuie să testeze codul, nu textul mesajului. Citirile pot fi repetate fără risc, cu backoff. Crearea unei comenzi sau a unei reîncărcări este diferită: nu există cheie de idempotență, deci după o expirare caută rezervarea înainte de a încerca din nou. FX-Port refuză un duplicat evident, de exemplu același pachet comandat de două ori în cel mult 60 s pe live. Nu există webhook-uri.
Pot anula sau rambursa o comandă eSIM prin API?
Nu. API-ul nu are un endpoint pentru anularea sau rambursarea unei comenzi eSIM. Fiecare comandă creează exact un eSIM, așa că verifică pachetul și datele călătorului înainte de a o trimite. Dacă furnizorul refuză o comandă, nu se debitează nimic și se salvează o rezervare eșuată. Pentru o problemă legată de o comandă anume, scrie echipei de dezvoltatori și menționează id-ul rezervării.
De ce am nevoie ca să încep și ce instrumente ajută?
Ai nevoie de o cheie sandbox și de un client HTTP. Documentația adaugă un fișier OpenAPI 3.1, o colecție Postman, exemple de cod în 9 limbaje și exporturi în text simplu pentru asistenți AI. Păstrează cheile pe serverul tău, niciodată într-un browser sau într-o aplicație. Partea care durează mai mult este propriul tău proces de plată, livrarea codului QR către călător și tratarea erorilor.
Alte API-uri FX-Port
Un eSIM merge de obicei cu o călătorie. Zborurile și hotelurile folosesc aceleași chei, același corp de eroare și aceleași convenții ca eSIM-urile, iar rezervările lor se află în același istoric al contului.
Caută, calculează prețul și rezervă zboruri, plătește comenzile ținute, anulează și citește biletele.
Găsește hoteluri, verifică tarifele, pre-rezervă și rezervă, citește voucherele și anulează.
- API TransferuriPreview
Cere ofertă, rezervă, urmărește și anulează transferuri aeroportuale.
Preferi să nu scrii cod? Agențiile pot vinde eSIM-uri și din panoul de control FX-Port. Vinde eSIM-uri din panoul de control
Rulează prima ta comandă eSIM în sandbox
Creează un cont, fă o cheie sandbox, listează pachete, creează o comandă și citește consumul chiar astăzi. Cheile live urmează după ce agenția ta este aprobată.
Întreabă un asistent AI despre acest API
Deschide această pagină într-un asistent și cere un plan de integrare pas cu pas.
