Hisabمركز المساعدة

البدء مع الـ API

2 دقيقة للقراءةآخر تحديث: Jun 3, 20264 مشاهدات

البدء مع الـ API

تتيح لك واجهة Hisab REST أتمتة الفوترة — إنشاء العملاء والفواتير، وإنهاؤها، وتصدير PDF/XML، والمزيد — مباشرةً من أنظمتك الخاصة.

متطلّب الخطة: الوصول إلى الـ API متاح في خطتي Professional وFiduciaire.

1. إنشاء مفتاح API

  1. اذهب إلى الإعدادات ← مفاتيح API.
  2. اضغط إنشاء مفتاح API.
  3. امنحه اسمًا واضحًا (مثل: «أتمتة الفوترة»).
  4. اختر الصلاحيات (scopes) المطلوبة (مبدأ أقل الامتيازات).
  5. أنشئه ثم انسخ المفتاح الآن — لأسباب أمنية يُعرض مرة واحدة فقط. احفظه في مكان آمن مثل مدير الأسرار.

2. المصادقة

أرسل مفتاحك بصيغة Bearer token. عنوان القاعدة هو:

https://hisab.ma/api/v1

مثال — عرض فواتيرك:

curl https://hisab.ma/api/v1/invoices \
  -H "Authorization: Bearer hisab_مفتاحك_هنا"

3. الصلاحيات (scopes)

المجموعةالصلاحيات
الفواتيرread, write, finalize, send, payment, void, export
الفواتير المتكررةread, write, delete
العملاءread, write, delete
المنظمةread, write
Webhooksread, write

4. إنشاء فاتورة

curl -X POST https://hisab.ma/api/v1/invoices \
  -H "Authorization: Bearer hisab_مفتاحك_هنا" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_...",
    "issue_date": "2026-06-03",
    "items": [
      { "description": "استشارة", "quantity": 10, "unit_price": 500, "tax_rate": 20 }
    ]
  }'

5. استخدام الـ SDK الرسمي (Node.js / TypeScript)

npm install hisab-sdk
import { HisabClient } from 'hisab-sdk';

const hisab = new HisabClient({ apiKey: process.env.HISAB_API_KEY });

const invoices = await hisab.invoices.list({ status: 'paid' });

6. Webhooks

للتفاعل مع الأحداث (مثل دفع فاتورة)، أعدّ نقاط النهاية من الإعدادات ← Webhooks. توقّع Hisab كل عملية إرسال حتى تتمكن من التحقق من صحتها.

ملاحظات

  • الطلبات محدودة المعدّل؛ عند تجاوز الحد ستحصل على 429 — تمهّل ثم أعد المحاولة.
  • حافظ على سرية مفاتيحك. في حال تسرّب أحدها، ألغِه من الإعدادات ← مفاتيح API وأنشئ آخر.

هل كانت هذه المقالة مفيدة؟

العودة إلى التكاملات وAPI
رجوعالرئيسيةالدعم