여행사와 OTA, 리셀러를 위한 eSIM API 서비스

한 국가의 패키지를 조회하는 것으로 시작해 여행객을 위해 하나를 주문하고, 주문의 설치 데이터를 조회합니다. 샌드박스는 가짜 활성화 코드가 든 테스트 eSIM을 만들며 차감되는 금액은 없습니다. 콘솔에는 카탈로그 응답을 줄여 놓은 사본이 표시됩니다.

1. 패키지 조회

   카탈로그 호출은 country와 type을 받아 조건에 맞는 패키지를 여행사 통화 기준 가격으로 돌려줍니다. 여행객이 고른 패키지의 package_id를 보관하세요.

   curl 'https://api.fx-port.com/api/v1/esims/packages?country=france&type=local' \
     -H "Authorization: Bearer fxp_test_YOUR_KEY"

   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
     }
   }

   표시용으로 줄인 예시

   • PASS 상태 코드가 200입니다
   • PASS $.success가 true와 같음
   • PASS $.data[0].package_id 존재함
   • PASS $.data[0].balance_debit_amount 존재함

   문서의 GET /esims/packages 레퍼런스

2. eSIM 주문

   주문 생성에는 package_id와 여행객의 이메일 주소, 전화번호가 필요합니다. 응답의 booking_id와 data.iccid를 보관하세요. 샌드박스에서는 balanceDebited, transactionCreated, payoutCreated가 모두 false입니다.

   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"
   }'

   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
   }

   표시용으로 줄인 예시

   • PASS 상태 코드가 200입니다
   • PASS $.environment가 sandbox와 같음
   • PASS $.balance_debited가 false와 같음
   • PASS $.data.iccid 존재함

   문서의 POST /esims/orders 레퍼런스

3. 설치 데이터 조회

   설치 데이터 호출은 booking_id를 받아 주문의 QR 코드, 활성화 데이터, 설치 링크, 설치 단계를 돌려줍니다. eSIM을 소유한 여행객에게만 보여 주세요.

   curl https://api.fx-port.com/api/v1/esims/bookings/FX-1793546602916/setup-instructions \
     -H "Authorization: Bearer fxp_test_YOUR_KEY"

   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"
     }
   }

   표시용으로 줄인 예시

   • PASS 상태 코드가 200입니다
   • PASS $.data.package_id가 france-in-7days-1gb와 같음
   • PASS $.data.sims[0].iccid 존재함

   문서의 GET /esims/bookings/{booking_id}/setup-instructions 레퍼런스

여행객이 eSIM을 갖게 되면 남은 데이터를 조회하고, 바로 그 eSIM에 추가할 수 있는 패키지를 확인한 뒤 충전을 생성합니다. 사용량은 캐시되므로 수치가 몇 분 지난 값일 수 있습니다. 충전 내역은 사이드바와 기록에서 볼 수 있습니다.

1. 사용량 조회

   사용량 호출은 주문의 ICCID를 받아 메가바이트 단위의 remaining과 total, status, 만료일을 돌려줍니다. 응답은 캐시에서 오며, force=true를 보내면 공급사에 다시 물어봅니다.

   curl https://api.fx-port.com/api/v1/esims/usage/8900000540463077957 \
     -H "Authorization: Bearer fxp_test_YOUR_KEY"

   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 상태 코드가 200입니다
   • PASS $.data.data.status가 ACTIVE와 같음
   • PASS $.data.data.remaining 존재함

   문서의 GET /esims/usage/{iccid} 레퍼런스

2. 충전 패키지 조회

   이 호출은 오늘 바로 이 eSIM에 추가할 수 있는 패키지를 보여 줍니다. 목록이 비어 있으면 지금은 충전할 수 없는 eSIM입니다. 충전의 package_id는 최초 주문이 아니라 이 목록에서 가져오세요.

   curl https://api.fx-port.com/api/v1/esims/topup-packages/8900000540463077957 \
     -H "Authorization: Bearer fxp_test_YOUR_KEY"

   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
         }
       ]
     }
   }

   표시용으로 줄인 예시

   • PASS 상태 코드가 200입니다
   • PASS $.data.data의 항목 수: 2개
   • PASS $.data.data[0].type가 topup와 같음

   문서의 GET /esims/topup-packages/{iccid} 레퍼런스

3. 충전 생성

   충전 생성에는 앞의 목록에서 가져온 package_id와 ICCID가 필요합니다. 라이브에서는 공급사가 수락한 뒤에만 잔액에서 차감됩니다. 샌드박스에서는 응답의 balance가 0이며 차감되는 금액은 없습니다.

   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"
   }'

   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 상태 코드가 200입니다
   • PASS $.environment가 sandbox와 같음
   • PASS $.balance_debited가 false와 같음
   • PASS $.data.balance.current가 0와 같음

   문서의 POST /esims/topups 레퍼런스

4. 충전 내역 조회

   충전 내역은 eSIM 하나의 충전을 최신순으로 보여 줍니다. 충전은 예약 목록에 없으므로 여기서 찾으면 됩니다.

   curl https://api.fx-port.com/api/v1/esims/bookings/8900000540463077957/topup-history \
     -H "Authorization: Bearer fxp_test_YOUR_KEY"

   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 상태 코드가 200입니다
   • PASS $.data[0].type가 topup와 같음

   문서의 GET /esims/bookings/{iccid}/topup-history 레퍼런스

