خُذ البيانات واحفظ علامتك التجارية.
كتالوج باقات eSIM للسفر بالكامل خلف واجهة REST واحدة. اشترِ بسعر الجملة وبِع بالسعر الذي تحدده، ودَع لنا التسليم ومتابعة الاستهلاك ومسار الاسترداد. لا يستغرق الربط أكثر من بعد ظهيرة واحدة.
بيئة Sandbox مجانية — نفّذ طلبًا كاملًا من البداية إلى النهاية قبل الانتقال إلى التشغيل الفعلي.
curl -X POST https://api.cotaesim.com/partner/v1/orders \
-H "Authorization: Bearer $COTA_TOKEN" \
-H "Idempotency-Key: PO-2026-00931" \
-H "Content-Type: application/json" \
-d '{ "planSlug": "fr-7d-1gb", "quantity": 2 }'
{
"orderId": "por_7f3a…",
"status": "completed",
"unitPriceCents": 499,
"requestedQuantity": 2,
"fulfilledCount": 2,
"esims": [
{ "esimId": "esim_1a2b…",
"lpa": "LPA:1$smdp.example.com$ABC-123-XYZ",
"universalLink": "https://esimsetup.apple.com/…",
"qrUrl": "/partner/v1/esims/esim_1a2b…/qr.png" }
]
}- Sandboxنفس نقاط النهاية، ورصيد مستقل، وبطاقات eSIM للاختبار
- نداء واحدالطلب والتسليم ورمز QR في استجابة واحدة
- Webhookأحداث موقَّعة، وثماني مراحل لإعادة المحاولة
- الهاتفتابع طلباتك من هاتفك
أربع خطوات حتى أول عملية بيع
- 01
احصل على بيانات الدخول
نفتح لك حساب شريك. بادِل
clientIdوclientSecretبرمز وصول صالح 24 ساعة؛ الرموز مُعتِمة، لذا يسري الإلغاء فورًا عند الحاجة. - 02
اختبر كل شيء في Sandbox
تقدّم بيئة Sandbox نفس نقاط النهاية ونفس عمليات التحقق ونفس رموز الأخطاء الموجودة في التشغيل الفعلي. الفرق الوحيد أنها تخصم من رصيد مستقل وتعيد بطاقة eSIM للاختبار، فتُكمل الربط دون أن تدفع شيئًا.
- 03
اطلب التشغيل الفعلي
اطلب الوصول إلى التشغيل الفعلي بزر واحد في البوابة. نُفعّل الحساب، وتعمل بيانات دخولك الفعلية عبر نفس مسار الكود — كل ما تغيّره هو متغيّر بيئة واحد.
- 04
هيّئ حسابك وابدأ البيع
هناك طريقتان للعمل: رصيد مدفوع مقدمًا، أو حد ائتماني متفق عليه. في الحالتين يُخصم كل طلب لحظة وصوله، ويُسجَّل كل حركة في دفتر لا يُضاف إليه إلا إضافة — فترى مصروفاتك دون انتظار كشف نهاية الشهر.
ما يقدّمه القطاع عادةً وما نفعله نحن بدلًا منه
معظم البنود التالية لا تظهر في الأسبوع الأول، بل توجع في الشهر السادس. عالجناها من البداية.
بيئة الاختبار
المعتاد في القطاعبيئة Sandbox إما غير موجودة أو تتصرف بخلاف بيئة التشغيل، فتضطر إلى تجربة الربط بأموال حقيقية.
COTA Partner APIتعمل Sandbox على نفس مسار الكود المستخدم في التشغيل الفعلي: نفس التحققات ونفس رموز الأخطاء، مع رصيد مستقل. والبيئة جزء من مفتاح عدم التكرار، فلا يمكن لطلب في Sandbox أن ينعكس على طلب فعلي أبدًا.
التسليم الجزئي
المعتاد في القطاعطلبت عشرًا فوصلت سبع. تبقى قيمة الثلاث الأخرى معلّقة في مكان ما، فتفتح تذكرة دعم.
COTA Partner APIتُعاد قيمة كل وحدة لم تُسلَّم إلى رصيدك داخل المعاملة نفسها. وتُظهر الاستجابة
requestedQuantityوfulfilledCountكلًّا على حدة، فلا تحتاج إلى التخمين.الطلبات المُعادة
المعتاد في القطاعإعادة المحاولة بعد انتهاء المهلة تُنشئ طلبًا ثانيًا ورسمًا ثانيًا.
COTA Partner APIأرسل
Idempotency-Key، فيُعيد المفتاح نفسه الاستجابة الأصلية ولا يُحصَّل مبلغ ثانٍ أبدًا. وإذا وصل طلبان في وقت واحد، أخذ أحدهما القفل وانتظر الآخر.تعطّل المورّد
المعتاد في القطاععندما يتعطّل المورّد يفشل الطلب فحسب، ولا يخبرك أحد بالسبب.
COTA Partner APIعند رفض قاطع ننتقل تلقائيًا إلى مورّد بديل. وإذا لم تصلنا أي إجابة فإننا لا ننتقل عن قصد، ونضع علامة «غير مؤكد» على السطر — لأن شراء الوحدة نفسها مرتين يكلّفك كما يكلّفنا.
وضوح الحساب
المعتاد في القطاعكشف في نهاية الشهر، وكل ما بينهما صندوق مغلق.
COTA Partner APIدفتر لا يُضاف إليه إلا إضافة: كل خصم وكل إضافة مع سببه، ويمكن قراءته فورًا عبر
GET /ledger. اعمل بالدفع المسبق أو بحد ائتماني متفق عليه؛ وفي الحالتين يبقى حساب التشغيل الفعلي منفصلًا عن حساب Sandbox.إيصال الأحداث
المعتاد في القطاعالاستقصاء المتكرر: تسأل باستمرار هل تغيّر الطلب.
COTA Partner APIwebhook موقَّع. تُكتب الأحداث داخل معاملة العمل نفسها، فلا يمكن أن يُغلق طلب ويضيع إشعاره. وإذا لم نصل إليك نُعيد المحاولة على ثمانية فواصل متزايدة، ويصلك بريد إذا وُسم عنوانك بأنه غير سليم.
الاسترداد
المعتاد في القطاعسلاسل بريد وانتظار بلا موعد، ولا تعرف أين وصل طلبك.
COTA Partner APIافتح طلب استرداد عبر الواجهة البرمجية وتابعه بـ
GET /refunds. وعند الموافقة تُكتب الإضافة في المعاملة نفسها التي يتغيّر فيها الحالة، فتصبح حالة «مُوافَق عليه ولم يُدفع» مستحيلة بحكم البنية.المتابعة اليومية
المعتاد في القطاعلوحة على الحاسب المكتبي، فينتهي الوضوح لحظة مغادرتك المكتب.
COTA Partner APIادخل تطبيقنا على الهاتف بالحساب نفسه، وانتقل إلى جانب الشركاء، وتابع طلباتك وبطاقات eSIM ودفترك من هاتفك.
| المعتاد في القطاع | COTA Partner API | |
|---|---|---|
| بيئة الاختبار | بيئة Sandbox إما غير موجودة أو تتصرف بخلاف بيئة التشغيل، فتضطر إلى تجربة الربط بأموال حقيقية. | تعمل Sandbox على نفس مسار الكود المستخدم في التشغيل الفعلي: نفس التحققات ونفس رموز الأخطاء، مع رصيد مستقل. والبيئة جزء من مفتاح عدم التكرار، فلا يمكن لطلب في Sandbox أن ينعكس على طلب فعلي أبدًا. |
| التسليم الجزئي | طلبت عشرًا فوصلت سبع. تبقى قيمة الثلاث الأخرى معلّقة في مكان ما، فتفتح تذكرة دعم. | تُعاد قيمة كل وحدة لم تُسلَّم إلى رصيدك داخل المعاملة نفسها. وتُظهر الاستجابة requestedQuantity وfulfilledCount كلًّا على حدة، فلا تحتاج إلى التخمين. |
| الطلبات المُعادة | إعادة المحاولة بعد انتهاء المهلة تُنشئ طلبًا ثانيًا ورسمًا ثانيًا. | أرسل Idempotency-Key، فيُعيد المفتاح نفسه الاستجابة الأصلية ولا يُحصَّل مبلغ ثانٍ أبدًا. وإذا وصل طلبان في وقت واحد، أخذ أحدهما القفل وانتظر الآخر. |
| تعطّل المورّد | عندما يتعطّل المورّد يفشل الطلب فحسب، ولا يخبرك أحد بالسبب. | عند رفض قاطع ننتقل تلقائيًا إلى مورّد بديل. وإذا لم تصلنا أي إجابة فإننا لا ننتقل عن قصد، ونضع علامة «غير مؤكد» على السطر — لأن شراء الوحدة نفسها مرتين يكلّفك كما يكلّفنا. |
| وضوح الحساب | كشف في نهاية الشهر، وكل ما بينهما صندوق مغلق. | دفتر لا يُضاف إليه إلا إضافة: كل خصم وكل إضافة مع سببه، ويمكن قراءته فورًا عبر GET /ledger. اعمل بالدفع المسبق أو بحد ائتماني متفق عليه؛ وفي الحالتين يبقى حساب التشغيل الفعلي منفصلًا عن حساب Sandbox. |
| إيصال الأحداث | الاستقصاء المتكرر: تسأل باستمرار هل تغيّر الطلب. | webhook موقَّع. تُكتب الأحداث داخل معاملة العمل نفسها، فلا يمكن أن يُغلق طلب ويضيع إشعاره. وإذا لم نصل إليك نُعيد المحاولة على ثمانية فواصل متزايدة، ويصلك بريد إذا وُسم عنوانك بأنه غير سليم. |
| الاسترداد | سلاسل بريد وانتظار بلا موعد، ولا تعرف أين وصل طلبك. | افتح طلب استرداد عبر الواجهة البرمجية وتابعه بـ GET /refunds. وعند الموافقة تُكتب الإضافة في المعاملة نفسها التي يتغيّر فيها الحالة، فتصبح حالة «مُوافَق عليه ولم يُدفع» مستحيلة بحكم البنية. |
| المتابعة اليومية | لوحة على الحاسب المكتبي، فينتهي الوضوح لحظة مغادرتك المكتب. | ادخل تطبيقنا على الهاتف بالحساب نفسه، وانتقل إلى جانب الشركاء، وتابع طلباتك وبطاقات eSIM ودفترك من هاتفك. |
عملك في جيبك
جانب الشركاء ليس محصورًا بالحاسب المكتبي. ادخل تطبيق COTA E-SIM ببريد الشريك الخاص بك فيظهر خيار «الانتقال إلى حساب الشريك»، وتصبح واجهتك التجارية داخل التطبيق نفسه.
لا يراه إلا من تدعوه
إن لم يكن بريدك مسجّلًا كمستخدم شريك، فلن يُظهر التطبيق أي زر خاص بالشركاء ولا أي إشارة إلى وجوده. أما العميل العادي فلم يتغيّر عنده شيء.
مبنيّ للمتابعة لا للبيع
جانب الهاتف للقراءة فقط عن قصد: تبقى الإجراءات غير القابلة للتراجع — كإنشاء طلب أو تغيير بيانات الدخول — في البوابة والواجهة البرمجية. لمسة خاطئة على الهاتف لا تستطيع إنفاق المال.
متطابق على iOS وAndroid
نفس الشاشات وبنفس الترتيب على المنصّتين، فلا يصبح نوع هاتف فريقك فرقًا في التدريب.
وصول يُفتح بالدعوة
تدعو زميلك بالبريد الإلكتروني، ولا يُفعَّل الحساب إلا بعد أن يؤكّد هو الرابط في بريده. فالعنوان المكتوب خطأً لا يفتح أي باب.
الشاشات نفسها موجودة في البوابة على partner.cotaesim.com — وهناك تجد بيانات الدخول وإعدادات webhook وطلب الانتقال إلى التشغيل الفعلي.
سطح تتعلّمه في بعد ظهيرة واحدة
أقل من عشرين نقطة نهاية إجمالًا: المصادقة والكتالوج والطلبات ودورة حياة eSIM وحركات الحساب وwebhook. وكلها تستخدم المصادقة نفسها وعقد الأخطاء نفسه وأسلوب التصفيح نفسه — فمن تعلّم واحدة تعلّمها جميعًا.
- أخطاء العمل تُرجع 422 مع
codeقابل للقراءة آليًا، أما 429 فيعني حدّ المعدّل ولا شيء غير ذلك. - يأتي الطلب والتسليم ورمز QR في استجابة واحدة، فلا تنتظر نداءً ثانيًا.
- تتصرّف كل نقطة نهاية بالطريقة نفسها مع بيانات Sandbox وبيانات التشغيل الفعلي.
كل نقطة نهاية ومخطط طلبها واستجابتها وقائمة الأخطاء كاملةً موجودة في مرجع OpenAPI — وهو مستند حيّ يمكنك تجربة النداءات عليه.
افتح المرجع الكامل للواجهة البرمجيةأسئلة تتكرر علينا
هل أحدد سعر البيع للمستهلك؟
نعم. نبيع لك بسعر الجملة، وما تتقاضاه من عميلك قرارك وحدك. والمبلغ الذي تراه في الكتالوج هو ما سنحسبه عليك.
هل أستطيع البيع تحت علامتي التجارية؟
نعم — تُرجع الواجهة البرمجية بيانات التسليم الخام (سلسلة LPA، والرابط الشامل لـ iOS، وصورة رمز QR). تعرضها في تطبيقك وبريدك وتصميمك، ولا يرانا عميلك أبدًا.
دفع مسبق أم ائتمان؟
الخيارَان متاحان. في الدفع المسبق يُخصم ما تشحنه لحظة وصول الطلب، وعند نفاده لا يُنشأ أي طلب — فلا يتراكم دين من دون علمك. وفي الائتمان يمكنك النزول تحت الصفر بحدود متفق عليها؛ والنمط المطبَّق عليك محدَّد في حسابك، وGET /balance يبلّغك به. ولا يسري الائتمان إلا على حساب التشغيل الفعلي، أما Sandbox فتعمل دائمًا برصيدها الاختباري. وفي النمطين كليهما تُنبَّه عند اقترابك من الحد.
هل الاسترداد تلقائي؟
لا، وذلك عن قصد. POST /refunds يفتح طلبًا فقط، والقرار لفريقنا. ولحظة الموافقة تُكتب الإضافة في دفترك في المعاملة نفسها التي يتغيّر فيها الحالة، ويبقى سبب القرار مرفقًا بالطلب.
هل Sandbox مطابقة فعلًا لبيئة التشغيل؟
نفس نقاط النهاية ونفس قواعد التحقق ونفس رموز الأخطاء ونفس أحداث webhook. والفرق أنها تخصم من رصيد مستقل وتعيد بطاقة eSIM للاختبار تشير إلى نطاق اختباري، ولا يتم تجهيز أي خط حقيقي.
هل يمكن لأكثر من شخص من فريقي الدخول؟
نعم. ادعُ من تشاء من المستخدمين إلى البوابة وإلى جانب الهاتف؛ والدخول بالبريد الإلكتروني ورمز يُستخدم مرة واحدة، دون كلمات مرور. وتبقى كل دعوة غير نشطة حتى يؤكّدها صاحبها من بريده.
وإن لم يكن لديّ فريق تقني؟
تؤدي البوابة على الشاشة معظم ما تؤديه الواجهة البرمجية: الكتالوج وسجل الطلبات وتفاصيل eSIM والدفتر وطلبات الاسترداد. فيمكنك أن تبدأ العمل دون كتابة سطر واحد مقابل الواجهة البرمجية.
لنتحدّث ونعرض عليك الكتالوج
سنُعدّ لك قائمة أسعارك ونفتح بيانات دخولك إلى Sandbox لتجرّب الربط على وتيرتك. والانتقال إلى التشغيل الفعلي زر واحد، متى كنت مستعدًّا.