# بيئات API ومفاتيحها

> أنشئ مفاتيح API فعلية أو اختبارية، واختر النطاقات، واعثر على عنوان URL الأساسي لواجهة API في عليا بوكس.

Source: /help/ar/api/environments-and-api-keys

تتيح واجهة REST API في عليا بوكس لنظام تخطيط الموارد (ERP) أو متجرك أو أداة المحاسبة لديك إنشاء الفواتير واستيراد الفواتير المستلمة واستقبال webhooks. يُتحكم في الوصول عبر مفاتيح API التي تديرها في التطبيق.

## إنشاء مفتاح

1. انتقل إلى **API access** (الوصول إلى API) (مجموعة System في الشريط الجانبي) ← علامة التبويب **API keys** (مفاتيح API) ← **New key** (مفتاح جديد).
2. أعطه اسماً تتعرف عليه، مثل اسم النظام الذي يستخدمه.
3. شغّل **Test key** (مفتاح اختبار) إذا كان ينبغي وضع علامة اختبار على المستندات التي ينشئها.
4. حدد تاريخ انتهاء اختيارياً.
5. اختر النطاقات. **all** و**read-only** اختصاران.
6. انقر **Create key** (إنشاء مفتاح) وانسخ المفتاح من مربع الحوار التالي. يُعرض مرة واحدة فقط؛ وتخزن عليا بوكس تجزئة (hash) له.

## الفعلي والاختباري

| المفتاح | البادئة | الأثر |
|---|---|---|
| Live (فعلي) | `sk_live_…` | ينشئ مستندات حقيقية تتبع وضع **Settings → E-invoicing** (الإعدادات ← الفوترة الإلكترونية) لديك |
| Test (اختباري) | `sk_test_…` | ينشئ مستندات تحمل علامة الاختبار؛ لا تصل أبداً إلى مزود الخدمة المعتمد الفعلي وتُستبعد من التقارير. يُعيد السرد بمفتاح اختبار مستندات الاختبار فقط. |

مفتاح الاختبار هو البيئة التجريبية في عليا بوكس؛ ولا يوجد عنوان URL منفصل لبيئة اختبار (sandbox).

يبدأ كل مفتاح بـ `sk_live_` أو `sk_test_`، فتعرف البيئة من المفتاح نفسه. وينبغي لعمليات التكامل التي تتحقق من صيغة المفتاح أن تقبل هاتين البادئتين.

## النطاقات

لكل من Invoices وIncoming invoices وCustomers وProducts وCustom fields وNumber series النطاقان `read` و`write`؛ ويشمل write النطاق read. أما Webhooks فلها نطاق واحد هو `manage`. يحصل الطلب خارج نطاقات المفتاح على `403 FORBIDDEN` مع ذكر النطاق المفقود.

## عنوان URL الأساسي وأول استدعاء

تعرض بطاقة **Endpoint** (نقطة النهاية) في صفحة API access عنوان URL الأساسي لبيئتك (`https://api.alyabooks.ai/api/v1` بمجرد تفعيل النطاق المخصص) ومثالاً قابلاً للنسخ:

```
curl <base>/me -H "X-API-KEY: sk_live_…"
```

يُعيد `GET /me` مؤسستك ونطاقات المفتاح وبيئته.

## معلومات مفيدة

- يدير المالكون والمسؤولون المفاتيح. يحتاج الأعضاء الآخرون إلى صلاحية "manage API keys" (إدارة مفاتيح API) ضمن **Settings → Team → Permissions** (الإعدادات ← الفريق ← الصلاحيات).
- يعرض جدول المفاتيح البادئة وعدد النطاقات وآخر استخدام مع عدد الاستدعاءات، والحالة active أو expired أو revoked. يوقف **Revoke** (إبطال) المفتاح فوراً ويبقيه مدرجاً؛ ويزيله **Delete** (حذف).
- ترسل شركات المحاسبة (CA firms) الترويسة `X-Organization-Id: <client org id>` للعمل نيابة عن عميل مُدار.
- الحد: 600 طلب في الدقيقة لكل مفتاح.
- تسجل علامة التبويب **Recent requests** (الطلبات الأخيرة) الاستدعاءات لأغراض استكشاف الأخطاء. ويُربط بمواصفة OpenAPI من الصفحة نفسها.
- **التطبيقات المرتبطة**: يستطيع Claude وChatGPT وغيرهما من المساعدين الربط بتسجيل الدخول بدلاً من استخدام مفتاح. وتظهر مع صلاحياتها في بطاقة **Connected apps** (التطبيقات المرتبطة) ضمن تبويب API keys، حيث يوقفها **Revoke** (إلغاء). انظر [ربط عليا بوكس بـ Claude أو ChatGPT](/help/ar/api/connect-ai-assistants).

## مقالات ذات صلة

- [لماذا أحصل على 401 عند استدعاء API؟](/help/ar/api/401-troubleshooting)
- [أخطاء API ورموز الحالة](/help/ar/api/error-handling)