# دليل API — ربط البرنامج المحاسبي بنظام التراخيص

**Base URL** (مثال فقط): `https://licenses.example.com/api/v1`

جميع الطلبات عبر HTTPS، وتستخدم `Content-Type: application/json`. لا يمكن لأي استدعاء عام الحصول على كود التفعيل أو معلومات خاصة بالعميل. يجب أن يحتوي البرنامج المحاسبي نفسه على واجهة لإدخال كود التفعيل الذي نسخَه المشتري من بوابته.

## 1. تسجيل النسخة التجريبية

`POST /api/v1/installations/register`

```bash
curl -X POST https://licenses.example.com/api/v1/installations/register \
  -H 'Content-Type: application/json' \
  -d '{"installation_code":"ACC-2026-8F92-KL47","app_version":"1.0.0"}'
```

استجابة متوقعة (قيم تجريبية):

```json
{
  "registered": true,
  "status": "تجريبي",
  "active": true,
  "trial_ends_at": "2026-11-17 00:00:00"
}
```

إذا كانت النسخة مسجلة أصلاً فلن يعيد التسجيل بدء فترة التجربة، حتى لو كرر البرنامج الاتصال.

## 2. التحقق من كود التفعيل

`POST /api/v1/licenses/validate`

```bash
curl -X POST https://licenses.example.com/api/v1/licenses/validate \
  -H 'Content-Type: application/json' \
  -d '{"installation_code":"ACC-2026-8F92-KL47","activation_key":"LIC-6D293F-6A25BC-29082A-7A6F51"}'
```

إذا كان الترخيص صالحاً، يكون الرد شبيهاً بما يلي:

```json
{
  "valid": true,
  "status": "active",
  "expires_at": "2027-11-03T16:00:00Z",
  "edition": "Standard",
  "checked_at": "2026-11-03T16:30:00Z"
}
```

إذا انتهت المدة أو أوقف الترخيص:

```json
{
  "valid": false,
  "status": "expired",
  "expires_at": "2026-11-01T00:00:00Z",
  "checked_at": "2026-11-03T16:30:00Z"
}
```

الحالات المرجعية: `active`, `expired`, `suspended`, `revoked`, `invalid_key`, `not_activated`.

**تنبيه:** مفاتيح التفعيل الواردة في الأمثلة ليست موجودة في قاعدة البيانات ولن تُفعّل أي برنامج. الرد ليس شهادة موقعة للعمل دون اتصال. لا تجعل البرنامج يصدق أي JSON محفوظ محلياً دون حماية؛ هذه وظيفة لاحقة تتطلب تصميم مفتاح عام/خاص وخطة للتجديد والتعليق.

## اقتراح آلية ربط تطبيق المحاسبة

1. عند التشغيل الأول أنشئ معرف نسخة عشوائياً وأبقِه ثابتاً عبر التشغيلات المعتادة. الأفضل توليد عشوائية قوية بدلاً من استخدام رقم القرص/الجهاز وحده.
2. سجّل النسخة باستدعاء `/installations/register`، ثم اعرض المعرف للمستخدم.
3. احفظ كود التفعيل الذي أدخله العميل محلياً في مخزن أسرار مناسب للمنصة التي يعمل عليها التطبيق.
4. عند التفعيل وعند نقاط التحقق المطلوبة، أرسل كود النسخة وكود التفعيل إلى `/licenses/validate` عبر HTTPS.
5. حدّد سلوكاً معقولاً لانقطاع الشبكة وعدم توفر الخادم، بحيث لا تفقد المؤسسة الوصول إلى سجلاتها المحاسبية بسبب عطل عابر.
6. إذا احتاج البرنامج العمل بالكامل دون إنترنت، أضف لاحقاً ترخيصاً موقّعاً مع مدة تحديث وبروتوكول للتحقق من الإلغاء.

## خصوصية المستخدم

نقطة الاستعلام البشرية `/license/check` تعرض معلومات عامة محدودة، أما بيانات العميل وكود التفعيل الكامل فلا تُعرض إلا بعد دخول عبر رابط بريد مؤقت أو داخل حساب المدير.