واجهة API لبطاقات eSIM لوكالات السفر وشركات OTA والموزعين

ابدأ بباقات دولة واحدة، ثم اطلب إحداها لمسافر، ثم اقرأ بيانات الإعداد الخاصة بالطلب. ينشئ Sandbox بطاقة 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 من الإجابة. في Sandbox تكون 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 تحديدًا. القائمة الفارغة تعني أنه لا يمكن إعادة شحنها الآن. خذ 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⁩ يحتوي عنصرين
   • PASS ⁦$.data.data[0].type⁩ يساوي ⁦topup⁩

   مرجع ⁦GET /esims/topup-packages/{iccid}⁩ في التوثيق

3. أنشئ إعادة الشحن

   يأخذ إنشاء إعادة الشحن package_id من تلك القائمة مع رقم ICCID. وفي Live لا يُخصم رصيدك إلا بعد أن يقبلها المورّد. أما في Sandbox فقيمة balance في الإجابة صفر ولا يُخصم شيء.

   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⁩ يحتوي عنصرًا واحدًا
   • 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. اقرأ الاستهلاك دفعة واحدة

   يقرأ استدعاء واحد استهلاك عدة بطاقات eSIM مدرجة في iccids ويعيد عنصرًا لكل 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 عدد الثواني الواجب انتظارها. ثم أعد المحاولة مع التراجع (backoff).

   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⁩ في التوثيق