> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryoto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# التوثيق في واجهة API

> احصل على رمز التحديث من لوحة تحكم OTO، واستبدله برمز وصول صالح لساعة واحدة، وأرسله في ترويسة Bearer مع كل طلب إلى واجهة API.

رمزان: أحدهما تحتفظ به، والآخر تستبدله كل ساعة.

## احصل على رمز التحديث

من لوحة التحكم، انتقل إلى **الإعدادات ← API Integrations** واضغط **Connect**. سيُنشئ ذلك رمز `refresh_token` الخاص بك.

هذا الرمز **دائم**، وهو بيان الاعتماد الوحيد طويل الأمد لديك. ولا يمكن استخدامه لاستدعاء أي شيء سوى نقطة نهاية الرموز.

> [!WARNING]
>
> **تعامل مع رمز التحديث كأنه كلمة مرور**
>
> لأنه لا تنتهي صلاحيته، فإن الرمز المسرّب يبقى صالحًا لمن يحمله حتى يلاحظ أحدهم ذلك ويُعيد إنشاءه.
>
> مكانه الصحيح في مدير الأسرار (Secrets Manager) أو في متغير بيئة، وليس أبدًا في كود يعمل لدى العميل أو حزمة تطبيق جوال أو مستودع كود أو تذكرة دعم أو لقطة شاشة. فكل ما يصل إلى المتصفح يمكن لمستخدم هذا المتصفح قراءته.

## استبدله برمز وصول

`POST /rest/v2/refreshToken` Free+

```json theme={null}
{ "refresh_token": "<your permanent token>" }
```

تحتوي الاستجابة على `access_token` صالح لمدة **ساعة واحدة**. أرسِله مع كل استدعاء آخر:

```text theme={null}
Authorization: Bearer <access_token>
```

> [!TIP]
>
> **احتفظ برمز الوصول مؤقتًا؛ ولا تطلب رمزًا جديدًا مع كل طلب**
>
> الرمز صالح لمدة ساعة، لذا فإن المهمة التي تستدعي واجهة API ألف مرة خلال تلك الساعة تحتاج إلى رمز واحد، لا ألف رمز.
>
> النهج الموثوق: احتفظ بالرمز ووقت انتهائه في الذاكرة، وجدّده عندما يقترب من الانتهاء ببضع دقائق، وجدّده أيضًا عند تلقي الخطأ 401 بدلًا من افتراض تطابق ساعتك مع ساعة الخادم. فطلب رمز جديد مع كل استدعاء هو السبب الأكثر شيوعًا لبطء عمليات الربط.

## تحقق من الاتصال

`GET /rest/v2/healthCheck` Free+

يؤكد أن المنصة متاحة وتستجيب. يُستحسن ربطه بنظام المراقبة لديك، حتى تعرف عند حدوث أي عطل من أي جانب وقع.

## بيئة التجربة (Sandbox)

بيئة منفصلة لها حسابها ورمزها وشركات شحن تجريبية خاصة بها، على العنوان `https://staging-api.tryoto.com`. المسارات نفسها، وهياكل البيانات نفسها.

> [!NOTE]
>
> **ابنِ على بيئة التجربة، لكن اختبر الانتقال إلى الإنتاج**
>
> بيئة التجربة هي المكان الذي تُنشئ فيه طلبات لا تتحول إلى طرود حقيقية، وحجوزات لا تتحول إلى فواتير حقيقية. ولا توجد بيئة أخرى آمنة للتجربة المتكررة.
>
> اللحظة التي يجب الاستعداد لها هي الانتقال إلى الإنتاج: ففي بيئة الإنتاج عقود شحن ومراكز ورموز مختلفة. والقيمة الثابتة المكتوبة داخل الكود أثناء التطوير هي المشكلة المعتادة في أول يوم بعد الإطلاق، لذا احفظ كل قيمة خاصة بالبيئة في ملفات الإعداد منذ أول commit.

## التوفر حسب الباقة

تخضع نقاط النهاية لمستوى الاشتراك، وبعضها يتطلب أيضًا إضافة (Add-on). وكل نقطة نهاية في [الفهرس](https://docs.tryoto.com/ar/developers/rest-api-reference.md) موضح بجانبها أدنى باقة تتضمنها.

| الباقة | ما الذي تتيحه؟ |
| - | - |
| Free+ | الطلبات، الشحنات، الطباعة، التتبع، المنتجات، الاستعلام عن شركات الشحن، العنوان الوطني. وهذا يكفي لتشغيل عملية ربط متكاملة من البداية للنهاية. |
| Starter+ | Webhooks، عقودك الخاصة مع شركات الشحن، العلامات التجارية، أتمتة المرتجعات، OTO FLEX، وStock Management مع إضافة WMS. |
| Scale+ | فرض حالة الطلب من جانبك، سجل إشعارات العملاء، وتقدير موعد التوصيل بما في ذلك المواعيد المتوقعة بالذكاء الاصطناعي. |
| Pro+ | التحقق من التوفر قبل الالتزام، وعدد غير محدود من قنوات البيع. |
| Enterprise+ | تتبع الشحنات على مستوى شركة الشحن، عدد غير محدود من عقود شركات الشحن، ونقاط استلام الطلب من نوع **الفرع**. |

> [!NOTE]
>
> **الشحن من المتجر عبر واجهة API ميزة في باقة الأعمال**
>
> يمكن إنشاء نقاط استلام الطلب في جميع الباقات، لكن بوصفها **مستودعات** فقط. أما إنشاء نقطة من النوع `type: "branch"`، أي متجر يشحن أيضًا، فمتاح في باقة الأعمال فقط.
>
> إذا كنت تخطط لجعل المتاجر تجهّز الطلبات برمجيًا، فهذا هو الحد الذي يجب التحقق منه قبل أن تبني تصميمك عليه. راجع [إدارة المراكز](https://docs.tryoto.com/ar/modules/hubs-management/overview.md) لمعرفة ما هو الفرع ولماذا يهم.

## صفحات ذات صلة

* [Webhooks](https://docs.tryoto.com/ar/developers/webhook-events.md) — أن تُبلَّغ بدلًا من أن تسأل.
* [فهرس نقاط النهاية](https://docs.tryoto.com/ar/developers/rest-api-reference.md) — الواجهة كاملةً.


## Related topics

- [أخطاء واجهة API وحدود الاستخدام](https://docs.tryoto.com/ar/developers/errors-and-rate-limits.md)
- [نظرة عامة على OTO API](https://docs.tryoto.com/ar/developers/overview.md)
- [البدء السريع: اشحن أول طلب مع OTO](https://docs.tryoto.com/ar/get-started/quickstart.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.