REST API

كل إجراء في واجهة Celerp نقطة نهاية REST، وهي الواجهة البرمجية نفسها التي تستخدمها واجهة الاستخدام داخليًا. أتمِت سير العمل، أو اربط أنظمة أخرى، أو ابنِ أدواتك الخاصة. تعمل الواجهة البرمجية محليًا على بياناتك؛ ولا يُرسَل شيء إلى السحابة.

المصادقة

يستخدم Celerp رموز وصول قصيرة الأمد من نوع JSON Web Token. سجّل الدخول ببريدك الإلكتروني وكلمة مرورك في Celerp للحصول على رمز وصول، ثم أرسله في ترويسة Bearer مع كل طلب.

1. تسجيل الدخول

curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "your-password"}'

تحتوي الاستجابة على رمزَين:

{
  "access_token": "eyJhbGciOiJI...",
  "refresh_token": "eyJhbGciOiJI..."
}

2. استدعاء الواجهة البرمجية باستخدام الرمز

curl http://localhost:8000/items \
  -H "Authorization: Bearer eyJhbGciOiJI..."

• يُعرّف الرمز المستخدمَ والدورَ والشركةَ، لذا تُقيَّد الطلبات تلقائيًا بتلك الشركة - دون الحاجة إلى ترويسة إضافية.
• تصل صلاحية رموز الوصول إلى 24 ساعة. عند انتهاء صلاحية أحدها، احصل على زوج جديد بإرسال refresh_token بطريقة POST إلى /auth/token/refresh.
• هل تنتمي إلى أكثر من شركة؟ أدرجها باستخدام GET /auth/my-companies، ثم احصل على رمز لشركة أخرى باستخدام POST /auth/switch-company/{company_id}.

إرسال الطلبات

توجد جميع نقاط النهاية تحت عنوان خادم الواجهة البرمجية لديك (http://localhost:8000 في تثبيت pip، كما في الأمثلة أدناه) وتُعيد JSON. وتُعيد نقاط نهاية القوائم مصفوفة items وإجماليًا في total:

curl "http://localhost:8000/items?limit=20&offset=0" \
  -H "Authorization: Bearer $TOKEN"

{
  "items": [
    { "id": "item:...", "sku": "WIDGET-001", "name": "Widget", "quantity": 42 }
  ],
  "total": 142
}

تقسيم الصفحات: مرّر ?limit= (الافتراضي 50) و?offset=. وتقبل معظم نقاط نهاية القوائم أيضًا عبارة بحث في q= ومرشّحات للأعمدة (مثل ?status=available).

إنشاء البيانات

أرسل JSON بطريقة POST لإنشاء السجلات. وتُعيد عمليات الكتابة مُعرِّف الكيان الجديد id (ومعه event_id الأساسي، فكل تغيير في Celerp حدث).

curl -X POST http://localhost:8000/crm/contacts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "email": "[email protected]",
    "contact_type": "customer",
    "idempotency_key": "acme-2026-06-21"
  }'

الاصطلاحات

• الأخطاء تُعيد الاستجابات التي لا تبدأ بـ 2xx الشكل {"detail": "..."} مع رمز حالة HTTP قياسي.
• حدود المعدّل 60 طلبًا في الدقيقة لكل عنوان IP افتراضيًا، وتسجيل الدخول محدود بـ 10 طلبات في الدقيقة. وتجاوز الحد يُعيد الرمز 429.
• الصلاحيات تخضع نقاط النهاية لدورك: viewer → operator → manager → admin → owner.
• نطاق الشركة يعمل كل طلب على الشركة المحدّدة في رمز وصولك؛ وللعمل على شركة أخرى بدّل الشركة أولًا.

نقاط النهاية الشائعة

شريحة صغيرة تكفي للبدء. وتضيف كل وحدة نقاط النهاية الخاصة بها، والقائمة الكاملة في مخطط OpenAPI أدناه.

مرجع كامل حسب القسم

كل نقطة نهاية يقدّمها الـ API قيد التشغيل، مجمّعة حسب القسم. تسرد كل صفحة الطريقة والمسار والمعاملات وبنية الطلب والاستجابة ومثالًا على الاستدعاء.

استكشاف الواجهة البرمجية الكاملة

المرجع الكامل والمحدَّث دائمًا مخطط OpenAPI 3.1 الذي تولّده نسختك:

GET http://localhost:8000/openapi.json

حمّله في أي أداة تدعم OpenAPI - Postman أو Insomnia أو Swagger UI أو أي مولّد عملاء برمجيين - لتستعرض كل نقطة نهاية وكل نموذج، وتجرّب الطلبات، وتولّد عميلًا بأنواع محدّدة بلغتك. ويشحن Celerp المخطط نفسه بدلًا من صفحة توثيق مستضافة، لتبقى واجهتك البرمجية خاصة بنسختك وحدها.