NowośćREST API z plikiem OpenAPI 3.1
API eSIM dla biur podróży, OTA i resellerów
Sprzedawaj eSIM dla podróżnych przez jedno REST API. Wyświetlaj pakiety danych według kraju z cenami w walucie agencji, zamawiaj eSIM dla podróżnego, przekazuj mu kod QR, sprawdzaj zużycie i doładowuj. Jeden bazowy URL obsługuje sandbox i Live. Zacznij od bezpłatnego klucza sandbox; klucze Live działają po zatwierdzeniu Twojej agencji.
Dokumentacja jest dostępna w języku angielskim.
- Bazowy URL
https://api.fx-port.com/api/v1- Uwierzytelnianie
Authorization: Bearer fxp_test_...- Prefiksy kluczy
fxp_test_ / fxp_live_- Endpointy
- 12
- Kraje z pakietami
- 190+
- Języki przykładów kodu
- 9
API eSIM, wywołanie po wywołaniu
Prześledź sprzedaż eSIM krok po kroku: każde żądanie jest budowane, wysyłane i otrzymuje odpowiedź. Sesje obejmują sprzedaż eSIM, utrzymanie łączności podróżnego, sprawdzanie urządzeń i rezerwacji oraz błędy, które warto obsłużyć. Żądania i odpowiedzi to przykłady z dokumentacji, a ta strona nigdy nie wywołuje API.
3 żądania: Wyświetl pakiety, Zamów eSIM, Odczytaj dane konfiguracyjne.
Sesja poglądowa: treści żądań i odpowiedzi to przykłady z dokumentacji, daty są przesunięte do przodu, by zawsze wypadały po dniu dzisiejszym, a czasy mają charakter poglądowy. Ta strona nie wysyła żadnych żądań.
Znajdź pakiet, zamów go, odczytaj dane konfiguracyjne
Zacznij od pakietów jednego kraju, zamów jeden dla podróżnego, a potem odczytaj dane konfiguracyjne zamówienia. Sandbox tworzy testowe eSIM z fikcyjnym kodem aktywacyjnym i niczego nie obciąża, a konsola pokazuje skróconą kopię odpowiedzi z katalogu.
Wyświetl pakiety
Wywołanie katalogu przyjmuje
countryitypei zwraca pasujące pakiety z cenami w walucie agencji. Zachowajpackage_idpakietu wybranego przez podróżnego.Żądanie GET /esims/packages curl 'https://api.fx-port.com/api/v1/esims/packages?country=france&type=local' \ -H "Authorization: Bearer fxp_test_YOUR_KEY"Odpowiedź 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 } }Przykład skrócony do wyświetlenia
- PASS Kod statusu to 200
- PASS $.success równa się true
- PASS $.data[0].package_id istnieje
- PASS $.data[0].balance_debit_amount istnieje
Zamów eSIM
Utworzenie zamówienia wymaga
package_idoraz adresu e-mail i numeru telefonu podróżnego. Zachowaj z odpowiedzibooking_ididata.iccid. W sandboxiebalanceDebited,transactionCreatedipayoutCreatedmają wartośćfalse.Żądanie 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" }'Odpowiedź 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 }Przykład skrócony do wyświetlenia
- PASS Kod statusu to 200
- PASS $.environment równa się sandbox
- PASS $.balance_debited równa się false
- PASS $.data.iccid istnieje
Odczytaj dane konfiguracyjne
Wywołanie z danymi konfiguracyjnymi przyjmuje
booking_idi zwraca kod QR, dane aktywacyjne, linki instalacyjne i kroki instalacji zamówienia. Pokazuj je tylko podróżnemu, który jest właścicielem eSIM.Żądanie 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"Odpowiedź 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" } }Przykład skrócony do wyświetlenia
- PASS Kod statusu to 200
- PASS $.data.package_id równa się france-in-7days-1gb
- PASS $.data.sims[0].iccid istnieje
Opis GET /esims/bookings/{booking_id}/setup-instructions w dokumentacji
Odczytaj zużycie, potem doładuj
Gdy podróżny ma już eSIM, odczytaj, ile danych zostało, zapytaj, które pakiety można dodać do tego konkretnego eSIM, a potem utwórz doładowanie. Zużycie jest zapisywane w pamięci podręcznej, więc wartość może mieć kilka minut. Historia doładowań jest na pasku bocznym i w transkrypcji.
Odczytaj zużycie
Wywołanie zużycia przyjmuje ICCID zamówienia i zwraca
remainingoraztotalw megabajtach,statusi termin ważności. Odpowiedź pochodzi z pamięci podręcznej, aforce=trueponownie pyta dostawcę.Żądanie GET /esims/usage/{iccid} curl https://api.fx-port.com/api/v1/esims/usage/8900000540463077957 \ -H "Authorization: Bearer fxp_test_YOUR_KEY"Odpowiedź 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 Kod statusu to 200
- PASS $.data.data.status równa się ACTIVE
- PASS $.data.data.remaining istnieje
Pakiety doładowań
To wywołanie wyświetla pakiety, które można dziś dodać do tego konkretnego eSIM. Pusta lista oznacza, że teraz nie można go doładować.
package_iddoładowania weź z tej listy, nigdy z pierwotnego zamówienia.Żądanie GET /esims/topup-packages/{iccid} curl https://api.fx-port.com/api/v1/esims/topup-packages/8900000540463077957 \ -H "Authorization: Bearer fxp_test_YOUR_KEY"Odpowiedź 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 } ] } }Przykład skrócony do wyświetlenia
- PASS Kod statusu to 200
- PASS $.data.data ma 2 elementy
- PASS $.data.data[0].type równa się topup
Utwórz doładowanie
Utworzenie doładowania wymaga
package_idz tej listy i ICCID. Na Live saldo jest obciążane dopiero po przyjęciu przez dostawcę. W sandboxiebalancew odpowiedzi wynosi zero i nic nie jest obciążane.Żądanie 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" }'Odpowiedź 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 Kod statusu to 200
- PASS $.environment równa się sandbox
- PASS $.balance_debited równa się false
- PASS $.data.balance.current równa się 0
Historia doładowań
Historia doładowań zawiera doładowania jednego eSIM, od najnowszych. Doładowań nie ma na liście rezerwacji, więc tu je znajdziesz.
Żądanie 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"Odpowiedź 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 Kod statusu to 200
- PASS $.data[0].type równa się topup
Opis GET /esims/bookings/{iccid}/topup-history w dokumentacji
Sprawdź urządzenie, potem odczytaj rezerwacje
Przed sprzedażą sprawdź, czy telefon podróżnego obsługuje eSIM. Po sprzedaży odczytaj swoje rezerwacje i sprawdź, czy dany numer rezerwacji należy do Ciebie. Zbiorczy odczyt zużycia jest na pasku bocznym.
Sprawdź listę urządzeń
Wywołanie zgodnych urządzeń zwraca urządzenia znane z obsługi eSIM, z polami
brand,modelios. Wyszukaj telefon podróżnego przed sprzedażą.Żądanie GET /esims/compatible-devices curl https://api.fx-port.com/api/v1/esims/compatible-devices \ -H "Authorization: Bearer fxp_test_YOUR_KEY"Odpowiedź 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 Kod statusu to 200
- PASS $.success równa się true
- PASS $.data[0].model istnieje
Wyświetl rezerwacje
Lista rezerwacji zwraca zamówienia eSIM Twojej agencji, od najnowszych. To żądanie prosi o jedną rezerwację przez
limit, apaginationmówi, ile zamówień pasuje i czy następuje kolejna strona.Żądanie GET /esims/bookings curl 'https://api.fx-port.com/api/v1/esims/bookings?limit=1' \ -H "Authorization: Bearer fxp_test_YOUR_KEY"Odpowiedź 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 Kod statusu to 200
- PASS $.data ma 1 element
- PASS $.pagination.has_more równa się true
Sprawdź własność
Sprawdzenie własności odpowiada
is_ownero wartości true, gdy rezerwacja należy do Twojej agencji. Rezerwacja innej agencji i rezerwacja, która nie istnieje, dostają tę samą odpowiedź, więc wywołanie nie służy do odgadywania numerów.Żądanie 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"Odpowiedź 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 Kod statusu to 200
- PASS $.is_owner równa się true
Zbiorczy odczyt zużycia
Jedno wywołanie odczytuje zużycie kilku eSIM wymienionych w
iccidsi zwraca jeden wpis na ICCID, każdy z własnymstatus. Zawsze wysyłajiccids.Żądanie GET /esims/usage/bulk curl 'https://api.fx-port.com/api/v1/esims/usage/bulk?iccids=8900000540463077957' \ -H "Authorization: Bearer fxp_test_YOUR_KEY"Odpowiedź 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 Kod statusu to 200
- PASS $.data[0].status równa się success
Niepowodzenia i jak reagować na każde
Wszystkie niepowodzenia mają jedną treść, a pierwszy element errors ma stały code. Te wywołania zamówień kończą się błędem celowo, każde z innego powodu i z inną reakcją.
Klucz Odczyt przy zamówieniu
Klucz Odczyt użyty w wywołaniu zamówienia jest odrzucany kodem
403iread_write_permission_required, zanim treść zostanie odczytana. Przełącz się na klucz Odczyt + zapis.Żądanie 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" }'Odpowiedź 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 Kod statusu to 403
- PASS Kod błędu to read_write_permission_required
- PASS $.errors[0].type równa się permission_error
Nieprawidłowy adres e-mail
Wartość, która nie jest adresem e-mail, jest odrzucana kodem
400iinvalid_email, afieldwskazujeemail. Popraw wartość, zanim ponownie wyślesz zamówienie: to samo żądanie zakończy się tak samo.Żądanie 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" }'Odpowiedź 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 Kod statusu to 400
- PASS Kod błędu to invalid_email
- PASS $.errors[0].field równa się email
Zdublowane zamówienie
Zamówienie pakietu, który jest już przetwarzany, jest odrzucane kodem
409iduplicate_request. Nie wysyłaj go od razu ponownie: najpierw wyszukaj rezerwację i zamów ponownie tylko wtedy, gdy żadna nie powstała.Żądanie 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" }'Odpowiedź 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 Kod statusu to 409
- PASS Kod błędu to duplicate_request
- PASS $.errors[0].type równa się conflict
Zbyt wiele żądań
Po przekroczeniu limitu na minutę wywołanie jest odrzucane kodem
429irate_limit_exceeded, a nagłówekRetry-Afterpodaje, ile sekund czekać. Potem ponów z backoffem.Żądanie 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" }'Odpowiedź 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 Kod statusu to 429
- PASS Kod błędu to rate_limit_exceeded
- PASS Nagłówek Retry-After jest obecny
- PASS $.errors[0].details.retry_after równa się 12
Od katalogu do podróżnego z łącznością w pięciu krokach
Integracja to krótka ścieżka: odczytaj katalog, utwórz zamówienie, przekaż podróżnemu eSIM, śledź zużycie i doładuj, gdy skończą się dane. Zmieniają coś tylko zamówienie i doładowanie. Każde inne wywołanie tylko odczytuje.
Odczytaj katalog dla jednego kierunku
Wyświetl pakiety jednego kraju, z cenami już w walucie agencji, i zachowaj package_id pakietu wybranego przez podróżnego. Zawsze wysyłaj country: cały katalog to bardzo duża odpowiedź bez paginacji. Identyfikatory pakietów odczytuj z odpowiedzi zamiast wpisywać je na stałe, bo katalog się zmienia.
Żądanie
curl 'https://api.fx-port.com/api/v1/esims/packages?country=france&type=local' \
-H "Authorization: Bearer fxp_test_YOUR_KEY"Odpowiedź 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
}
}Utwórz zamówienie
Wyślij package_id razem z adresem e-mail i numerem telefonu podróżnego. Jedno zamówienie tworzy dokładnie jedno eSIM, a na Live obciąża saldo Twojej agencji. Zachowaj z odpowiedzi booking_id i ICCID, bo każde kolejne wywołanie potrzebuje jednego z nich.
Żądanie
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"
}'Odpowiedź 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
}| Pole | Co zawiera |
|---|---|
booking_id | Numer zamówienia w FX-Port. Zachowaj go na potrzeby danych konfiguracyjnych, sprawdzenia własności i własnej ewidencji. |
data.iccid | Identyfikator eSIM. Zużycie, doładowania i instrukcje instalacji są pobierane według ICCID. |
data.sim.qrcode data.sim.qrcode_url | Ciąg aktywacyjny zakodowany w kodzie QR oraz link do obrazu kodu QR. |
data.sim.direct_apple_installation_url data.sim.sharing | Link uruchamiający instalację na iPhonie oraz strona udostępniania, na której podróżny może otworzyć eSIM za pomocą kodu dostępu. Link dla Androida dodaje wywołanie z danymi konfiguracyjnymi. |
PENDING-, a dane będą dostępne w wywołaniu z danymi konfiguracyjnymi, gdy tylko dostawca je przekaże.Przekaż podróżnemu eSIM
Odpowiedź zawiera kod QR i jego ciąg aktywacyjny, więc możesz pokazać je na własnych ekranach. FX-Port prosi też dostawcę o wysłanie kodu QR i linku do udostępnienia na adres e-mail podróżnego, więc nie musisz tego przekazywać dalej. Wywołanie z danymi konfiguracyjnymi zwraca te same dane ponownie, także później, wraz z krokami instalacji.
Żądanie
curl https://api.fx-port.com/api/v1/esims/bookings/FX-1793546602916/setup-instructions \
-H "Authorization: Bearer fxp_test_YOUR_KEY"Odpowiedź 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
}
}Śledź zużycie
Odczytaj pozostałe dane i termin ważności eSIM według jego ICCID. Odpowiedź jest przechowywana w pamięci podręcznej nawet do 15 minut, więc używaj jej na ekranie lub w przypomnieniu, a nie jako licznika.
Żądanie
curl https://api.fx-port.com/api/v1/esims/usage/8900000540463077957 \
-H "Authorization: Bearer fxp_test_YOUR_KEY"Odpowiedź 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"
}
}
}Doładuj, gdy skończą się dane
Wyświetl pakiety, które można dodać do tego konkretnego eSIM, a potem utwórz doładowanie z jednym z nich. Jeśli lista jest pusta, tego eSIM nie można teraz doładować i podróżny potrzebuje nowego.
Żądanie
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"
}'Odpowiedź 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
}Ceny, prowizja i Twoje saldo
Każdy pakiet zawiera pola z kwotami, obliczone na serwerze w walucie Twojej agencji. Cena przesłana w treści żądania jest ignorowana, więc zamówienie zawsze powstaje po cenie wyliczonej przez serwer.
| Pole | Co zawiera |
|---|---|
base_price price | Cena pakietu przed doliczeniem Twojej prowizji. To nie jest kwota obciążająca Twoje saldo. |
total_price retail_price | Cena do pobrania od podróżnego, z wliczoną Twoją prowizją. |
balance_debit_amount b2b_price | Kwota odejmowana od salda agencji, gdy zamawiasz pakiet na Live. Odczytuj ją, nie wyliczaj. |
agency_commission commission_rate | Twoja stawka prowizji, jako tekst i jako liczba. Rezerwacje zwracają Twoją prowizję jako kwotę. |
W przykładzie z katalogu podróżny płaci 468.84 DZD. Zamówienie na Live obciąża Twoje saldo kwotą 418.60 DZD, a różnica, 50.24 DZD, to Twoja prowizja.
Stawka należy do Twojej agencji
Stawka prowizji wraca z każdym pakietem i nie jest taka sama dla każdej agencji. Agencja korporacyjna objęta umową może mieć stawkę zero, a wtedy cena całkowita jest równa obciążeniu.
Odczytuj pola, nie odtwarzaj ich
Obciążenie może być wyższe od ceny bazowej, bo wchodzą w nie kwoty specyficzne dla Twojej agencji. Dlatego odczytuj balance_debit_amount i nigdy nie wyliczaj go z base_price. Słowo price oznacza cenę bazową w katalogu, ale cenę detaliczną w zamówieniach, pakietach doładowań i danych konfiguracyjnych: używaj wszędzie base_price i total_price, a niejednoznaczność zniknie.
Ceny w walucie Twojej agencji
Każda kwota jest już przeliczona na walutę Twojej agencji, niezależnie od waluty dostawcy. Odpowiedź pokazuje też walutę dostawcy i kurs wymiany, więc możesz sam sprawdzić kurs i nigdy nie musisz przeliczać ponownie.
Po sprzedaży: zużycie, doładowania i dane konfiguracyjne
Sprzedaż nie kończy się na zamówieniu. Te wywołania utrzymują łączność podróżnego i działają tylko dla eSIM zamówionych przez Twoją agencję w tym samym środowisku co Twój klucz.
Odczyt zużycia i jego aktualność
Wywołanie zużycia zwraca pozostałe dane, limit pakietu, status i termin ważności jednego eSIM albo nawet 50 eSIM w jednym wywołaniu. FX-Port przechowuje ostatnią odpowiedź nawet do 15 minut, aby chronić limity zapytań dostawcy, więc podana wartość może być tak stara. Przekaż force=true, aby ponownie zapytać dostawcę, na przykład tuż po doładowaniu. Nie rób tego przy każdym żądaniu, bo dostawca ogranicza częstotliwość odczytu zużycia. Jeśli dostawca nie może odpowiedzieć, otrzymasz ostatnią znaną wartość oznaczoną jako nieaktualną.
Doładowania: najpierw zapytaj, potem utwórz
Doładowanie to dwa wywołania. Najpierw wyświetl pakiety, które można dodać do tego konkretnego eSIM, a potem utwórz doładowanie z jednym ze zwróconych identyfikatorów pakietu. Nigdy nie używaj ponownie identyfikatora pakietu z pierwotnego zamówienia i nie przechowuj pakietu doładowania na później: zapytaj ponownie, gdy podróżny zechce doładować eSIM. Doładowanie dodaje dane do eSIM i nie zastępuje tego, co zostało, więc wynik odczytaj ze zużycia z force=true.
Gdy doładowanie nie jest możliwe
Dostawcy wybierają, którzy operatorzy sieci komórkowych obsługują dany kraj, i w rzadkich przypadkach zmieniają któregoś z nich. eSIM może wtedy działać do wygaśnięcia, a jego pakietu nie można już doładować. Lista pakietów doładowań wraca pusta. Jeśli dostawca odrzuci doładowanie, Twoje saldo pozostaje nietknięte, a próba zostaje zapisana jako nieudana rezerwacja. Odpowiedzią jest supplier_error, na który możesz zareagować.
Dane konfiguracyjne i kroki instalacji
Wywołanie z danymi konfiguracyjnymi zwraca kod QR, dane aktywacyjne, linki instalacyjne i kroki instalacji zamówienia, kiedy tylko ich potrzebujesz. Wywołanie z instrukcjami zwraca kroki dla każdego systemu operacyjnego, w żądanym języku. Kroki to ogólny tekst od dostawcy, więc pokaż je obok kodu QR zamówienia. Oba pokazuj tylko podróżnemu, który jest właścicielem eSIM.
Rezerwacje, historia doładowań i własność
Lista rezerwacji zwraca zamówienia eSIM Twojej agencji w środowisku Twojego klucza, od najnowszych. Możesz ją przeszukiwać według numeru rezerwacji, nazwiska podróżnego, adresu e-mail, nazwy pakietu lub ICCID. Doładowań nie ma na tej liście: odczytaj je z historii doładowań danego eSIM. Zanim zbudujesz link lub ekran wokół numeru rezerwacji, sprawdzenie własności powie, czy jest Twój. Rezerwacja innej agencji i rezerwacja, która nie istnieje, dostają tę samą odpowiedź.
Każdy endpoint eSIM, z OpenAPI, Postmanem i przykładami kodu
API eSIM ma 12 endpointów pod jednym bazowym URL. Każdy wiersz otwiera stronę referencyjną danego wywołania z polami żądania, odpowiedziami, błędami i przykładami w 9 językach.
| Endpoint | Do czego służy | Klucz |
|---|---|---|
GET /api/v1/esims/packages | Wyświetla pakiety jednego kraju lub regionu z cenami już w walucie agencji. Zawsze wysyłaj kraj: cały katalog jest bardzo duży i nie ma paginacji. | Odczyt |
GET /api/v1/esims/compatible-devices | Urządzenia znane z obsługi eSIM, do sprawdzenia, zanim podróżny kupi. | Odczyt |
POST /api/v1/esims/orders | Tworzy jedno eSIM z pakietu dla podróżnego i konfiguruje je u dostawcy. Na Live obciąża saldo agencji. | Odczyt + zapis |
GET /api/v1/esims/topup-packages/{iccid} | Pakiety, które można dziś dodać do jednego konkretnego eSIM. Pusta lista oznacza, że teraz nie można go doładować. | Odczyt |
POST /api/v1/esims/topups | Dodaje pakiet doładowania do istniejącego eSIM. Na Live saldo jest obciążane dopiero po przyjęciu przez dostawcę. | Odczyt + zapis |
GET /api/v1/esims/usage/{iccid} | Pozostałe dane, limit, status i termin ważności jednego eSIM. Odpowiedź może mieć nawet 15 minut. | Odczyt |
GET /api/v1/esims/usage/bulk | Zużycie nawet 50 eSIM w jednym wywołaniu, jeden wpis na ICCID, każdy z własnym statusem. | Odczyt |
GET /api/v1/esims/bookings | Zamówienia eSIM Twojej agencji, od najnowszych, z wyszukiwaniem i paginacją. Doładowań nie ma na tej liście. | Odczyt |
GET /api/v1/esims/bookings/{iccid}/topup-history | Doładowania jednego eSIM, od najnowszych. Lista jest pusta, gdy eSIM nie ma żadnego doładowania. | Odczyt |
GET /api/v1/esims/bookings/{booking_id}/verify | Sprawdza, czy numer rezerwacji należy do Twojej agencji, zanim zbudujesz wokół niego link lub ekran. | Odczyt |
GET /api/v1/esims/bookings/{booking_id}/setup-instructions | Kod QR, dane aktywacyjne, linki instalacyjne i kroki instalacji zamówienia, jako JSON. | Odczyt |
GET /api/v1/esims/instructions/{iccid} | Instrukcje instalacji krok po kroku dla jednego ICCID, osobno dla każdego systemu operacyjnego, w żądanym języku. | Odczyt |
OpenAPI 3.1
Jeden plik opisuje każdy endpoint i każde pole. Wygeneruj z niego klienta, zaimportuj go do narzędzia API albo przekaż asystentowi programistycznemu.
Kolekcja Postman
Kolekcja eSIM obejmuje wszystkie 12 endpointów w folderach odpowiadających etapom sprzedaży. Nie zawiera kluczy, więc dodaj własne.
Przykłady kodu w 9 językach
Każda strona referencyjna pokazuje swoje żądanie w cURL, Node.js, Python, PHP, Go, Java, C#, Swift i Kotlin, wygenerowane z opisu OpenAPI. Każde żądanie eSIM jest dostępne we wszystkich z nich.
Dokumentacja dla asystentów AI
llms.txt i llms-full.txt przekazują asystentom AI dokumentację jako zwykły tekst, a każdą stronę dokumentacji można odczytać jako Markdown, dodając .md do jej adresu.
Gotowe na produkcję: klucze, błędy, ponowienia i buforowanie
Integracja eSIM jest oceniana na produkcji pod kątem uwierzytelniania, błędów, ponowień, buforowania i limitów zapytań. Oto, co warto wiedzieć o każdym z nich.
Jeden bazowy URL, dwa rodzaje kluczy
Każde żądanie zawiera klucz jako token Bearer w nagłówku Authorization. Prefiks mówi, gdzie klucz działa: fxp_test_ w sandboxie i fxp_live_ na Live. Oba trafiają na ten sam bazowy URL, a każda odpowiedź JSON podaje w environment, z jakiego środowiska pochodzi. Klucze należą na Twój serwer, nigdy do przeglądarki ani aplikacji. FX-Port przechowuje tylko skrót każdego klucza, więc zgubionego klucza nie można wyświetlić ponownie. Zmiana klucza może zacząć działać po kilku minutach.
Który klucz do jakiego wywołania
Klucz Odczyt może wyświetlać pakiety, sprawdzać urządzenia, odczytywać zużycie i rezerwacje. Utworzenie zamówienia lub doładowania wymaga klucza Odczyt + zapis, a klucz Odczyt, który spróbuje to zrobić, dostaje read_write_permission_required. Każdy klucz można ograniczyć do listy adresów IP, a wywołanie z innego adresu dostaje ip_not_allowed. Tam, gdzie kod tylko wyświetla wyniki, używaj klucza Odczyt.
Jeden format błędu dla każdego niepowodzenia
Nieudane wywołanie zwraca tablicę errors. Jej pierwszy element ma stały code, type mówiący, jak zareagować, i field, którego dotyczy błąd. Testuj kod, nigdy komunikat. Lista błędów wspólna dla lotów, hoteli, eSIM i konta zawiera 180 kodów. Gdy dostawca odrzuci zamówienie lub doładowanie, odpowiedzią jest supplier_error z własnym statusem HTTP dostawcy. Nic nie jest obciążane, a nieudana rezerwacja zostaje zapisana. Tuż po restarcie katalog i lista urządzeń mogą odpowiedzieć 202 z success ustawionym na false: poczekaj kilka sekund i zapytaj ponownie.
Ponawianie bez podwójnego zamówienia
FX-Port nie ma klucza idempotentności, więc nie ma nagłówka Idempotency-Key do wysłania. Odczyty można bezpiecznie powtarzać; utworzenia zamówienia lub doładowania nie. FX-Port odrzuca oczywisty duplikat kodem 409 i duplicate_request: zamówienie pakietu, który jest jeszcze przetwarzany. Na Live odrzuca też ten sam pakiet zamówiony ponownie w ciągu 60 sekund od ostatniego potwierdzonego zamówienia Twojej agencji, niezależnie od podróżnego. Zamówienia zwykle odpowiadają w kilka sekund, ale wolny dostawca może potrzebować znacznie więcej. Jeśli wywołanie przekroczy limit czasu lub połączenie zostanie zerwane, nie wysyłaj zamówienia od razu ponownie, bo eSIM może już istnieć. Poszukaj go parametrem search listy rezerwacji, podając adres e-mail podróżnego, i zamów ponownie tylko wtedy, gdy nic nie powstało.
Bez webhooków: pytasz, gdy potrzebujesz
FX-Port nie wywołuje żadnego Twojego adresu URL, ani w sandboxie, ani na Live. Zamówienie odpowiada eSIM albo znacznikiem PENDING-, dopóki dostawca go nie zwróci. O wszystko inne pytasz wtedy, gdy tego potrzebujesz: dane konfiguracyjne, zużycie lub listę rezerwacji.
Buforowanie i szybkość
Zużycie jest przechowywane nawet do 15 minut, a lista pakietów doładowań przez kilka minut, a force=true pomija pamięć podręczną. Katalog bez filtra to bardzo duża odpowiedź bez paginacji, więc wysyłaj country i akceptuj kompresję przez Accept-Encoding: gzip. Nazwy pakietów wracają w języku parametru locale; pierwsze żądanie w języku innym niż angielski jest wolniejsze, bo tekst jest wtedy pobierany, a potem buforowany.
Limity zapytań
Limity są liczone na klucz i na minutę w dwóch grupach, a każda odpowiedź zawiera ratelimit-limit i ratelimit-remaining, więc możesz zwolnić, zanim zostaniesz odrzucony. Po 429 poczekaj liczbę sekund z Retry-After i ponów z wykładniczym backoffem i jitterem. Zbyt wiele zamówień lub doładowań jednego klucza albo agencji wykonywanych jednocześnie może dostać odpowiedź concurrency_limit_exceeded.
| Rodzaj wywołania | Na minutę |
|---|---|
| Tworzenie zamówień i doładowań | 1,200 |
| Każdy inny endpoint eSIM | 6,000 |
Na razie pułap zamówień i doładowań wykonywanych jednocześnie działa w trybie obserwacji: jest liczony, ale nie egzekwowany, więc nic nie jest jeszcze z jego powodu odrzucane, a dzień jego egzekwowania ogłosi changelog. Traktuj te liczby jako obecną politykę, a nie obietnicę. Klucze sandbox mają te same liczniki na minutę co klucze Live, więc testy obciążeniowe planuj według harmonogramu, zamiast uruchamiać je w pętli.
Nazwy i wersje
Pola żądań mają format snake_case, na przykład first_name i agent_id. Starsze zapisy nadal działają: user_id jest odczytywane jako agent_id i dodaje wpis w warnings, a customer_email jest przyjmowane jako email bez takiego wpisu. W wielu odpowiedziach starszy klucz zostaje obok swojego odpowiednika snake_case z tą samą wartością, na przykład order_id obok code, a ?naming=snake zwraca wyłącznie klucze snake_case. Wersja jest w ścieżce, /api/v1: zmiana łamiąca zgodność dostałaby nowy prefiks, a nowe pola i zapisy są tylko dodawane, bez łamania zgodności.
Zacznij w bezpłatnym sandboxie, potem przejdź na Live
Wszystko na tej stronie działa dziś w sandboxie. Klucz sandbox zakładasz sam, jest bezpłatny i nigdy nie dotyka Twojego prawdziwego salda.
Załóż konto
Zarejestruj konto w FX-Port. Klucze sandbox są bezpłatne, a rezerwacje w sandboxie nie generują żadnych rzeczywistych opłat.
Utwórz klucz sandbox
Na stronie API w panelu utwórz klucz zaczynający się od
fxp_test_. Klucz Odczyt może wyszukiwać i odczytywać dane; klucz Odczyt + zapis może także tworzyć rezerwacje testowe.Wyślij pierwsze żądanie
Adres bazowy jest jeden, a klucz przekazujesz w nagłówku
Authorizationjako token Bearer. Pierwsze wywołanie krok po kroku opisuje przewodnik Szybki start.Przejdź na Live, gdy będziesz gotowy
Podmień klucz na
fxp_live_. Live działa po zatwierdzeniu Twojej agencji; do tego czasu API odpowiada403 agency_not_active. Rzeczywiste rezerwacje opłaca się z zasilonego salda.
Pierwsze żądanie do katalogu w cURL. Dokumentacja pokazuje to samo żądanie w każdym obsługiwanym języku.
Żądanie
curl 'https://api.fx-port.com/api/v1/esims/packages?country=france&type=local' \
-H "Authorization: Bearer fxp_test_YOUR_KEY"Szybki start: pierwsze wywołanie w sandboxie
Co robi sandbox
Zamówienie w sandboxie tworzy u dostawcy prawdziwe testowe eSIM z fikcyjnym kodem aktywacyjnym, więc nie da się go zainstalować w telefonie. Nic nie jest obciążane, o czym informują odpowiedzi: balanceDebited, transactionCreated i payoutCreated mają wartość false. Doładowanie zwraca saldo równe zero. Zużycie jest statyczne: nowe eSIM pokazuje pełny limit i status ACTIVE. Rezerwacje z sandboxa są widoczne tylko dla kluczy sandbox.
Co może sprawdzić tylko Live
Kontrola salda, kontrola duplikatów i blokada salda działają tylko na Live. Dlatego odpowiedzi 402 z insufficient_balance, 409 dla tego samego pakietu zamówionego ponownie w ciągu 60 sekund oraz 503 z balance_lock_timeout nigdy nie pojawiają się w sandboxie. Ich obsługę napisz na podstawie listy kodów błędów.
Przejście na Live
Klucze Live są powiązane z zatwierdzeniem agencji: dopóki Twoja agencja nie zostanie zatwierdzona, klucz Live odpowiada agency_not_active, a Twój klucz sandbox nadal działa. Zamówienia Live są opłacane z zasilonego salda agencji. Przejście na Live zmienia klucz, nie kod, bo sandbox i Live mają jeden bazowy URL.
Kto buduje na API eSIM
Każda grupa opiera się na innej części tych samych wywołań.
Agencje sprzedające podróże
Agencje sprzedają eSIM razem z lotem i hotelem. Zamawiają z własnym adresem e-mail podróżnego, aby dostawca wysłał kod QR i link do udostępnienia, a zużycie odczytują, gdy podróżny o nie zapyta. Stawka prowizji wraca z każdym pakietem, a agent_id zapisuje, który użytkownik Twojej agencji złożył zamówienie.
OTA i marketplace’y
Marketplace’y budują najpierw stronę przeglądania: jeden kraj naraz, pakiety lokalne lub regionalne, sieci i limit danych każdego pakietu oraz sprawdzenie urządzenia, zanim podróżny kupi. Ekran z listą eSIM podróżnego może odczytać zużycie nawet 50 z nich w jednym wywołaniu.
Zespoły travel-tech i korporacyjne
Zespoły technologiczne branży turystycznej i działy podróży służbowych budują własne narzędzia rezerwacyjne. Wszystko, czego potrzebują na start, jest publiczne: plik OpenAPI, kolekcja Postman i dokumentacja w postaci zwykłego tekstu, którą może czytać asystent AI do programowania, więc pierwszy prototyp powstaje na podstawie prawdziwego kontraktu.
API eSIM: najczęstsze pytania
Czym jest API eSIM FX-Port i dla kogo jest przeznaczone?
To REST API, dzięki któremu biuro podróży, OTA lub reseller sprzedaje eSIM z danymi dla podróżnych w ramach jednej integracji. Wyświetlasz pakiety danego kierunku z cenami w walucie agencji i zamawiasz jeden dla podróżnego. Przekazujesz mu kod QR, śledzisz zużycie i doładowujesz. Wszystko to JSON przez HTTPS, a plik OpenAPI opisuje każdy endpoint.
Czy jest bezpłatny sandbox i jak zdobyć klucz?
Tak. Załóż konto FX-Port, otwórz stronę API w panelu i utwórz klucz sandbox; możesz to zrobić sam, bez żadnych kosztów. Zamówienie w sandboxie tworzy testowe eSIM z fikcyjnym kodem aktywacyjnym, więc nie da się go zainstalować w telefonie. Twoje saldo nie jest obciążane. Sandbox i Live mają jeden bazowy URL, więc kod, który testujesz, jest kodem, który wdrażasz.
Czego wymaga przejście na Live?
Twoja agencja musi zostać zatwierdzona, zanim klucz Live zacznie działać. Do tego czasu klucz Live jest odrzucany, a Twój klucz sandbox nadal działa. Zamówienia Live są opłacane z zasilonego salda agencji, którego sandbox nigdy nie dotyka, a każdy klucz można ograniczyć do listy adresów IP. Przejście oznacza wyłącznie zmianę klucza; każda odpowiedź podaje środowisko, z którego pochodzi.
Jakie kraje i pakiety mogę sprzedawać?
Pakiety są dostępne dla ponad 190 krajów, a pakiety regionalne pojawiają się pod swoim regionem. Pakiety różnią się limitem danych, okresem ważności, sieciami i możliwością doładowania. Te pola oraz identyfikator pakietu odczytuj z odpowiedzi katalogu zamiast wpisywać je na stałe. Pytaj o jeden kraj naraz, bo cały katalog to bardzo duża odpowiedź. Osobna lista urządzeń pozwala sprawdzić telefon podróżnego przed sprzedażą.
Jak podróżny otrzymuje eSIM?
Odpowiedź na zamówienie zawiera kod QR, jego ciąg aktywacyjny, link instalacyjny dla iPhone’a i stronę udostępniania. Możesz pokazać je na własnych ekranach. FX-Port prosi też dostawcę o wysłanie kodu QR i linku do udostępnienia na adres e-mail podróżnego, gdy tylko eSIM zostanie utworzone. Jeśli dostawca nie zwrócił jeszcze eSIM, zamówienie i tak istnieje, a dane będą dostępne później w wywołaniu z danymi konfiguracyjnymi.
Jak łączą się ceny, prowizja i moje saldo?
Każdy pakiet zawiera te pola z kwotami w walucie agencji: cenę bazową przed prowizją, cenę całkowitą do pobrania od podróżnego, kwotę obciążającą Twoje saldo oraz stawkę prowizji. Twoja prowizja to cena całkowita minus obciążenie. Odczytuj te pola zamiast je odtwarzać, bo obciążenie jest specyficzne dla Twojej agencji. W sandboxie nic nie jest obciążane; na Live obciążenie opuszcza saldo agencji.
Czy mogę doładować eSIM i jak sprawdzić, ile zostało?
Tak, w dwóch wywołaniach: wyświetl pakiety, które można dodać do danego eSIM, a potem utwórz doładowanie z jednym z nich. Doładowanie nie zawsze jest możliwe, bo dostawca może zmienić operatora w danym kraju. Pusta lista oznacza wtedy, że podróżny potrzebuje nowego eSIM. Zużycie jest przechowywane w pamięci podręcznej nawet do 15 minut, więc traktuj je jako niedawną wartość, a jedno wywołanie odczytuje nawet 50 eSIM.
Jak raportowane są błędy i czy są webhooki?
Błąd wraca w jednym formacie ze stałym kodem błędu, i to ten kod powinien testować Twój program, a nie treść komunikatu. Odczyty można bezpiecznie powtarzać z backoffem. Utworzenie zamówienia lub doładowania jest inne: nie ma klucza idempotentności, więc po przekroczeniu limitu czasu wyszukaj rezerwację, zanim spróbujesz ponownie. FX-Port odrzuca oczywisty duplikat, na przykład ten sam pakiet zamówiony dwa razy w ciągu 60 sekund na Live. Webhooków nie ma.
Czy mogę anulować zamówienie eSIM lub zwrócić środki przez API?
Nie. API nie ma endpointu do anulowania zamówienia eSIM ani do zwrotu środków. Każde zamówienie tworzy dokładnie jedno eSIM, więc sprawdź pakiet i dane podróżnego, zanim je wyślesz. Jeśli dostawca odrzuci zamówienie, nic nie jest obciążane, a nieudana rezerwacja zostaje zapisana. W sprawie konkretnego zamówienia napisz do zespołu deweloperskiego i podaj numer rezerwacji.
Czego potrzebuję na start i jakie narzędzia pomagają?
Potrzebujesz klucza sandbox i klienta HTTP. Dokumentacja dodaje plik OpenAPI 3.1, kolekcję Postman, przykłady kodu w 9 językach oraz eksporty w zwykłym tekście dla asystentów AI. Trzymaj klucze na swoim serwerze, nigdy w przeglądarce ani aplikacji. Dłużej zajmie Ci własny proces zakupowy, przekazanie kodu QR podróżnemu i obsługa błędów.
Inne API FX-Port
eSIM zwykle idzie w parze z podróżą. Loty i hotele używają tych samych kluczy, tej samej treści błędów i tych samych konwencji co eSIM, a ich rezerwacje trafiają do tej samej historii konta.
Wyszukuj, wyceniaj i rezerwuj loty, opłacaj wstrzymane zamówienia, anuluj i odczytuj bilety.
Znajdź hotele, sprawdzaj stawki, dokonuj wstępnej rezerwacji i rezerwacji, odczytuj vouchery i anuluj.
- API transferówPodgląd
Wyceniaj, rezerwuj, śledź i anuluj transfery lotniskowe.
Wolisz nie pisać kodu? Agencje mogą też sprzedawać eSIM z panelu FX-Port. Sprzedaż eSIM z panelu
Złóż pierwsze zamówienie eSIM w sandboxie
Załóż konto, utwórz klucz sandbox, wyświetl pakiety, złóż zamówienie i odczytaj zużycie już dziś. Klucze Live otrzymasz po zatwierdzeniu Twojej agencji.
Zapytaj asystenta AI o to API
Otwórz tę stronę w asystencie i poproś o plan integracji krok po kroku.
