E reAPI REST me skedar OpenAPI 3.1
API eSIM për agjenci udhëtimi, OTA dhe rishitës
Shitni eSIM udhëtimi me një API REST. Listoni paketat e të dhënave sipas vendit me çmime në monedhën e agjencisë, porositni një eSIM për udhëtarin, jepuni atij kodin QR, ndiqni përdorimin dhe rifusni. Një URL bazë shërben si sandbox ashtu edhe live. Filloni me një çelës sandbox falas; çelësat live funksionojnë pasi agjencia juaj miratohet.
Dokumentacioni është i shkruar në anglisht.
- URL bazë
https://api.fx-port.com/api/v1- Autentikimi
Authorization: Bearer fxp_test_...- Prefikset e çelësave
fxp_test_ / fxp_live_- Endpoint-e
- 12
- Vende me paketa
- 190+
- Gjuhë të shembujve të kodit
- 9
API eSIM, thirrje pas thirrjeje
Ndiqni një shitje eSIM hap pas hapi, teksa çdo kërkesë ndërtohet, dërgohet dhe merr përgjigje. Skenarët mbulojnë shitjen e një eSIM, mbajtjen e udhëtarit të lidhur, kontrollin e pajisjeve dhe të rezervimeve, si dhe dështimet që vlen t’i trajtoni. Kërkesat dhe përgjigjet janë shembuj nga dokumentacioni, dhe kjo faqe nuk e thërret kurrë API-n.
3 kërkesa: Listoni paketat, Porositni eSIM-in, Lexoni të dhënat e konfigurimit.
Seancë ilustruese: trupat e kërkesave dhe të përgjigjeve janë shembuj nga dokumentacioni, datat janë shtyrë përpara që të mbeten në të ardhmen dhe kohët janë ilustruese. Kjo faqe nuk dërgon asnjë kërkesë.
Gjeni një paketë, porositeni, lexoni të dhënat e konfigurimit
Filloni me paketat e një vendi, porositni një për udhëtarin, pastaj lexoni të dhënat e konfigurimit të porosisë. Sandbox-i krijon një eSIM testimi me kod aktivizimi fiktiv dhe nuk debiton asgjë, dhe konsola tregon një kopje të shkurtuar të përgjigjes së katalogut.
Listoni paketat
Thirrja e katalogut merr
countrydhetypedhe kthen paketat që përputhen, me çmime në monedhën e agjencisë suaj. Ruanipackage_idtë paketës që zgjedh udhëtari.Kërkesa GET /esims/packages curl 'https://api.fx-port.com/api/v1/esims/packages?country=france&type=local' \ -H "Authorization: Bearer fxp_test_YOUR_KEY"Përgjigjja 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 } }Shembull i shkurtuar për shfaqje
- PASS Kodi i statusit është 200
- PASS $.success = true
- PASS $.data[0].package_id ekziston
- PASS $.data[0].balance_debit_amount ekziston
Porositni eSIM-in
Krijimi i një porosie merr
package_idme adresën e email-it dhe numrin e telefonit të udhëtarit. Ruanibooking_iddhedata.iccidnga përgjigja. Në sandbox,balanceDebited,transactionCreateddhepayoutCreatedjanë të gjithafalse.Kërkesa 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" }'Përgjigjja 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 }Shembull i shkurtuar për shfaqje
- PASS Kodi i statusit është 200
- PASS $.environment = sandbox
- PASS $.balance_debited = false
- PASS $.data.iccid ekziston
Lexoni të dhënat e konfigurimit
Thirrja e të dhënave të konfigurimit merr
booking_iddhe kthen kodin QR, të dhënat e aktivizimit, lidhjet e instalimit dhe hapat e instalimit të porosisë. Shfaqini vetëm udhëtarit që zotëron eSIM-in.Kërkesa 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"Përgjigjja 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" } }Shembull i shkurtuar për shfaqje
- PASS Kodi i statusit është 200
- PASS $.data.package_id = france-in-7days-1gb
- PASS $.data.sims[0].iccid ekziston
Referenca e GET /esims/bookings/{booking_id}/setup-instructions në dokumentacion
Lexoni përdorimin, pastaj rifusni
Pasi udhëtari ka një eSIM, lexoni sa të dhëna kanë mbetur, pyesni cilat paketa mund t’i shtohen pikërisht këtij eSIM, pastaj krijoni rifusjen. Përdorimi ruhet në cache, ndaj një shifër mund të jetë disa minuta e vjetër. Historiku i rifusjeve është në shiritin anësor dhe në transkript.
Lexoni përdorimin
Thirrja e përdorimit merr ICCID-në e porosisë dhe kthen
remainingdhetotalnë megabajt,statusdhe skadimin. Përgjigja vjen nga cache, dheforce=truei kërkon përsëri furnizuesit.Kërkesa GET /esims/usage/{iccid} curl https://api.fx-port.com/api/v1/esims/usage/8900000540463077957 \ -H "Authorization: Bearer fxp_test_YOUR_KEY"Përgjigjja 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 Kodi i statusit është 200
- PASS $.data.data.status = ACTIVE
- PASS $.data.data.remaining ekziston
Listoni paketat e rifusjes
Kjo thirrje liston paketat që mund t’i shtohen sot pikërisht këtij eSIM. Një listë bosh do të thotë se eSIM-i nuk mund të rifuset tani. Merrni
package_idtë rifusjes nga kjo listë, kurrë nga porosia origjinale.Kërkesa GET /esims/topup-packages/{iccid} curl https://api.fx-port.com/api/v1/esims/topup-packages/8900000540463077957 \ -H "Authorization: Bearer fxp_test_YOUR_KEY"Përgjigjja 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 } ] } }Shembull i shkurtuar për shfaqje
- PASS Kodi i statusit është 200
- PASS $.data.data ka 2 elemente
- PASS $.data.data[0].type = topup
Referenca e GET /esims/topup-packages/{iccid} në dokumentacion
Krijoni rifusjen
Krijimi i një rifusjeje merr
package_idnga ajo listë dhe ICCID-në. Në live, bilanci juaj debitohet vetëm pasi furnizuesi e pranon. Në sandboxbalancenë përgjigje është zero dhe nuk debitohet asgjë.Kërkesa 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" }'Përgjigjja 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 Kodi i statusit është 200
- PASS $.environment = sandbox
- PASS $.balance_debited = false
- PASS $.data.balance.current = 0
Lexoni historikun e rifusjeve
Historiku i rifusjeve liston rifusjet e një eSIM, më të rejat të parat. Rifusjet nuk janë në listën e rezervimeve, ndaj këtu i gjeni.
Kërkesa 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"Përgjigjja 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 Kodi i statusit është 200
- PASS $.data[0].type = topup
Referenca e GET /esims/bookings/{iccid}/topup-history në dokumentacion
Kontrolloni një pajisje, pastaj lexoni rezervimet
Para shitjes, kontrolloni që telefoni i udhëtarit mbështet eSIM. Pas shitjes, lexoni rezervimet tuaja dhe kontrolloni që një referencë rezervimi është e juaja. Përdorimi në masë renditet në shiritin anësor.
Kontrolloni listën e pajisjeve
Thirrja e pajisjeve të përputhshme kthen pajisjet që dihet se mbështesin eSIM, me
brand,modeldheos. Kërkoni telefonin e udhëtarit para se të shisni.Kërkesa GET /esims/compatible-devices curl https://api.fx-port.com/api/v1/esims/compatible-devices \ -H "Authorization: Bearer fxp_test_YOUR_KEY"Përgjigjja 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 Kodi i statusit është 200
- PASS $.success = true
- PASS $.data[0].model ekziston
Listoni rezervimet tuaja
Lista e rezervimeve kthen porositë eSIM të agjencisë suaj, më të rejat të parat. Kjo kërkesë kërkon një rezervim me
limit, dhepaginationtregon sa porosi përputhen dhe nëse vjen një faqe tjetër.Kërkesa GET /esims/bookings curl 'https://api.fx-port.com/api/v1/esims/bookings?limit=1' \ -H "Authorization: Bearer fxp_test_YOUR_KEY"Përgjigjja 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 Kodi i statusit është 200
- PASS $.data ka 1 element
- PASS $.pagination.has_more = true
Kontrolloni pronësinë
Kontrolli i pronësisë përgjigjet me
is_ownertë vërtetë kur rezervimi i përket agjencisë suaj. Një rezervim i një agjencie tjetër dhe një që nuk ekziston marrin të njëjtën përgjigje, ndaj thirrja nuk mund të përdoret për të zbuluar referenca.Kërkesa 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"Përgjigjja 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 Kodi i statusit është 200
- PASS $.is_owner = true
Referenca e GET /esims/bookings/{booking_id}/verify në dokumentacion
Lexoni përdorimin në masë
Një thirrje lexon përdorimin e disa eSIM-eve të listuara te
iccidsdhe kthen një hyrje për ICCID, secila mestatustë vet. Dërgoni gjithmonëiccids.Kërkesa GET /esims/usage/bulk curl 'https://api.fx-port.com/api/v1/esims/usage/bulk?iccids=8900000540463077957' \ -H "Authorization: Bearer fxp_test_YOUR_KEY"Përgjigjja 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 Kodi i statusit është 200
- PASS $.data[0].status = success
Dështimet dhe si t’u reagoni
Të gjitha dështimet ndajnë një trup, dhe hyrja e parë e errors ka një code të qëndrueshëm. Këto thirrje porosie dështojnë me qëllim, secila për një arsye tjetër dhe me një reagim tjetër.
Çelës Lexim te një porosi
Një çelës Lexim te thirrja e porosisë refuzohet me
403dheread_write_permission_required, para se të lexohet trupi. Kaloni te një çelës Lexim + shkrim.Kërkesa 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" }'Përgjigjja 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 Kodi i statusit është 403
- PASS Kodi i gabimit është read_write_permission_required
- PASS $.errors[0].type = permission_error
Email i pavlefshëm
Një vlerë që nuk është adresë email-i refuzohet me
400dheinvalid_email, dhefieldemërtonemail. Korrigjoni vlerën para se ta dërgoni porosinë përsëri: e njëjta kërkesë dështon njësoj.Kërkesa 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" }'Përgjigjja 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 Kodi i statusit është 400
- PASS Kodi i gabimit është invalid_email
- PASS $.errors[0].field = email
Porosi e dyfishtë
Një porosi për një paketë që po përpunohet tashmë refuzohet me
409dheduplicate_request. Mos e dërgoni përsëri menjëherë: kërkoni së pari rezervimin, dhe porositni përsëri vetëm nëse nuk është krijuar asnjë.Kërkesa 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" }'Përgjigjja 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 Kodi i statusit është 409
- PASS Kodi i gabimit është duplicate_request
- PASS $.errors[0].type = conflict
Shumë kërkesa
Mbi kufirin në minutë, thirrja refuzohet me
429dherate_limit_exceeded, dhe header-iRetry-Aftertregon sa sekonda të prisni. Pastaj riprovoni me backoff.Kërkesa 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" }'Përgjigjja 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 Kodi i statusit është 429
- PASS Kodi i gabimit është rate_limit_exceeded
- PASS Header-i Retry-After është i pranishëm
- PASS $.errors[0].details.retry_after = 12
Nga katalogu te udhëtari i lidhur, në pesë hapa
Një integrim është një rrugë e shkurtër: lexoni katalogun, krijoni porosinë, jepini udhëtarit eSIM-in, ndiqni përdorimin dhe rifusni kur mbarojnë të dhënat. Vetëm porosia dhe rifusja ndryshojnë diçka. Çdo thirrje tjetër vetëm lexon.
Lexoni katalogun për një destinacion
Listoni paketat e një vendi, me çmime tashmë në monedhën e agjencisë, dhe ruani package_id të paketës që zgjedh udhëtari. Dërgoni gjithmonë country: i gjithë katalogu është një përgjigje shumë e madhe, pa faqosje. Lexoni ID-të e paketave nga përgjigja në vend që t’i shkruani në kod, sepse katalogu ndryshon.
Kërkesa
curl 'https://api.fx-port.com/api/v1/esims/packages?country=france&type=local' \
-H "Authorization: Bearer fxp_test_YOUR_KEY"Përgjigjja 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
}
}Krijoni porosinë
Dërgoni package_id me adresën e email-it dhe numrin e telefonit të udhëtarit. Një porosi krijon saktësisht një eSIM dhe, në live, debiton bilancin e agjencisë suaj. Ruani booking_id dhe ICCID nga përgjigja, sepse çdo thirrje e mëpasshme ka nevojë për njërën prej tyre.
Kërkesa
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"
}'Përgjigjja 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
}| Fusha | Çfarë mban |
|---|---|
booking_id | Referenca e porosisë te FX-Port. Ruajeni për të dhënat e konfigurimit, kontrollin e pronësisë dhe evidencën tuaj. |
data.iccid | Identifikuesi i eSIM-it. Përdorimi, rifusjet dhe udhëzimet e instalimit kërkohen të gjitha me ICCID. |
data.sim.qrcode data.sim.qrcode_url | Vargu i aktivizimit që kodohet nga kodi QR, dhe një lidhje te imazhi i kodit QR. |
data.sim.direct_apple_installation_url data.sim.sharing | Një lidhje që nis instalimin në iPhone dhe një faqe ndarjeje ku udhëtari mund ta hapë eSIM-in me kodin e tij të qasjes. Thirrja e të dhënave të konfigurimit shton lidhjen për Android. |
PENDING-, dhe të dhënat merren nga thirrja e të dhënave të konfigurimit sapo furnizuesi t’i ketë.Jepini udhëtarit eSIM-in
Përgjigja përmban kodin QR dhe vargun e tij të aktivizimit, ndaj mund t’i shfaqni në ekranet tuaja. FX-Port i kërkon furnizuesit edhe t’i dërgojë me email kodin QR dhe një lidhje ndarjeje në adresën e udhëtarit, kështu që nuk keni pse ta ridërgoni. Thirrja e të dhënave të konfigurimit i kthen të njëjtat të dhëna më vonë, me hapat e instalimit.
Kërkesa
curl https://api.fx-port.com/api/v1/esims/bookings/FX-1793546602916/setup-instructions \
-H "Authorization: Bearer fxp_test_YOUR_KEY"Përgjigjja 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
}
}Ndiqni përdorimin
Lexoni të dhënat e mbetura dhe skadimin e një eSIM me ICCID-në e tij. Përgjigja ruhet në cache deri në 15 minuta, ndaj përdoreni për një ekran ose një kujtesë, jo si matës.
Kërkesa
curl https://api.fx-port.com/api/v1/esims/usage/8900000540463077957 \
-H "Authorization: Bearer fxp_test_YOUR_KEY"Përgjigjja 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"
}
}
}Rifusni kur mbarojnë të dhënat
Listoni paketat që mund t’i shtohen pikërisht këtij eSIM, pastaj krijoni rifusjen me njërën prej tyre. Nëse lista është bosh, eSIM-i nuk mund të rifuset tani dhe udhëtari ka nevojë për një të ri.
Kërkesa
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"
}'Përgjigjja 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
}Çmimet, komisioni dhe bilanci juaj
Çdo paketë ka fushat e saj të parasë, të llogaritura në server në monedhën e agjencisë suaj. Një çmim në trupin e kërkesës shpërfillet, ndaj një porosi krijohet gjithmonë me çmimin që llogarit serveri.
| Fusha | Çfarë mban |
|---|---|
base_price price | Çmimi i paketës para komisionit tuaj. Nuk është shuma që debitohet nga bilanci juaj. |
total_price retail_price | Çmimi që i faturohet udhëtarit, me komisionin tuaj të përfshirë. |
balance_debit_amount b2b_price | Ajo që del nga bilanci i agjencisë suaj kur e porositni paketën në live. Lexojeni, mos e llogaritni. |
agency_commission commission_rate | Norma juaj e komisionit, si tekst dhe si numër. Rezervimet e kthejnë komisionin tuaj si shumë. |
Në shembullin e katalogut, udhëtari paguan 468.84 DZD. Një porosi në live debiton bilancin tuaj me 418.60 DZD, dhe diferenca, 50.24 DZD, është komisioni juaj.
Norma i përket agjencisë suaj
Norma e komisionit kthehet me çdo paketë dhe nuk është e njëjtë për çdo agjenci. Një agjenci korporative me kontratë mund të ketë normë zero, dhe atëherë çmimi total është i barabartë me debitimin.
Lexoni fushat, mos i rindërtoni
Debitimi mund të jetë më i lartë se çmimi bazë, sepse në të hyjnë shuma specifike për agjencinë tuaj. Prandaj lexoni balance_debit_amount dhe mos e llogaritni kurrë nga base_price. Fjala price është çmimi bazë në katalog, por çmimi i shitjes me pakicë në porosi, paketat e rifusjes dhe të dhënat e konfigurimit: përdorni kudo base_price dhe total_price dhe paqartësia zhduket.
Çmim në monedhën e agjencisë suaj
Çdo shumë është konvertuar tashmë në monedhën e agjencisë suaj, cilado monedhë të përdorë furnizuesi. Përgjigja tregon edhe monedhën e furnizuesit dhe kursin e këmbimit, ndaj mund ta verifikoni vetë kursin dhe nuk keni nevojë të konvertoni më.
Pas shitjes: përdorimi, rifusjet dhe të dhënat e konfigurimit
Shitja nuk mbaron me porosinë. Këto thirrje e mbajnë udhëtarin të lidhur dhe funksionojnë vetëm për eSIM-et që agjencia juaj i ka porositur në të njëjtin mjedis me çelësin tuaj.
Leximi i përdorimit dhe sa i freskët është
Përdorimi kthen të dhënat e mbetura, kuotën, statusin dhe skadimin e një eSIM, ose të deri në 50 eSIM-eve në një thirrje. FX-Port e ruan përgjigjen e fundit deri në 15 minuta për të mbrojtur kufijtë e shpejtësisë së furnizuesit, ndaj një shifër mund të jetë kaq e vjetër. Dërgoni force=true për t’i kërkuar përsëri furnizuesit, për shembull menjëherë pas një rifusjeje. Mos e bëni në çdo kërkesë, sepse furnizuesi kufizon sa shpesh mund të lexohet përdorimi. Nëse furnizuesi nuk mund të përgjigjet, merrni shifrën e fundit të njohur, të shënuar si e vjetruar.
Rifusjet: pyesni së pari, pastaj krijoni
Një rifusje është dy thirrje. Së pari listoni paketat që mund t’i shtohen pikërisht këtij eSIM, pastaj krijoni rifusjen me një nga ID-të e paketave të kthyera. Mos ripërdorni kurrë ID-në e paketës së porosisë origjinale dhe mos ruani një paketë rifusjeje për më vonë: pyesni përsëri kur udhëtari dëshiron të rifusë. Një rifusje shton të dhëna te eSIM dhe nuk zëvendëson atë që ka mbetur, ndaj lexojeni rezultatin nga përdorimi me force=true.
Kur një rifusje nuk është e mundur
Furnizuesit zgjedhin cilët operatorë mobilë shërbejnë në një vend dhe, në raste të rralla, e ndryshojnë njërin. Atëherë eSIM-i mund të vazhdojë të funksionojë deri sa të skadojë, ndërsa paketës së tij nuk mund t’i bëhet më rifusje. Lista e paketave të rifusjes kthehet bosh. Nëse një furnizues e refuzon një rifusje, bilanci juaj nuk preket dhe tentativa ruhet si rezervim i dështuar. Përgjigja është një supplier_error që mund ta trajtoni.
Të dhënat e konfigurimit dhe hapat e instalimit
Thirrja e të dhënave të konfigurimit kthen kodin QR, të dhënat e aktivizimit, lidhjet e instalimit dhe hapat e instalimit të një porosie sa herë që ju duhen. Thirrja e udhëzimeve kthen hapat sipas sistemit operativ, në gjuhën që kërkoni. Hapat janë tekst i përgjithshëm nga furnizuesi, ndaj shfaqini pranë kodit QR të porosisë. Shfaqini të dyja vetëm udhëtarit që zotëron eSIM-in.
Rezervimet, historiku i rifusjeve dhe pronësia
Lista e rezervimeve kthen porositë eSIM të agjencisë suaj në mjedisin e çelësit tuaj, më të rejat të parat. Mund ta kërkoni sipas ID-së së rezervimit, emrit të udhëtarit, adresës së email-it, emrit të paketës ose ICCID-së. Rifusjet nuk janë në atë listë: lexojini me historikun e rifusjeve të një eSIM. Para se të ndërtoni një lidhje ose një ekran rreth një ID-je rezervimi, kontrolli i pronësisë ju tregon nëse është e juaja. Një rezervim i një agjencie tjetër dhe një që nuk ekziston marrin të njëjtën përgjigje.
Çdo endpoint eSIM, me OpenAPI, Postman dhe shembuj kodi
API eSIM ka 12 endpoint-e nën një URL bazë. Çdo rresht hap faqen e referencës së asaj thirrjeje, me fushat e kërkesës, përgjigjet, gabimet dhe shembujt në 9 gjuhë.
| Endpoint | Çfarë bën | Çelësi |
|---|---|---|
GET /api/v1/esims/packages | Liston paketat e një vendi ose rajoni, me çmime tashmë në monedhën e agjencisë suaj. Dërgoni gjithmonë një vend: i gjithë katalogu është shumë i madh dhe nuk ka faqosje. | Lexim |
GET /api/v1/esims/compatible-devices | Pajisjet që dihet se mbështesin eSIM, për një kontroll para se udhëtari të blejë. | Lexim |
POST /api/v1/esims/orders | Krijon një eSIM nga një paketë për një udhëtar dhe e provizionon te furnizuesi. Në live debiton bilancin e agjencisë suaj. | Lexim + shkrim |
GET /api/v1/esims/topup-packages/{iccid} | Paketat që mund t’i shtohen sot pikërisht një eSIM. Një listë bosh do të thotë se nuk mund të rifuset tani. | Lexim |
POST /api/v1/esims/topups | Shton një paketë rifusjeje te një eSIM ekzistues. Në live, bilanci debitohet vetëm pasi furnizuesi e pranon. | Lexim + shkrim |
GET /api/v1/esims/usage/{iccid} | Të dhënat e mbetura, kuota, statusi dhe skadimi i një eSIM. Përgjigja mund të jetë deri në 15 minuta e vjetër. | Lexim |
GET /api/v1/esims/usage/bulk | Përdorimi i deri në 50 eSIM-eve në një thirrje, një hyrje për ICCID, secila me statusin e vet. | Lexim |
GET /api/v1/esims/bookings | Porositë eSIM të agjencisë suaj, më të rejat të parat, me kërkim dhe faqosje. Rifusjet nuk janë në këtë listë. | Lexim |
GET /api/v1/esims/bookings/{iccid}/topup-history | Rifusjet e një eSIM, më të rejat të parat. Lista është bosh kur eSIM-i nuk ka asnjë. | Lexim |
GET /api/v1/esims/bookings/{booking_id}/verify | Kontrollon që një referencë rezervimi i përket agjencisë suaj, para se të ndërtoni një lidhje ose një ekran rreth saj. | Lexim |
GET /api/v1/esims/bookings/{booking_id}/setup-instructions | Kodi QR, të dhënat e aktivizimit, lidhjet e instalimit dhe hapat e instalimit të një porosie, si JSON. | Lexim |
GET /api/v1/esims/instructions/{iccid} | Udhëzime instalimi hap pas hapi për një ICCID, sipas sistemit operativ, në gjuhën që kërkoni. | Lexim |
OpenAPI 3.1
Një skedar përshkruan çdo endpoint dhe çdo fushë. Gjeneroni prej tij një klient, importojeni në një mjet API ose jepjani një asistenti kodimi.
Koleksioni Postman
Koleksioni eSIM mbulon të gjitha 12 endpoint-et në dosje që ndjekin fazat e një shitjeje. Nuk përmban çelësa, ndaj shtoni tuajt.
Shembuj kodi në 9 gjuhë
Çdo faqe referencë e printon kërkesën në cURL, Node.js, Python, PHP, Go, Java, C#, Swift dhe Kotlin, të gjeneruar nga përshkrimi OpenAPI. Çdo kërkesë eSIM është e disponueshme në të gjitha.
Dokumentacion për asistentët e IA-së
llms.txt dhe llms-full.txt ua japin asistentëve të inteligjencës artificiale dokumentacionin si tekst të thjeshtë, dhe çdo faqe e dokumentacionit mund të lexohet si Markdown duke i shtuar .md adresës së saj.
Ndërtuar për prodhim: çelësa, gabime, riprovime dhe cache
Një integrim eSIM gjykohet në prodhim për autentikimin, dështimet, riprovimet, cache-n dhe kufijtë e shpejtësisë. Ja çfarë duhet të dini për secilin.
Një URL bazë, dy lloje çelësash
Çdo kërkesë mbart një çelës si token bearer në header-in Authorization. Prefiksi tregon ku funksionon çelësi: fxp_test_ për sandbox dhe fxp_live_ për live. Të dy përdorin të njëjtën URL bazë, dhe çdo përgjigje JSON e thotë mjedisin nga vjen te environment. Çelësat i përkasin serverit tuaj, kurrë shfletuesit ose një aplikacioni. FX-Port ruan vetëm një hash të çdo çelësi, ndaj një çelës i humbur nuk mund të shfaqet më. Një ndryshim i çelësit mund të marrë disa minuta të zbatohet.
Cili çelës bën cilën thirrje
Një çelës Lexim mund të listojë paketa, të kontrollojë pajisje, të lexojë përdorimin dhe rezervimet. Krijimi i një porosie ose rifusjeje kërkon një çelës Lexim + shkrim, dhe një çelës Lexim që e provon merr read_write_permission_required. Çdo çelës mund të kyçet te një listë adresash IP, dhe një thirrje nga një adresë tjetër merr ip_not_allowed. Përdorni një çelës Lexim kudo ku kodi vetëm shfaq rezultate.
Një format gabimi për çdo dështim
Një thirrje e dështuar kthen një varg errors. Hyrja e parë ka një code të qëndrueshëm, një type që tregon si të reagohet dhe field me fushën me gabim. Testoni kodin, kurrë mesazhin. Lista e gabimeve e përbashkët për fluturimet, hotelet, eSIM-et dhe llogarinë përmban 180 kode. Kur furnizuesi refuzon një porosi ose një rifusje, përgjigja është një supplier_error me statusin HTTP të vetë furnizuesit. Nuk debitohet asgjë dhe ruhet një rezervim i dështuar. Menjëherë pas një rinisjeje, katalogu dhe lista e pajisjeve mund të përgjigjen me 202 dhe success të vendosur në false: prisni disa sekonda dhe pyesni përsëri.
Riprovimi pa porositur dy herë
FX-Port nuk ka çelës idempotence, ndaj nuk ka header Idempotency-Key për të dërguar. Leximet përsëriten pa rrezik; krijimi i një porosie ose rifusjeje jo. FX-Port e refuzon një dublikatë të dukshme me 409 dhe duplicate_request: një porosi për një paketë që po përpunohet ende. Në live refuzon edhe të njëjtën paketë të porositur përsëri brenda 60 sekondave nga porosia e fundit e konfirmuar e agjencisë suaj, kushdo qoftë udhëtari. Porositë zakonisht përgjigjen brenda pak sekondash, por një furnizues i ngadaltë mund të zgjasë shumë më tepër. Nëse një thirrje skadon ose lidhja ndërpritet, mos e dërgoni porosinë përsëri menjëherë, sepse eSIM-i mund të ekzistojë. Kërkojeni me parametrin search të listës së rezervimeve, me adresën e email-it të udhëtarit, dhe porositni përsëri vetëm nëse nuk është krijuar asgjë.
Pa webhook-e: pyesni kur ju duhet
FX-Port nuk thërret asnjë URL tuajën, as në sandbox, as në live. Një porosi përgjigjet me eSIM-in, ose me një vendmbajtës PENDING- derisa furnizuesi ta ketë kthyer. Çdo gjë tjetër e kërkoni kur ju duhet: të dhënat e konfigurimit, përdorimin ose listën e rezervimeve.
Cache dhe shpejtësia
Përdorimi ruhet deri në 15 minuta dhe lista e paketave të rifusjes për disa minuta, ndërsa force=true e anashkalon cache-n. Katalogu pa filtër është një përgjigje shumë e madhe pa faqosje, ndaj dërgoni country dhe pranoni kompresimin me Accept-Encoding: gzip. Titujt e paketave kthehen në gjuhën e parametrit locale; kërkesa e parë në një gjuhë tjetër nga anglishtja është më e ngadaltë, sepse teksti merret atëherë dhe ruhet në cache pas kësaj.
Kufijtë e shpejtësisë
Kufijtë numërohen për çelës dhe për minutë në dy grupe, dhe çdo përgjigje mbart ratelimit-limit dhe ratelimit-remaining, që të ngadalësoni para se t’ju refuzojnë. Pas një 429, prisni sekondat e Retry-After dhe riprovoni me backoff eksponencial dhe jitter. Tepër shumë porosi ose rimbushje të një çelësi apo agjencie që ekzekutohen njëkohësisht mund të marrin përgjigjen concurrency_limit_exceeded.
| Lloji i thirrjes | Në minutë |
|---|---|
| Krijimi i porosive dhe rifusjeve | 1,200 |
| Çdo endpoint tjetër eSIM | 6,000 |
Për momentin tavani i porosive dhe rimbushjeve që ekzekutohen njëkohësisht është në mënyrë vëzhgimi: numërohet, por nuk zbatohet, ndaj asgjë nuk refuzohet për shkak të tij, dhe changelog-u njofton ditën kur do të zbatohet. Lexojini këto numra si politikën e tanishme dhe jo si premtim. Çelësat sandbox kanë të njëjtët numërues në minutë si çelësat live, ndaj planifikoni testet e ngarkesës në vend që t’i ekzekutoni në cikël.
Emrat dhe versionet
Fushat e kërkesës janë snake_case, si first_name dhe agent_id. Emërtimet e mëparshme funksionojnë ende: user_id lexohet si agent_id dhe shton një hyrje warnings, ndërsa customer_email pranohet si email pa të. Shumë përgjigje mbajnë një çelës të vjetër pranë binjakut të tij snake_case me të njëjtën vlerë, si order_id pranë code, dhe ?naming=snake kthen vetëm çelësa snake_case. Versioni qëndron në shteg, /api/v1: një ndryshim që prish përputhshmërinë do të merrte një prefiks të ri, ndërsa fushat dhe emërtimet e reja janë shtesa.
Filloni në sandbox-in falas, pastaj kaloni në live
Çdo gjë në këtë faqe funksionon sot në sandbox. Një çelës sandbox është vetë-shërbyes dhe falas, dhe nuk e prek kurrë bilancin tuaj real.
Krijoni një llogari
Regjistrohuni për një llogari FX-Port. Çelësat sandbox janë falas dhe rezervimet sandbox nuk kanë asnjë tarifim real.
Krijoni një çelës sandbox
Në faqen API të panelit tuaj, krijoni një çelës që fillon me
fxp_test_. Një çelës Lexim mund të kërkojë dhe të lexojë; një çelës Lexim + shkrim mund të krijojë edhe rezervime testimi.Dërgoni kërkesën tuaj të parë
Ka vetëm një URL bazë, ndërsa çelësi vendoset në header-in
Authorizationsi token Bearer. Udhëzuesi i shpejtë përshkruan hap pas hapi thirrjen e parë.Kaloni në Live kur të jeni gati
Zëvendësojeni me një çelës
fxp_live_. Live funksionon pasi agjencia juaj miratohet; deri atëherë API përgjigjet me403 agency_not_active. Rezervimet reale paguhen nga një bilanc i financuar.
Një kërkesë e parë katalogu në cURL. Dokumentacioni e printon të njëjtën kërkesë në çdo gjuhë të mbështetur.
Kërkesa
curl 'https://api.fx-port.com/api/v1/esims/packages?country=france&type=local' \
-H "Authorization: Bearer fxp_test_YOUR_KEY"Nisja e shpejtë: thirrja e parë sandbox
Çfarë bën sandbox-i
Një porosi në sandbox krijon një eSIM testimi të vërtetë te furnizuesi, me një kod aktivizimi fiktiv, ndaj nuk mund të instalohet në telefon. Nuk debitohet asgjë dhe përgjigjet e thonë këtë: balanceDebited, transactionCreated dhe payoutCreated janë të gjitha false. Një rifusje përgjigjet me bilanc zero. Përdorimi është statik: një eSIM i ri tregon kuotën e plotë dhe statusin ACTIVE. Rezervimet sandbox shihen vetëm nga çelësat sandbox.
Çfarë mund të testohet vetëm në live
Kontrolli i bilancit, kontrolli i dublikatave dhe kyçja e bilancit ekzekutohen vetëm në live. Ndaj përgjigjet 402 me insufficient_balance, 409 për të njëjtën paketë të porositur përsëri brenda 60 sekondave dhe 503 me balance_lock_timeout nuk shfaqen kurrë në sandbox. Shkruani trajtimin e tyre sipas listës së kodeve të gabimit.
Kalimi në live
Çelësat live lidhen me miratimin e agjencisë: derisa agjencia juaj të miratohet, një çelës live përgjigjet agency_not_active dhe çelësi juaj sandbox vazhdon të funksionojë. Porositë live paguhen nga një bilanc agjencie i financuar. Kalimi në live ndryshon çelësin, jo kodin, sepse sandbox dhe live ndajnë një URL bazë.
Kush ndërton mbi API-n eSIM
Çdo audiencë mbështetet te një pjesë tjetër e të njëjtave thirrje.
Agjenci që shesin udhëtime
Agjencitë e shesin eSIM-in pranë fluturimit dhe hotelit. Porositin me adresën e email-it të vetë udhëtarit, që furnizuesi të dërgojë kodin QR dhe një lidhje ndarjeje, dhe lexojnë përdorimin kur një udhëtar pyet. Norma e komisionit kthehet me çdo paketë, dhe agent_id regjistron cili përdorues i agjencisë suaj ka bërë një porosi.
OTA dhe tregje
Tregjet e ndërtojnë së pari faqen e shfletimit: një vend në herë, paketa lokale ose rajonale, rrjetet dhe kuota e të dhënave e secilës paketë, dhe një kontroll pajisjeje para se udhëtari të blejë. Një ekran që liston eSIM-et e një udhëtari mund të lexojë përdorimin e deri në 50 prej tyre në një thirrje.
Ekipe të teknologjisë së udhëtimit dhe korporative
Ekipet e teknologjisë së udhëtimit dhe departamentet e udhëtimeve korporative ndërtojnë mjetet e tyre të rezervimit. Çdo gjë që u duhet për të filluar është publike: skedari OpenAPI, koleksioni Postman dhe dokumentacioni në tekst të thjeshtë që e lexon një asistent kodimi me IA, ndaj prototipi i parë nis nga kontrata e vërtetë.
API eSIM: pyetje të shpeshta
Çfarë është API eSIM i FX-Port dhe për kë është?
Është një API REST që i lejon një agjencie udhëtimi, një OTA-je ose një rishitësi të shesë eSIM të dhënash për udhëtim nga një integrim i vetëm. Listoni paketat e një destinacioni me çmime në monedhën e agjencisë suaj dhe porositni një për udhëtarin. I jepni udhëtarit kodin QR, ndiqni përdorimin dhe rifusni. Gjithçka është JSON mbi HTTPS, dhe një skedar OpenAPI përshkruan çdo endpoint.
A ka sandbox falas dhe si ta marr një çelës?
Po. Krijoni një llogari FX-Port, hapni faqen API të panelit tuaj dhe krijoni një çelës sandbox; mund ta bëni vetë, pa kosto. Një porosi në sandbox krijon një eSIM testimi me kod aktivizimi fiktiv, ndaj nuk mund të instalohet në telefon. Nuk debitohet asgjë nga bilanci juaj. Sandbox dhe live ndajnë një URL bazë, kështu që kodi që testoni është kodi që publikoni.
Çfarë duhet për të kaluar në live?
Agjencia juaj duhet të miratohet para se një çelës live të funksionojë. Deri atëherë një çelës live refuzohet dhe çelësi juaj sandbox vazhdon të funksionojë. Porositë live paguhen nga një bilanc agjencie i financuar, të cilin sandbox-i nuk e prek kurrë, dhe çdo çelës mund të kyçet te një listë adresash IP. Kalimi do të thotë të ndryshoni vetëm çelësin; çdo përgjigje e thotë mjedisin nga vjen.
Cilat vende dhe paketa mund t’i shes?
Paketat ofrohen për 190+ vende, dhe paketat rajonale shfaqen nën rajonin e tyre. Paketat ndryshojnë në kuotën e të dhënave, vlefshmërinë, rrjetet dhe nëse mund të rifusen. Lexoni këto fusha dhe ID-në e paketës nga përgjigja e katalogut në vend që t’i shkruani në kod. Kërkoni një vend në herë, sepse i gjithë katalogu është një përgjigje shumë e madhe. Një listë e veçantë pajisjesh ju lejon të kontrolloni telefonin e udhëtarit para shitjes.
Si e merr udhëtari eSIM-in?
Përgjigja e porosisë mbart kodin QR, vargun e tij të aktivizimit, një lidhje instalimi për iPhone dhe një faqe ndarjeje. Mund t’i shfaqni në ekranet tuaja. FX-Port i kërkon furnizuesit edhe t’i dërgojë me email kodin QR dhe një lidhje ndarjeje në adresën e udhëtarit sapo krijohet eSIM-i. Nëse furnizuesi nuk e ka kthyer ende eSIM-in, porosia ekziston prapë dhe të dhënat merren më vonë nga thirrja e të dhënave të konfigurimit.
Si lidhen çmimet, komisioni dhe bilanci im?
Çdo paketë mbart këto fusha parash në monedhën e agjencisë suaj: çmimin bazë para komisionit tuaj, çmimin total që i faturohet udhëtarit, shumën e debituar nga bilanci juaj dhe normën tuaj të komisionit. Komisioni juaj është çmimi total minus debitimi. Lexoni këto fusha në vend që t’i rindërtoni, sepse debitimi është specifik për agjencinë tuaj. Në sandbox nuk debitohet asgjë; në live debitimi del nga bilanci i agjencisë.
A mund ta rifus një eSIM dhe si e shoh çfarë ka mbetur?
Po, me dy thirrje: listoni paketat që mund t’i shtohen pikërisht këtij eSIM, pastaj krijoni rifusjen me njërën prej tyre. Një rifusje nuk është gjithmonë e mundur, sepse një furnizues mund ta ndryshojë operatorin e një vendi. Atëherë një listë bosh do të thotë se udhëtari ka nevojë për një eSIM të ri. Përdorimi ruhet në cache deri në 15 minuta, ndaj trajtojeni si shifër të fundit, dhe një thirrje lexon deri në 50 eSIM.
Si raportohen dështimet dhe a ka webhook-e?
Një dështim kthehet në një format të vetëm me një kod gabimi të qëndrueshëm, dhe ky kod është ajo që duhet të testojë programi juaj, jo teksti i mesazhit. Leximet përsëriten pa rrezik me backoff. Krijimi i një porosie ose rifusjeje është ndryshe: nuk ka çelës idempotence, ndaj pas një skadimi kërkoni rezervimin para se të provoni përsëri. FX-Port e refuzon një dublikatë të dukshme, si e njëjta paketë e porositur dy herë brenda 60 sekondave në live. Nuk ka webhook-e.
A mund ta anuloj ose rimbursoj një porosi eSIM përmes API-t?
Jo. API nuk ka endpoint për të anuluar ose rimbursuar një porosi eSIM. Çdo porosi krijon saktësisht një eSIM, ndaj kontrolloni paketën dhe të dhënat e udhëtarit para se ta dërgoni. Nëse furnizuesi e refuzon një porosi, nuk debitohet asgjë dhe ruhet një rezervim i dështuar. Për një problem me një porosi të caktuar, shkruani ekipit të zhvilluesve dhe citoni ID-në e rezervimit të saj.
Çfarë më duhet për të filluar dhe cilat mjete ndihmojnë?
Ju duhet një çelës sandbox dhe një klient HTTP. Dokumentacioni shton një skedar OpenAPI 3.1, një koleksion Postman, shembuj kodi në 9 gjuhë dhe eksporte në tekst të thjeshtë për asistentët e IA-së. Mbajini çelësat në serverin tuaj, kurrë në shfletues ose në aplikacion. Pjesa që kërkon më shumë kohë është faqja juaj e pagesës, dërgimi i kodit QR te udhëtari dhe trajtimi i gabimeve.
API të tjera të FX-Port
Një eSIM zakonisht shkon me një udhëtim. Fluturimet dhe hotelet përdorin të njëjtët çelësa, të njëjtin trup gabimi dhe të njëjtat konventa si eSIM-et, dhe rezervimet e tyre janë në të njëjtin historik llogarie.
Kërkoni, konfirmoni çmimin dhe rezervoni fluturime, paguani porositë e mbajtura, anuloni dhe lexoni biletat.
Gjeni hotele, kontrolloni tarifat, bëni para-rezervim dhe rezervim, lexoni vauçerët dhe anuloni.
- API i TransfertaveParaprake
Kuotoni, rezervoni, ndiqni dhe anuloni transfertat e aeroportit.
Nuk doni të shkruani kod? Agjencitë mund t’i shesin eSIM-et edhe nga paneli i FX-Port. Shitni eSIM nga paneli
Ekzekutoni porosinë tuaj të parë eSIM në sandbox
Krijoni një llogari, bëni një çelës sandbox, listoni paketa, krijoni një porosi dhe lexoni përdorimin që sot. Çelësat live vijnë pasi agjencia juaj miratohet.
Pyesni një asistent IA për këtë API
Hapni këtë faqe në një asistent dhe kërkoni një plan integrimi hap pas hapi.
