YeniOpenAPI 3.1 dosyalı REST API
Seyahat acenteleri, OTA’lar ve bayiler için eSIM API’si
Seyahat eSIM’lerini tek bir REST API üzerinden satışa sunun. Ülkeye göre veri paketlerini acente para biriminizle fiyatlı listeleyin, yolcu için sipariş verin, yolcuya QR kodunu iletin, kullanımı izleyin ve ek paket yükleyin. Tek bir temel URL hem sandbox hem canlı ortama hizmet verir. Ücretsiz bir sandbox anahtarıyla başlayın; canlı anahtarlar acenteniz onaylandıktan sonra çalışır.
Dokümantasyon İngilizce yazılmıştır.
- Temel URL
https://api.fx-port.com/api/v1- Kimlik doğrulama
Authorization: Bearer fxp_test_...- Anahtar önekleri
fxp_test_ / fxp_live_- Endpoint’ler
- 12
- Paketi olan ülkeler
- 190+
- Kod örneği dilleri
- 9
eSIM API’si, çağrı çağrı
Bir eSIM satışını, her istek oluşturulup gönderildikçe ve yanıtlandıkça adım adım izleyin. Oturumlar eSIM satışını, yolcunun bağlantısını sürdürmeyi, cihaz ve rezervasyon kontrolünü ve ele almaya değer hataları kapsar. İstekler ve yanıtlar dokümantasyondan alınmış örneklerdir; bu sayfa API’yi hiç çağırmaz.
3 istek: Paketleri listeleyin, eSIM siparişi verin, Kurulum verisini okuyun.
Örnek oturum: gövdeler dokümantasyondaki örneklerdir, tarihler bugünden sonraya denk gelecek şekilde ileri kaydırılmıştır ve süreler örnek niteliğindedir. Bu sayfa hiçbir istek göndermez.
Paketi bulun, sipariş verin, kurulum verisini okuyun
Bir ülkenin paketleriyle başlayın, yolcu için birini sipariş edin, sonra siparişin kurulum verisini okuyun. Sandbox, sahte etkinleştirme koduna sahip bir test eSIM’i oluşturur ve hiçbir şey düşmez; konsol, katalog yanıtının kısaltılmış bir kopyasını gösterir.
Paketleri listeleyin
Katalog çağrısı
countryvetypealır, eşleşen paketleri acente para biriminizle fiyatlı döndürür. Yolcunun seçtiği paketinpackage_iddeğerini saklayın.İstek GET /esims/packages curl 'https://api.fx-port.com/api/v1/esims/packages?country=france&type=local' \ -H "Authorization: Bearer fxp_test_YOUR_KEY"Yanıt 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 } }Örnek, gösterim için kısaltıldı
- PASS Durum kodu 200
- PASS $.success değeri true
- PASS $.data[0].package_id mevcut
- PASS $.data[0].balance_debit_amount mevcut
eSIM siparişi verin
Sipariş oluşturma,
package_iddeğerini yolcunun e-posta adresi ve telefon numarasıyla birlikte alır. Yanıttakibooking_idvedata.icciddeğerlerini saklayın. Sandbox’tabalanceDebited,transactionCreatedvepayoutCreatedalanlarının üçü defalseolur.İstek 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" }'Yanıt 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 }Örnek, gösterim için kısaltıldı
- PASS Durum kodu 200
- PASS $.environment değeri sandbox
- PASS $.balance_debited değeri false
- PASS $.data.iccid mevcut
Kurulum verisini okuyun
Kurulum verisi çağrısı
booking_idalır; siparişin QR kodunu, etkinleştirme verisini, kurulum bağlantılarını ve kurulum adımlarını döndürür. Bunları yalnızca eSIM’in sahibi olan yolcuya gösterin.İstek 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"Yanıt 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" } }Örnek, gösterim için kısaltıldı
- PASS Durum kodu 200
- PASS $.data.package_id değeri france-in-7days-1gb
- PASS $.data.sims[0].iccid mevcut
Dokümantasyonda GET /esims/bookings/{booking_id}/setup-instructions başvurusu
Kullanımı okuyun, sonra ek paket yükleyin
Yolcunun eSIM’i olduktan sonra kalan veriyi okuyun, tam olarak bu eSIM’e hangi paketlerin eklenebileceğini sorun, sonra ek paketi oluşturun. Kullanım önbellekten gelir; bu yüzden bir değer dakikalarca eski olabilir. Ek paket geçmişi kenar çubuğunda ve istek-yanıt kaydında yer alır.
Kullanımı okuyun
Kullanım çağrısı siparişin ICCID değerini alır; megabayt cinsinden
remainingvetotaldeğerlerini,statusalanını ve bitiş tarihini döndürür. Yanıt önbellekten gelir;force=truetedarikçiye yeniden sorar.İstek GET /esims/usage/{iccid} curl https://api.fx-port.com/api/v1/esims/usage/8900000540463077957 \ -H "Authorization: Bearer fxp_test_YOUR_KEY"Yanıt 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 Durum kodu 200
- PASS $.data.data.status değeri ACTIVE
- PASS $.data.data.remaining mevcut
Ek paketleri listeleyin
Bu çağrı, bugün tam olarak bu eSIM’e eklenebilecek paketleri listeler. Liste boşsa eSIM’e şu an ek paket yüklenemez. Ek paketin
package_iddeğerini bu listeden alın, asla ilk siparişten almayın.İstek GET /esims/topup-packages/{iccid} curl https://api.fx-port.com/api/v1/esims/topup-packages/8900000540463077957 \ -H "Authorization: Bearer fxp_test_YOUR_KEY"Yanıt 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 } ] } }Örnek, gösterim için kısaltıldı
- PASS Durum kodu 200
- PASS $.data.data içinde 2 öğe var
- PASS $.data.data[0].type değeri topup
Ek paketi oluşturun
Ek paket oluşturma, o listedeki
package_iddeğerini ve ICCID’yi alır. Canlı ortamda bakiyeniz yalnızca tedarikçi kabul ettikten sonra düşer. Sandbox’ta yanıttakibalancesıfırdır ve hiçbir şey düşmez.İstek 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" }'Yanıt 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 Durum kodu 200
- PASS $.environment değeri sandbox
- PASS $.balance_debited değeri false
- PASS $.data.balance.current değeri 0
Ek paket geçmişini okuyun
Ek paket geçmişi, bir eSIM’in ek paketlerini en yeniden eskiye doğru listeler. Ek paketler rezervasyon listesinde yer almaz; onları burada bulursunuz.
İstek 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"Yanıt 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 Durum kodu 200
- PASS $.data[0].type değeri topup
Dokümantasyonda GET /esims/bookings/{iccid}/topup-history başvurusu
Cihazı kontrol edin, sonra rezervasyonlarınızı okuyun
Satıştan önce yolcunun telefonunun eSIM desteklediğini kontrol edin. Satıştan sonra rezervasyonlarınızı okuyun ve bir rezervasyon kimliğinin size ait olduğunu doğrulayın. Toplu kullanım kenar çubuğunda listelenir.
Cihaz listesine bakın
Uyumlu cihazlar çağrısı, eSIM desteklediği bilinen cihazları
brand,modelveosalanlarıyla döndürür. Satıştan önce yolcunun telefonunu listede arayın.İstek GET /esims/compatible-devices curl https://api.fx-port.com/api/v1/esims/compatible-devices \ -H "Authorization: Bearer fxp_test_YOUR_KEY"Yanıt 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 Durum kodu 200
- PASS $.success değeri true
- PASS $.data[0].model mevcut
Rezervasyonlarınızı listeleyin
Rezervasyon listesi, acentenizin eSIM siparişlerini en yeniden eskiye doğru döndürür. Bu istek
limitile tek bir rezervasyon ister;paginationkaç siparişin eşleştiğini ve başka bir sayfanın olup olmadığını söyler.İstek GET /esims/bookings curl 'https://api.fx-port.com/api/v1/esims/bookings?limit=1' \ -H "Authorization: Bearer fxp_test_YOUR_KEY"Yanıt 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 Durum kodu 200
- PASS $.data içinde 1 öğe var
- PASS $.pagination.has_more değeri true
Sahipliği kontrol edin
Sahiplik kontrolü, rezervasyon acentenize aitse
is_owneriçin true yanıtını verir. Başka bir acentenin rezervasyonu ile var olmayan bir rezervasyon aynı yanıtı alır; bu yüzden çağrı rezervasyon kimliklerini keşfetmek için kullanılamaz.İstek 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"Yanıt 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 Durum kodu 200
- PASS $.is_owner değeri true
Dokümantasyonda GET /esims/bookings/{booking_id}/verify başvurusu
Kullanımı toplu okuyun
Tek çağrı,
iccidsiçinde listelenen birkaç eSIM’in kullanımını okur ve her ICCID için kendistatusalanıyla bir kayıt döndürür.iccidsalanını her zaman gönderin.İstek GET /esims/usage/bulk curl 'https://api.fx-port.com/api/v1/esims/usage/bulk?iccids=8900000540463077957' \ -H "Authorization: Bearer fxp_test_YOUR_KEY"Yanıt 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 Durum kodu 200
- PASS $.data[0].status değeri success
Hatalar ve her birine nasıl tepki verilir
Tüm hatalar tek bir gövdeyi paylaşır ve errors içindeki ilk kaydın sabit bir code değeri vardır. Bu sipariş çağrıları bilerek başarısız olur; her biri farklı bir nedenle ve farklı bir tepkiyle.
Siparişte Okuma anahtarı
Sipariş çağrısında Okuma anahtarı, gövde okunmadan önce
403veread_write_permission_requiredile reddedilir. Okuma+Yazma anahtarına geçin.İstek 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" }'Yanıt 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 Durum kodu 403
- PASS Hata kodu read_write_permission_required
- PASS $.errors[0].type değeri permission_error
Geçersiz e-posta adresi
E-posta adresi olmayan bir değer
400veinvalid_emailile reddedilir;fieldalanıemailadını verir. Siparişi yeniden göndermeden önce değeri düzeltin: aynı istek aynı şekilde başarısız olur.İstek 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" }'Yanıt 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 Durum kodu 400
- PASS Hata kodu invalid_email
- PASS $.errors[0].field değeri email
Yinelenen sipariş
Zaten işlenmekte olan bir paket için verilen sipariş
409veduplicate_requestile reddedilir. Hemen yeniden göndermeyin: önce rezervasyonu arayın, ancak hiç oluşmamışsa yeniden sipariş verin.İstek 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" }'Yanıt 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 Durum kodu 409
- PASS Hata kodu duplicate_request
- PASS $.errors[0].type değeri conflict
Çok fazla istek
Dakikalık sınır aşılınca çağrı
429verate_limit_exceededile reddedilir;Retry-Afterbaşlığı kaç saniye bekleneceğini söyler. Sonra backoff ile yeniden deneyin.İstek 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" }'Yanıt 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 Durum kodu 429
- PASS Hata kodu rate_limit_exceeded
- PASS Retry-After başlığı mevcut
- PASS $.errors[0].details.retry_after değeri 12
Katalogdan bağlantıdaki yolcuya beş adımda
Entegrasyon kısa bir yoldur: kataloğu okuyun, siparişi oluşturun, eSIM’i yolcuya verin, kullanımı izleyin ve veri bitince ek paket yükleyin. Yalnızca sipariş ve ek paket bir şeyi değiştirir. Diğer tüm çağrılar yalnızca okur.
Bir destinasyonun kataloğunu okuyun
Bir ülkenin paketlerini, fiyatlar zaten acente para biriminizde olacak şekilde listeleyin ve yolcunun seçtiği paketin package_id değerini saklayın. Her zaman country gönderin: sayfalama olmadan tüm katalog çok büyük bir yanıttır. Katalog değiştiği için paket kimliklerini koda sabitlemek yerine yanıttan okuyun.
İstek
curl 'https://api.fx-port.com/api/v1/esims/packages?country=france&type=local' \
-H "Authorization: Bearer fxp_test_YOUR_KEY"Yanıt 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
}
}Siparişi oluşturun
package_id değerini yolcunun e-posta adresi ve telefon numarasıyla birlikte gönderin. Bir sipariş tam olarak bir eSIM oluşturur ve canlı ortamda acente bakiyenizden düşer. Sonraki her çağrı bunlardan birine ihtiyaç duyduğu için yanıttaki booking_id ve ICCID değerlerini saklayın.
İstek
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"
}'Yanıt 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
}| Alan | İçerdiği bilgi |
|---|---|
booking_id | Siparişin FX-Port referansı. Kurulum verisi, sahiplik kontrolü ve kendi kayıtlarınız için saklayın. |
data.iccid | eSIM’in tanımlayıcısı. Kullanım, ek paket ve kurulum talimatları ICCID ile sorulur. |
data.sim.qrcode data.sim.qrcode_url | QR kodun kodladığı etkinleştirme dizesi ve QR kod görselinin bağlantısı. |
data.sim.direct_apple_installation_url data.sim.sharing | iPhone’da kurulumu başlatan bir bağlantı ve yolcunun eSIM’i erişim koduyla açabileceği bir paylaşım sayfası. Kurulum verisi çağrısı Android bağlantısını ekler. |
PENDING- ile başlar ve veri, tedarikçide hazır olunca kurulum verisi çağrısından alınabilir.eSIM’i yolcuya verin
Yanıt, QR kodunu ve etkinleştirme dizesini taşır; böylece bunları kendi ekranlarınızda gösterebilirsiniz. FX-Port ayrıca tedarikçiden QR kodunu ve bir paylaşım bağlantısını yolcunun adresine e-postayla göndermesini ister; yani iletmekle uğraşmazsınız. Kurulum verisi çağrısı aynı veriyi kurulum adımlarıyla birlikte daha sonra yeniden döndürür.
İstek
curl https://api.fx-port.com/api/v1/esims/bookings/FX-1793546602916/setup-instructions \
-H "Authorization: Bearer fxp_test_YOUR_KEY"Yanıt 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
}
}Kullanımı izleyin
Bir eSIM’in kalan verisini ve bitiş tarihini ICCID ile okuyun. Yanıt en fazla 15 dakika önbellekte tutulur; bu yüzden bir ekran veya hatırlatma için kullanın, sayaç olarak değil.
İstek
curl https://api.fx-port.com/api/v1/esims/usage/8900000540463077957 \
-H "Authorization: Bearer fxp_test_YOUR_KEY"Yanıt 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"
}
}
}Veri bitince ek paket yükleyin
Tam olarak bu eSIM’e eklenebilecek paketleri listeleyin, sonra bunlardan biriyle ek paket yüklemesini oluşturun. Liste boşsa eSIM’e şu an ek paket yüklenemez ve yolcunun yeni bir eSIM’e ihtiyacı vardır.
İstek
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"
}'Yanıt 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
}Fiyatlar, komisyon ve bakiyeniz
Her paket, sunucuda acente para biriminizle hesaplanmış para alanlarını taşır. İstek gövdesindeki fiyat yok sayılır; bu yüzden sipariş her zaman sunucunun hesapladığı fiyattan oluşturulur.
| Alan | İçerdiği bilgi |
|---|---|
base_price price | Komisyonunuzdan önceki paket fiyatı. Bakiyenizden düşen tutar değildir. |
total_price retail_price | Yolcuya yansıtılacak fiyat; komisyonunuz dahildir. |
balance_debit_amount b2b_price | Paketi canlı ortamda sipariş ettiğinizde acente bakiyenizden çıkan tutar. Hesaplamayın, okuyun. |
agency_commission commission_rate | Komisyon oranınız, metin ve sayı olarak. Rezervasyonlar ise komisyonunuzu tutar olarak döndürür. |
Katalog örneğinde yolcu 468.84 DZD öder. Canlı ortamdaki bir sipariş bakiyenizden 418.60 DZD düşer; aradaki fark olan 50.24 DZD sizin komisyonunuzdur.
Oran acentenize aittir
Komisyon oranı her paketle birlikte gelir ve her acente için aynı değildir. Sözleşmeli kurumsal bir acentenin oranı sıfır olabilir; bu durumda toplam fiyat borçlandırılan tutara eşittir.
Alanları okuyun, yeniden hesaplamayın
Borçlandırılan tutar, acentenize özgü tutarlar dahil olduğu için baz fiyattan yüksek olabilir. Bu yüzden balance_debit_amount alanını okuyun, base_price alanından asla hesaplamayın. price sözcüğü katalogda baz fiyat, ancak siparişlerde, ek paketlerde ve kurulum verisinde perakende fiyattır: her yerde base_price ve total_price kullanın, belirsizlik ortadan kalkar.
Acente para biriminizle fiyatlandırılır
Tedarikçi hangi para birimini kullanırsa kullansın, her tutar zaten acente para biriminize çevrilmiştir. Yanıt ayrıca tedarikçi para birimini ve döviz kurunu gösterir; kuru kendiniz doğrulayabilirsiniz ve bir daha çeviri yapmanız gerekmez.
Satıştan sonra: kullanım, ek paket ve kurulum verisi
Satış siparişle bitmez. Bu çağrılar yolcunun bağlantısını sürdürür ve yalnızca acentenizin, anahtarınızla aynı ortamda sipariş ettiği eSIM’lerde çalışır.
Kullanımı okumak ve ne kadar güncel olduğu
Kullanım yanıtı, bir eSIM’in veya tek çağrıda en fazla 50 eSIM’in kalan verisini, toplam hakkını, durumunu ve bitiş tarihini döndürür. FX-Port, tedarikçinin istek sınırlarını korumak için son yanıtı en fazla 15 dakika saklar; yani bir değer bu kadar eski olabilir. Tedarikçiye yeniden sormak için force=true gönderin, örneğin ek paketten hemen sonra. Her istekte bunu yapmayın, çünkü tedarikçi kullanımın ne sıklıkla okunabileceğini sınırlar. Tedarikçi yanıt veremezse, eski olarak işaretlenmiş son bilinen değeri alırsınız.
Ek paket: önce sorun, sonra oluşturun
Ek paket iki çağrıdır. Önce tam olarak bu eSIM’e eklenebilecek paketleri listeleyin, sonra dönen paket kimliklerinden biriyle ek paketi oluşturun. İlk siparişin paket kimliğini asla yeniden kullanmayın ve bir ek paketi sonraya saklamayın: yolcu ek paket istediğinde yeniden sorun. Ek paket eSIM’e veri ekler, kalanın yerine geçmez; sonucu force=true ile kullanım çağrısından okuyun.
Ek paket mümkün olmadığında
Tedarikçiler bir ülkeyi hangi mobil operatörlerin karşılayacağını seçer ve nadir durumlarda birini değiştirir. Bu durumda eSIM süresi dolana kadar çalışmaya devam edebilir, ancak paketine artık ek paket yüklenemez. Ek paket listesi boş döner. Bir tedarikçi ek paketi reddederse bakiyenize dokunulmaz ve deneme başarısız rezervasyon olarak kaydedilir. Yanıt, tepki verebileceğiniz bir supplier_error olur.
Kurulum verisi ve kurulum adımları
Kurulum verisi çağrısı, bir siparişin QR kodunu, etkinleştirme verisini, kurulum bağlantılarını ve kurulum adımlarını ihtiyaç duyduğunuz her an döndürür. Talimat çağrısı adımları işletim sistemine göre, istediğiniz dilde döndürür. Adımlar tedarikçiden gelen genel metindir; bu yüzden siparişin QR kodunun yanında gösterin. İkisini de yalnızca eSIM’in sahibi olan yolcuya gösterin.
Rezervasyonlar, ek paket geçmişi ve sahiplik
Rezervasyon listesi, acentenizin eSIM siparişlerini anahtarınızın ortamında, en yeniden eskiye doğru döndürür. Rezervasyon kimliği, yolcu adı, e-posta adresi, paket adı veya ICCID ile arayabilirsiniz. Ek paketler bu listede yer almaz: bir eSIM’in ek paket geçmişinden okuyun. Bir rezervasyon kimliği etrafında bağlantı veya ekran kurmadan önce sahiplik kontrolü size onun sizin olup olmadığını söyler. Başka bir acentenin rezervasyonu ile var olmayan bir rezervasyon aynı yanıtı alır.
Tüm eSIM endpoint’leri; OpenAPI, Postman ve kod örnekleriyle
eSIM API’si tek temel URL altında 12 endpoint sunar. Her satır, o çağrının istek alanlarını, yanıtlarını, hatalarını ve 9 dilde örneklerini içeren başvuru sayfasını açar.
| Endpoint | Ne yapar | Anahtar |
|---|---|---|
GET /api/v1/esims/packages | Bir ülkenin veya bölgenin paketlerini, fiyatlar zaten acente para biriminizde olacak şekilde listeler. Her zaman bir ülke gönderin: tüm katalog çok büyüktür ve sayfalaması yoktur. | Okuma |
GET /api/v1/esims/compatible-devices | eSIM desteklediği bilinen cihazlar; yolcu satın almadan önce kontrol etmek için. | Okuma |
POST /api/v1/esims/orders | Bir paketten yolcu için bir eSIM oluşturur ve tedarikçide hazırlar. Canlıda acente bakiyenizden düşer. | Okuma+Yazma |
GET /api/v1/esims/topup-packages/{iccid} | Bugün belirli bir eSIM’e eklenebilecek paketler. Boş liste, eSIM’e şu an ek paket yüklenemediği anlamına gelir. | Okuma |
POST /api/v1/esims/topups | Mevcut bir eSIM’e ek paket ekler. Canlıda bakiyeniz yalnızca tedarikçi kabul ettikten sonra düşer. | Okuma+Yazma |
GET /api/v1/esims/usage/{iccid} | Bir eSIM’in kalan verisi, toplam hakkı, durumu ve bitiş tarihi. Yanıt en fazla 15 dakika eski olabilir. | Okuma |
GET /api/v1/esims/usage/bulk | Tek çağrıda en fazla 50 eSIM’in kullanımı; her ICCID için ayrı bir kayıt ve kendi durumu. | Okuma |
GET /api/v1/esims/bookings | Acentenizin eSIM siparişleri, en yeniden eskiye doğru, arama ve sayfalamayla. Ek paketler bu listede yer almaz. | Okuma |
GET /api/v1/esims/bookings/{iccid}/topup-history | Bir eSIM’in ek paketleri, en yeniden eskiye doğru. eSIM’de hiç ek paket yoksa liste boş döner. | Okuma |
GET /api/v1/esims/bookings/{booking_id}/verify | Bir rezervasyon kimliğinin acentenize ait olduğunu, etrafında bir bağlantı veya ekran kurmadan önce doğrulayın. | Okuma |
GET /api/v1/esims/bookings/{booking_id}/setup-instructions | Bir siparişin QR kodu, etkinleştirme verisi, kurulum bağlantıları ve kurulum adımları, JSON olarak. | Okuma |
GET /api/v1/esims/instructions/{iccid} | Bir ICCID için işletim sistemine göre adım adım kurulum talimatı, istediğiniz dilde. | Okuma |
OpenAPI 3.1
Tek bir dosya her endpoint’i ve her alanı tanımlar. Ondan istemci üretin, bir API aracına aktarın veya kodlama asistanına verin.
Postman koleksiyonu
eSIM koleksiyonu, bir satışın aşamalarını izleyen klasörlerde 12 endpoint’in tamamını kapsar. İçinde anahtar yoktur; kendi anahtarlarınızı ekleyin.
9 dilde kod örnekleri
Her başvuru sayfası isteği cURL, Node.js, Python, PHP, Go, Java, C#, Swift ve Kotlin ile gösterir; örnekler OpenAPI tanımından üretilir. Her eSIM isteği bunların hepsinde mevcuttur.
Yapay zekâ asistanları için dokümanlar
llms.txt ve llms-full.txt yapay zekâ asistanlarına dokümantasyonu düz metin olarak verir; ayrıca her doküman sayfası adresine .md eklenerek Markdown olarak okunabilir.
Canlı kullanıma hazır: anahtarlar, hatalar, yeniden denemeler ve önbellek
Bir eSIM entegrasyonu canlıda kimlik doğrulama, hatalar, yeniden denemeler, önbellek ve istek sınırlarıyla değerlendirilir. Her biri için bilmeniz gerekenler burada.
Tek temel URL, iki tür anahtar
Her istek, bir anahtarı Authorization başlığında Bearer token olarak taşır. Önek, anahtarın nerede çalıştığını söyler: sandbox için fxp_test_, canlı için fxp_live_. İkisi de aynı temel URL’ye gider ve her JSON yanıtı geldiği ortamı environment alanında belirtir. Anahtarlar sunucunuzda durur; tarayıcıda veya uygulamada asla. FX-Port her anahtarın yalnızca özetini (hash) saklar; bu yüzden kaybolan anahtar yeniden gösterilemez. Bir anahtardaki değişikliğin uygulanması birkaç dakika sürebilir.
Hangi anahtar hangi çağrıyı yapar
Okuma anahtarı paketleri listeleyebilir, cihazları kontrol edebilir, kullanımı ve rezervasyonları okuyabilir. Sipariş veya ek paket oluşturmak Okuma+Yazma anahtarı gerektirir; bunu deneyen bir Okuma anahtarı read_write_permission_required alır. Her anahtar bir IP adresi listesine kilitlenebilir ve başka bir adresten gelen çağrı ip_not_allowed alır. Kod yalnızca sonuçları gösteriyorsa Okuma anahtarı kullanın.
Her hata için tek hata biçimi
Başarısız bir çağrı bir errors dizisi döndürür. İlk girdisinde kararlı bir code, nasıl tepki verileceğini söyleyen bir type ve hatalı field bulunur. Mesajı değil, kodu test edin. Uçuşlar, oteller, eSIM’ler ve hesap için ortak hata listesinde 180 kod vardır. Tedarikçi bir siparişi veya ek paketi reddettiğinde yanıt, tedarikçinin kendi HTTP durumunu taşıyan bir supplier_error olur. Hiçbir tutar düşmez ve başarısız bir rezervasyon kaydedilir. Yeniden başlatmanın hemen ardından katalog ve cihaz listesi, success değeri false olan 202 ile yanıt verebilir: birkaç saniye bekleyip yeniden sorun.
İki kez sipariş vermeden yeniden deneme
FX-Port’ta idempotency anahtarı yoktur, dolayısıyla gönderilecek bir Idempotency-Key başlığı da yoktur. Okumaları tekrarlamak güvenlidir; sipariş veya ek paket oluşturmak değildir. FX-Port bariz bir tekrarı 409 ve duplicate_request ile reddeder: hâlâ işlenen bir paket için verilen sipariş. Canlı ortamda ayrıca, yolcu kim olursa olsun, aynı paketin acentenizin son onaylı siparişinden sonraki 60 saniye içinde yeniden sipariş edilmesini de reddeder. Siparişler genellikle birkaç saniyede yanıtlanır, ancak yavaş bir tedarikçi çok daha uzun sürebilir. Bir çağrı zaman aşımına uğrarsa veya bağlantı koparsa siparişi hemen yeniden göndermeyin, çünkü eSIM oluşmuş olabilir. Rezervasyon listesinin search parametresiyle, yolcunun e-posta adresini kullanarak arayın ve yalnızca hiçbir şey oluşmadıysa yeniden sipariş verin.
Webhook yok: ihtiyaç duyduğunuzda sorun
FX-Port, sandbox’ta da canlıda da sizin bir URL’nizi çağırmaz. Sipariş, eSIM ile ya da tedarikçi henüz döndürmediyse bir PENDING- yer tutucusuyla yanıtlanır. Başka her şeyi ihtiyaç duyduğunuzda siz sorarsınız: kurulum verisini, kullanımı veya rezervasyon listesini.
Önbellek ve hız
Kullanım en fazla 15 dakika, ek paket listesi birkaç dakika saklanır; force=true önbelleği atlar. Filtresiz katalog sayfalama olmadan çok büyük bir yanıttır; bu yüzden country gönderin ve Accept-Encoding: gzip ile sıkıştırmayı kabul edin. Paket başlıkları locale parametresinin diliyle gelir; İngilizce dışındaki bir dilde ilk istek daha yavaştır, çünkü metin o anda alınır ve sonrasında önbelleğe yazılır.
İstek sınırları
Sınırlar anahtar başına ve dakika başına, iki grupta sayılır; her yanıt ratelimit-limit ve ratelimit-remaining taşır, böylece reddedilmeden önce yavaşlayabilirsiniz. 429 sonrasında Retry-After içindeki saniye kadar bekleyin ve üstel backoff ile jitter uygulayarak yeniden deneyin. Aynı anda çalışan çok fazla sipariş veya ek paket yüklemesi (aynı anahtardan ya da aynı acenteden) concurrency_limit_exceeded yanıtını alabilir.
| Çağrı türü | Dakikada |
|---|---|
| Sipariş ve ek paket oluşturma | 1,200 |
| Diğer tüm eSIM endpoint’leri | 6,000 |
Şimdilik aynı anda çalışan sipariş ve ek paket yükleme sınırı gözlem modundadır: sayılır ancak uygulanmaz, yani henüz bu nedenle hiçbir istek reddedilmez; uygulanmaya başlayacağı günü değişiklik günlüğü duyurur. Bu sayıları bir söz değil, güncel politika olarak okuyun. Sandbox anahtarlarının dakika başına sayaçları canlı anahtarlarla aynıdır; bu yüzden yük testlerini döngüde çalıştırmak yerine planlayın.
Adlar ve sürümler
İstek alanları snake_case biçimindedir, örneğin first_name ve agent_id. Eski yazımlar hâlâ çalışır: user_id, agent_id olarak okunur ve bir warnings girdisi ekler; customer_email ise uyarı eklenmeden email olarak kabul edilir. Pek çok yanıt eski bir anahtarı aynı değerli snake_case ikiziyle yan yana tutar, örneğin code yanında order_id; ?naming=snake yalnızca snake_case anahtarlar döndürür. Sürüm yolun içindedir, /api/v1: geriye uyumsuz bir değişiklik yeni bir önek alır, yeni alanlar ve yazımlar ise eklemeli olur.
Ücretsiz sandbox’ta başlayın, sonra canlıya geçin
Bu sayfadaki her şey bugün sandbox’ta çalışır. Sandbox anahtarını kendiniz alırsınız, ücretsizdir ve gerçek bakiyenize hiç dokunmaz.
Hesap oluşturun
Bir FX-Port hesabı için kaydolun. Sandbox anahtarları ücretsizdir ve sandbox rezervasyonları gerçek bir ücret doğurmaz.
Sandbox anahtarı oluşturun
Panelinizdeki API sayfasında
fxp_test_ile başlayan bir anahtar oluşturun. Okuma anahtarı arama yapabilir ve veri okuyabilir; Okuma+Yazma anahtarı ayrıca test rezervasyonu oluşturabilir.İlk isteğinizi gönderin
Tek bir temel URL vardır; anahtar,
Authorizationbaşlığında bearer token olarak gönderilir. Hızlı başlangıç kılavuzu ilk çağrıyı adım adım gösterir.Hazır olduğunuzda canlıya geçin
fxp_live_anahtarıyla değiştirin. Canlı ortam, acenteniz onaylandıktan sonra çalışır; o zamana kadar API403 agency_not_activeyanıtı verir. Gerçek rezervasyonlar, yüklenmiş bir bakiyeden ödenir.
cURL ile ilk katalog isteği. Dokümanlar aynı isteği desteklenen her dilde gösterir.
İstek
curl 'https://api.fx-port.com/api/v1/esims/packages?country=france&type=local' \
-H "Authorization: Bearer fxp_test_YOUR_KEY"Hızlı başlangıç: ilk sandbox çağrısı
Sandbox ne yapar
Sandbox’taki bir sipariş, tedarikçide sahte bir etkinleştirme koduyla gerçek bir test eSIM’i oluşturur; bu yüzden telefona kurulamaz. Hiçbir tutar düşmez ve yanıtlar bunu söyler: balanceDebited, transactionCreated ve payoutCreated hepsi false olur. Ek paket yanıtı sıfır bakiye döndürür. Kullanım sabittir: yeni bir eSIM tam hakkını ve ACTIVE durumunu gösterir. Sandbox rezervasyonları yalnızca sandbox anahtarlarına görünür.
Yalnızca canlıda test edilebilenler
Bakiye kontrolü, tekrar kontrolü ve bakiye kilidi yalnızca canlıda çalışır. Bu yüzden insufficient_balance ile 402, aynı paketin 60 saniye içinde yeniden sipariş edilmesi için 409 ve balance_lock_timeout ile 503 yanıtları sandbox’ta hiç görünmez. Bunların işlenmesini hata kodları listesinden yazın.
Canlıya geçiş
Canlı anahtarlar acente onayına bağlıdır: acenteniz onaylanana kadar canlı anahtar agency_not_active yanıtı verir ve sandbox anahtarınız çalışmaya devam eder. Canlı siparişler, yüklü bir acente bakiyesinden ödenir. Sandbox ve canlı aynı temel URL’yi paylaştığı için canlıya geçmek kodu değil, anahtarı değiştirir.
eSIM API’si üzerine kimler geliştirme yapar
Her kitle aynı çağrıların farklı bir bölümüne dayanır.
Seyahat satan acenteler
Acenteler uçağın ve otelin yanında bir eSIM de satar. Tedarikçinin QR kodunu ve paylaşım bağlantısını göndermesi için yolcunun kendi e-posta adresiyle sipariş verir ve yolcu sorduğunda kullanımı okurlar. Komisyon oranı her paketle birlikte gelir; agent_id ise siparişi acentenizin hangi kullanıcısının verdiğini kaydeder.
OTA’lar ve pazaryerleri
Pazaryerleri önce gezinme sayfasını kurar: her seferinde tek ülke, yerel veya bölgesel paketler, her paketin ağları ve veri hakkı, ve yolcu satın almadan önce cihaz kontrolü. Bir yolcunun eSIM’lerini listeleyen ekran, bunlardan en fazla 50 tanesinin kullanımını tek çağrıda okuyabilir.
Seyahat teknolojisi ve kurumsal ekipler
Seyahat teknolojisi ekipleri ve kurumsal seyahat departmanları kendi rezervasyon araçlarını geliştirir. Başlamak için gereken her şey herkese açıktır: OpenAPI dosyası, Postman koleksiyonu ve bir yapay zekâ kodlama asistanının okuyabileceği düz metin dokümanlar; böylece ilk prototip gerçek sözleşmeden başlar.
eSIM API: sık sorulan sorular
FX-Port eSIM API’si nedir ve kimler içindir?
Seyahat acentesinin, OTA’nın veya bayinin tek bir entegrasyonla seyahat veri eSIM’leri satmasını sağlayan bir REST API’dir. Bir destinasyonun paketlerini acente para biriminizle fiyatlı listeler ve yolcu için sipariş verirsiniz. Yolcuya QR kodunu iletir, kullanımı izler ve ek paket yüklersiniz. Her şey HTTPS üzerinden JSON ile çalışır ve bir OpenAPI dosyası her endpoint’i tanımlar.
Ücretsiz bir sandbox var mı, anahtarı nasıl alırım?
Evet. Bir FX-Port hesabı oluşturun, panelinizdeki API sayfasını açın ve bir sandbox anahtarı oluşturun; bunu kendiniz, ücretsiz yapabilirsiniz. Sandbox’taki bir sipariş, sahte etkinleştirme koduna sahip bir test eSIM’i oluşturur; bu yüzden telefona kurulamaz. Bakiyenizden hiçbir şey düşmez. Sandbox ve canlı ortam tek bir temel URL’yi paylaşır; yani test ettiğiniz kod, yayına aldığınız koddur.
Canlıya geçmek için ne gerekir?
Canlı anahtarın çalışması için acenteniz onaylanmış olmalıdır. O zamana kadar canlı anahtar reddedilir ve sandbox anahtarınız çalışmaya devam eder. Canlı siparişler, sandbox’ın asla dokunmadığı, yüklü bir acente bakiyesinden ödenir; ayrıca her anahtar bir IP adresi listesine kilitlenebilir. Geçiş yalnızca anahtarı değiştirmektir; her yanıt hangi ortamdan geldiğini belirtir.
Hangi ülkeler için hangi paketleri satabilirim?
Paketler 190+ ülke için mevcuttur; bölgesel paketler kendi bölgelerinin altında görünür. Paketler veri hakkı, geçerlilik süresi, şebekeler ve ek paket yüklenip yüklenemediği bakımından farklılaşır. Bu alanları ve paket kimliğini koda sabitlemek yerine katalog yanıtından okuyun. Tüm katalog çok büyük bir yanıt olduğundan her seferinde tek bir ülke isteyin. Ayrı bir cihaz listesi, satıştan önce yolcunun telefonunu kontrol etmenizi sağlar.
Yolcu eSIM’i nasıl alır?
Sipariş yanıtı QR kodunu, etkinleştirme dizesini, iPhone için bir kurulum bağlantısını ve bir paylaşım sayfasını taşır. Bunları kendi ekranlarınızda gösterebilirsiniz. FX-Port ayrıca eSIM oluşturulur oluşturulmaz tedarikçiden QR kodunu ve bir paylaşım bağlantısını yolcunun adresine e-postayla göndermesini ister. Tedarikçi eSIM’i henüz döndürmediyse sipariş yine de vardır ve veri daha sonra kurulum verisi çağrısından alınabilir.
Fiyat, komisyon ve bakiyem nasıl birbirine bağlanır?
Her paket, acente para biriminizde şu tutar alanlarını taşır: komisyonunuzdan önceki temel fiyat, yolcudan tahsil edilecek toplam fiyat, bakiyenizden düşen tutar ve komisyon oranınız. Komisyonunuz, toplam fiyattan bakiyenizden düşen tutarın çıkarılmasıyla bulunur. Düşen tutar acentenize özgü olduğundan bu alanları yeniden hesaplamak yerine okuyun. Sandbox’ta hiçbir şey düşmez; canlı ortamda düşen tutar acente bakiyenizden çıkar.
Bir eSIM’e ek paket yükleyebilir miyim, kalan veriyi nasıl görürüm?
Evet, iki çağrıyla: önce tam olarak bu eSIM’e eklenebilecek paketleri listeleyin, sonra bunlardan biriyle ek paketi oluşturun. Ek paket her zaman mümkün değildir, çünkü bir tedarikçi bir ülkenin operatörünü değiştirebilir. Bu durumda boş liste, yolcunun yeni bir eSIM’e ihtiyacı olduğu anlamına gelir. Kullanım en fazla 15 dakika önbellekte tutulur; bu yüzden onu yakın tarihli bir değer olarak ele alın. Tek çağrı en fazla 50 eSIM okur.
Hatalar nasıl bildirilir, webhook var mı?
Hata, sabit bir hata koduyla tek bir biçimde döner; programınızın sınaması gereken mesaj metni değil, bu koddur. Okuma çağrılarını backoff ile tekrarlamak güvenlidir. Sipariş veya ek paket oluşturma farklıdır: idempotency anahtarı yoktur, bu yüzden zaman aşımından sonra yeniden denemeden önce rezervasyonu arayın. FX-Port, canlı ortamda 60 saniye içinde aynı paketin iki kez sipariş edilmesi gibi bariz bir yinelemeyi reddeder. Webhook yoktur.
API üzerinden bir eSIM siparişini iptal edebilir veya iade edebilir miyim?
Hayır. API’de bir eSIM siparişini iptal etmek veya iade etmek için bir endpoint yoktur. Her sipariş tam olarak bir eSIM oluşturur; bu yüzden göndermeden önce paketi ve yolcunun bilgilerini kontrol edin. Tedarikçi bir siparişi reddederse hiçbir şey düşmez ve başarısız bir rezervasyon kaydedilir. Belirli bir siparişle ilgili sorun için geliştirici ekibine yazın ve rezervasyon kimliğini belirtin.
Başlamak için neye ihtiyacım var, hangi araçlar yardımcı olur?
Bir sandbox anahtarına ve bir HTTP istemcisine ihtiyacınız var. Dokümantasyon buna bir OpenAPI 3.1 dosyası, bir Postman koleksiyonu, 9 dilde kod örnekleri ve yapay zekâ asistanları için düz metin dışa aktarımları ekler. Anahtarlarınızı sunucunuzda tutun; tarayıcıya veya uygulamaya asla koymayın. Daha uzun süren kısım, kendi ödeme akışınız, QR kodunun yolcuya iletilmesi ve hata yönetimidir.
FX-Port’un diğer API’leri
Bir eSIM genellikle bir seyahatle birlikte gider. Uçuş ve otel API’leri, eSIM’lerle aynı anahtarları, aynı hata gövdesini ve aynı kuralları kullanır; rezervasyonları da aynı hesap geçmişinde yer alır.
Uçuşları arayın, fiyatlandırın ve rezerve edin; bekletilen siparişleri ödeyin, iptal edin ve biletleri okuyun.
Otelleri bulun, fiyatları kontrol edin, ön rezervasyon ve rezervasyon yapın, voucher’ları okuyun ve iptal edin.
- Transfer API’siÖnizleme
Havaalanı transferleri için teklif alın, rezervasyon yapın, takip edin ve iptal edin.
Kod yazmak istemiyor musunuz? Acenteler eSIM’leri FX-Port panelinden de satabilir. Panelden eSIM satışı yapın
İlk eSIM siparişinizi sandbox’ta çalıştırın
Hesap oluşturun, sandbox anahtarı alın, paketleri listeleyin, sipariş verin ve kullanımı bugün okuyun. Canlı anahtarlar acenteniz onaylandıktan sonra gelir.
Bu API hakkında bir yapay zekâ asistanına sorun
Bu sayfayı bir asistanda açın ve adım adım entegrasyon planı isteyin.