판매 전에는 여행객의 휴대폰이 eSIM을 지원하는지 확인하세요. 판매 후에는 예약을 조회하고, 예약 참조 번호가 여행사의 것인지 확인하세요. 일괄 사용량은 사이드바에 있습니다.

1. 기기 목록 확인

   호환 기기 호출은 eSIM을 지원하는 것으로 알려진 기기를 brand, model, os와 함께 돌려줍니다. 판매하기 전에 여행객의 휴대폰을 찾아보세요.

   curl https://api.fx-port.com/api/v1/esims/compatible-devices \
     -H "Authorization: Bearer fxp_test_YOUR_KEY"

   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 상태 코드가 200입니다
   • PASS $.success가 true와 같음
   • PASS $.data[0].model 존재함

   문서의 GET /esims/compatible-devices 레퍼런스

2. 예약 목록 조회

   예약 목록은 여행사가 주문한 eSIM을 최신순으로 돌려줍니다. 이 요청은 limit으로 예약 하나만 요청하며, pagination은 조건에 맞는 주문의 수와 다음 페이지가 있는지를 알려 줍니다.

   curl 'https://api.fx-port.com/api/v1/esims/bookings?limit=1' \
     -H "Authorization: Bearer fxp_test_YOUR_KEY"

   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 상태 코드가 200입니다
   • PASS $.data의 항목 수: 1개
   • PASS $.pagination.has_more가 true와 같음

   문서의 GET /esims/bookings 레퍼런스

3. 소유 확인

   소유 확인은 예약이 여행사의 것이면 is_owner를 true로 응답합니다. 다른 여행사의 예약과 존재하지 않는 예약은 같은 응답을 받으므로, 이 호출로 참조 번호를 알아낼 수는 없습니다.

   curl https://api.fx-port.com/api/v1/esims/bookings/FX-1793546602916/verify \
     -H "Authorization: Bearer fxp_test_YOUR_KEY"

   200 OK
   
   {
     "environment": "sandbox",
     "isOwner": true,
     "is_owner": true,
     "userAgencyId": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
     "bookingAgencyId": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d"
   }

   • PASS 상태 코드가 200입니다
   • PASS $.is_owner가 true와 같음

   문서의 GET /esims/bookings/{booking_id}/verify 레퍼런스

4. 사용량 일괄 조회

   한 번의 호출로 iccids에 나열한 여러 eSIM의 사용량을 읽고, ICCID별로 각자의 status가 담긴 항목 하나씩을 돌려줍니다. iccids는 항상 보내세요.

   curl 'https://api.fx-port.com/api/v1/esims/usage/bulk?iccids=8900000540463077957' \
     -H "Authorization: Bearer fxp_test_YOUR_KEY"

   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 상태 코드가 200입니다
   • PASS $.data[0].status가 success와 같음

   문서의 GET /esims/usage/bulk 레퍼런스

모든 실패는 하나의 본문 형식을 공유하며, errors의 첫 항목에는 변하지 않는 code가 있습니다. 이 주문 호출들은 서로 다른 이유로, 서로 다른 대응이 필요하도록 일부러 실패시킨 것입니다.

1. 주문에 읽기 키 사용

   주문 호출에 읽기 키를 쓰면 본문을 읽기도 전에 403과 read_write_permission_required로 거부됩니다. 읽기+쓰기 키로 바꾸세요.

   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"
   }'

   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 상태 코드가 403입니다
   • PASS 오류 코드가 read_write_permission_required입니다
   • PASS $.errors[0].type가 permission_error와 같음

   문서의 POST /esims/orders 레퍼런스

2. 잘못된 이메일 주소

   이메일 주소가 아닌 값은 400과 invalid_email로 거부되며, field에는 email이 표시됩니다. 같은 요청은 같은 방식으로 실패하므로, 주문을 다시 보내기 전에 값을 고치세요.

   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"
   }'

   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 상태 코드가 400입니다
   • PASS 오류 코드가 invalid_email입니다
   • PASS $.errors[0].field가 email와 같음

   문서의 POST /esims/orders 레퍼런스

3. 중복 주문

   이미 처리 중인 패키지에 대한 주문은 409와 duplicate_request로 거부됩니다. 곧바로 다시 보내지 말고 먼저 예약을 조회해 보고, 생성된 것이 없을 때만 다시 주문하세요.

   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"
   }'

   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 상태 코드가 409입니다
   • PASS 오류 코드가 duplicate_request입니다
   • PASS $.errors[0].type가 conflict와 같음

   문서의 POST /esims/orders 레퍼런스

4. 요청 과다

   분당 한도를 넘으면 호출이 429와 rate_limit_exceeded로 거부되며, Retry-After 헤더가 기다려야 할 초를 알려 줍니다. 그다음 백오프를 적용해 재시도하세요.

   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"
   }'

   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 상태 코드가 429입니다
   • PASS 오류 코드가 rate_limit_exceeded입니다
   • PASS 헤더 Retry-After 있음
   • PASS $.errors[0].details.retry_after가 12와 같음

   문서의 POST /esims/orders 레퍼런스