API شريك
اربط أنظمتك الداخلية أو تطبيقاتك بشريك مباشرة — اسحب بيانات عملائك وعقودك، أنشئ فواتير، واستقبل تنبيهات فورية بالـwebhooks.
المصادقة
كل طلب لازم يحمل توكن Bearer في الـheader. تقدر تولّد توكن من إعدادات حسابك (Tokens API) بعد ما تسجّل دخول.
Authorization: Bearer YOUR_API_TOKEN
كل توكن بيتحدد له صلاحية أو أكتر (abilities) وقت إنشائه — الـendpoint بيرفض أي توكن مالوش الصلاحية المطلوبة.
| الصلاحية | بتسمح بإيه |
|---|---|
read | قراءة العملاء، العقود، كشوف الحساب، ميزان المراجعة، توقع التدفق النقدي |
write-invoices | إنشاء فواتير مسودة (لسه محتاجة مراجعة وترحيل يدوي من الشاشة العادية) |
manage-webhooks | إدارة اشتراكات الـwebhook (عرض/إضافة/حذف) |
حد أقصى 60 طلب في الدقيقة لكل توكن.
رموز الأخطاء
| الحالة | المعنى |
|---|---|
401 | توكن مفقود، غلط، منتهي، أو حساب صاحب التوكن معطّل |
402 | اشتراك الشركة منتهي |
403 | التوكن مالوش الصلاحية المطلوبة، أو الموديول ده مش مفعّل للشركة |
404 | السجل مش موجود، أو تابع لشركة تانية |
422 | بيانات الطلب غير صحيحة |
429 | تجاوزت حد الطلبات (60/دقيقة) |
الـEndpoints
قائمة عملاء شركتك، مقسّمة صفحات (حد أقصى 100 في الصفحة).
curl https://app.sharikadvisory.com/api/v1/clients \ -H "Authorization: Bearer YOUR_API_TOKEN"
{
"data": [
{ "id": 1, "name": "أحمد محمد", "phone": "99887766", "email": null, "created_at": "2026-07-01T10:00:00Z" }
],
"current_page": 1,
"per_page": 50
}
قائمة عقود التقسيط بتاعة شركتك.
curl https://app.sharikadvisory.com/api/v1/contracts \ -H "Authorization: Bearer YOUR_API_TOKEN"
كشف حساب تفصيلي لعقد معيّن.
إنشاء فاتورة عامة كـ"مسودة" — لسه محتاجة مراجعة وترحيل يدوي من شاشة الفواتير العادية، مش بترحّل تلقائي.
curl -X POST https://app.sharikadvisory.com/api/v1/invoices \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"client_id": 1,
"invoice_date": "2026-08-21",
"payment_type": "credit",
"lines": [
{ "account_id": 12, "description": "استشارة", "quantity": 1, "unit_price": 150.00 }
]
}'
ميزان مراجعة موحّد لمجموعة شركاتك (لو شركتك عضو في مجموعة).
توقع التدفق النقدي لعدد شهور قادمة (افتراضيًا 6).
Webhooks
سجّل رابط عندك عشان يستقبل تنبيه فوري (HTTPS فقط) أول ما حدث معيّن يحصل عندك.
curl -X POST https://app.sharikadvisory.com/api/v1/webhooks/subscriptions \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "url": "https://example.com/hook", "event": "payment.created" }'
الأحداث المتاحة
| event | بيتطلق لما |
|---|---|
payment.created | عند تسجيل دفعة جديدة |
invoice.posted | عند ترحيل فاتورة عامة |
vendor_bill.posted | عند ترحيل فاتورة مورد |
credit_note.posted | عند ترحيل مذكرة دائن |
debit_note.posted | عند ترحيل مذكرة مدين |
vendor_payment.created | عند تسجيل سداد لمورد |
invoice_payment.created | عند تسجيل سداد فاتورة عامة |
contract.created | عند إنشاء عقد تقسيط جديد |
quotation.accepted | عند قبول عميل لعرض سعر عن طريق رابط العميل |
quotation.rejected | عند رفض عميل لعرض سعر عن طريق رابط العميل |
purchase_order.confirmed | عند تأكيد مورد لأمر شراء عن طريق رابط المورد |
purchase_order.declined | عند رفض مورد لأمر شراء عن طريق رابط المورد |
كل طلب webhook بيتوقّع بـHMAC-SHA256 باستخدام السر (secret) اللي بترجعه وقت التسجيل — تأكد من التوقيع قبل ما تثق في المحتوى.