بيئات API ومفاتيحها
أنشئ مفاتيح API فعلية أو اختبارية، واختر النطاقات، واعثر على عنوان URL الأساسي لواجهة API في عليا بوكس.
تتيح واجهة REST API في عليا بوكس لنظام تخطيط الموارد (ERP) أو متجرك أو أداة المحاسبة لديك إنشاء الفواتير واستيراد الفواتير المستلمة واستقبال webhooks. يُتحكم في الوصول عبر مفاتيح API التي تديرها في التطبيق.
إنشاء مفتاح
- انتقل إلى API access (الوصول إلى API) (مجموعة System في الشريط الجانبي) ← علامة التبويب API keys (مفاتيح API) ← New key (مفتاح جديد).
- أعطه اسماً تتعرف عليه، مثل اسم النظام الذي يستخدمه.
- شغّل Test key (مفتاح اختبار) إذا كان ينبغي وضع علامة اختبار على المستندات التي ينشئها.
- حدد تاريخ انتهاء اختيارياً.
- اختر النطاقات. all وread-only اختصاران.
- انقر 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.