مرجع API

واجهة REST API لحساب

صادق بمفتاح API، أنشئ الفواتير وثبّتها، وأدر العملاء والفواتير المتكررة. كل نقطة نهاية أدناه تعمل في الإنتاج.

31نقطة نهاية|https://hisab.ma/api/v1

البداية

واجهة حساب هي API REST بصيغة JSON عبر HTTPS. كل طلب يُصادَق بمفتاح API ويقتصر على مؤسستك.

الرابط الأساسي

https://hisab.ma/api/v1

الوصول إلى API مشمول في عرضي Professional وFiduciaire. قارن العروض

حدود المعدل

الطلبات محدودة في الدقيقة لكل مفتاح API. عند التجاوز تعيد الواجهة 429 RATE_LIMIT_EXCEEDED مع ترويسة Retry-After.

العرض	الطلبات	مفاتيح API
Professional	120 req/min	10
Fiduciaire	300 req/min	غير محدودة

كل استجابة تُظهر استهلاكك الحالي في هذه الترويسات:

headers

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1780750800

المصادقة

تُنشأ مفاتيح API من لوحة التحكم: الإعدادات ثم مفاتيح API. تختار الصلاحيات عند الإنشاء، ويُعرض السر الكامل مرة واحدة فقط.

أرسل المفتاح كرمز Bearer في ترويسة Authorization:

cURL

curl https://hisab.ma/api/v1/invoices \
  -H "Authorization: Bearer hisab_live_***"

hisab_live_***

مفتاح إنتاج. يعمل على بياناتك الحقيقية.

hisab_test_***

مفتاح اختبار. نفس الصيغة، لبيئات التجريب.

تُخزن المفاتيح مُجزأة (SHA-256) لدينا ويمكن إلغاؤها في أي وقت من لوحة التحكم. استجابة 401 تعني أن المفتاح مفقود أو غير صالح أو مُلغى:

401

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

الصلاحيات

كل مفتاح يحمل قائمة صريحة من الصلاحيات. الطلب الذي يتطلب صلاحية غير موجودة يعيد 403 FORBIDDEN مع الصلاحيات المطلوبة في تفاصيل الخطأ.

invoices:readinvoices:writeinvoices:finalizeinvoices:sendinvoices:paymentinvoices:voidinvoices:exportrecurring:readrecurring:writerecurring:deletecustomers:readcustomers:writecustomers:deleteorganization:readorganization:writewebhooks:readwebhooks:writeorganizations:readorganizations:writeorganizations:archive

عند إنشاء مفتاح تقترح لوحة التحكم ثلاث حزم (قراءة فقط، فوترة، وصول كامل)، ويمكنك دائماً اختيار الصلاحيات واحدة واحدة.

تقسيم الصفحات

نقاط نهاية القوائم تقبل page وper_page (بحد أقصى 100) وتعيد كتلة pagination داخل meta:

JSON

{
  "success": true,
  "data": [ ... ],
  "meta": {
    "pagination": { "total": 128, "page": 1, "perPage": 20, "totalPages": 7 }
  }
}

الأخطاء

كل الأخطاء بنفس الشكل: success تساوي false، وerror يحمل رمزاً ثابتاً ورسالة مقروءة وتفاصيل اختيارية لكل حقل. الرموز القياسية:

`VALIDATION_ERROR`	400
`INVALID_JSON`	400
`UNAUTHORIZED`	401
`FORBIDDEN`	403
`API_DISABLED`	403
`SUBSCRIPTION_EXPIRED`	403
`API_TIER_NOT_SUPPORTED`	403
`ORG_HEADER_REQUIRED`	400
`ACCOUNT_KEY_REQUIRED`	403
`ENTITY_CAP_REACHED`	403
`NOT_FOUND`	404
`RATE_LIMIT_EXCEEDED`	429
`INTERNAL_ERROR`	500

Webhooks

يوقع حساب ويرسل حدثاً إلى نقطتك عند كل تغيير في فاتورة أو عميل. تُضبط Webhooks من لوحة التحكم: الإعدادات ثم Webhooks.

invoice.createdinvoice.updatedinvoice.finalizedinvoice.sentinvoice.paidinvoice.voidedcustomer.createdcustomer.updatedcustomer.deleted

اقرأ دليل Webhooks

الفواتير

أنشئ مسودات فواتير، ثبّتها للحصول على الرقم الرسمي، ثم تتبع الإرسال والدفع والإلغاء. الفواتير المثبتة تُصدّر PDF وXML بصيغة UBL 2.1.

GET/api/v1/invoices

قائمة الفواتير

تعيد فواتير مؤسستك، الأحدث أولاً. رشّح حسب الحالة أو العميل أو تاريخ الإصدار.

الصلاحياتinvoices:read

معاملات الاستعلام

`page`	integerdefault: 1
`per_page`	integerdefault: 20 (max 100)
`order`	stringdefault: desc `ascdesc`
`status`	string `draftfinalizedsentpaidvoid`
`customer_id`	uuid
`date_from`	date (YYYY-MM-DD)
`date_to`	date (YYYY-MM-DD)

cURL

curl https://hisab.ma/api/v1/invoices \
  -H "Authorization: Bearer hisab_live_***"

GET/api/v1/invoices/:id

جلب فاتورة

تعيد فاتورة واحدة مع عميلها وبنودها ومجاميعها.

الصلاحياتinvoices:read

cURL

curl https://hisab.ma/api/v1/invoices/{id} \
  -H "Authorization: Bearer hisab_live_***"

POST/api/v1/invoices

إنشاء فاتورة

تنشئ مسودة. تُحسب المجاميع والضرائب على الخادم من البنود.

الصلاحياتinvoices:writeinvoice.created

معاملات الجسم

`customer_id`required	uuid
`issue_date`required	date (YYYY-MM-DD)
`due_date`	date (YYYY-MM-DD)
`currency`	stringdefault: MAD
`payment_terms`	string
`notes`	string
`internal_notes`	string
`items[].description`required	string
`items[].quantity`required	number
`items[].unit_price`required	number
`items[].tax_rate`	numberdefault: 20

cURL

curl https://hisab.ma/api/v1/invoices \
  -X POST \
  -H "Authorization: Bearer hisab_live_***" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_2b81fe",
    "issue_date": "2026-06-05",
    "items": [
      {
        "description": "Integration services",
        "quantity": 8,
        "unit_price": 1300,
        "tax_rate": 20
      }
    ]
  }'

PATCH/api/v1/invoices/:id

تعديل فاتورة

تعدل مسودة. الفواتير المثبتة غير قابلة للتغيير؛ يعيد الاستدعاء INVOICE_NOT_EDITABLE.

الصلاحياتinvoices:writeinvoice.updated

معاملات الجسم

`customer_id`	uuid
`issue_date`	date (YYYY-MM-DD)
`due_date`	date (YYYY-MM-DD)
`currency`	string
`payment_terms`	string
`notes`	string
`items[].description`	string
`items[].quantity`	number
`items[].unit_price`	number
`items[].tax_rate`	numberdefault: 20

أخطاء خاصةINVOICE_NOT_EDITABLE

cURL

curl https://hisab.ma/api/v1/invoices/{id} \
  -X PATCH \
  -H "Authorization: Bearer hisab_live_***" \
  -H "Content-Type: application/json" \
  -d '{
    "due_date": "2026-08-05"
  }'

POST/api/v1/invoices/:id/finalize

تثبيت فاتورة

يمنح الرقم التسلسلي الرسمي ويقفل الفاتورة. هذه خطوة الإصدار القانوني.

الصلاحياتinvoices:finalizeinvoice.finalized

أخطاء خاصةINVOICE_NOT_DRAFTVALIDATION_ERROR

cURL

curl https://hisab.ma/api/v1/invoices/{id}/finalize \
  -X POST \
  -H "Authorization: Bearer hisab_live_***"

POST/api/v1/invoices/:id/send

وضع علامة مُرسلة

يسجل أن الفاتورة المثبتة سُلمت إلى العميل.

الصلاحياتinvoices:writeinvoice.sent

أخطاء خاصةINVALID_STATUS_TRANSITION

cURL

curl https://hisab.ma/api/v1/invoices/{id}/send \
  -X POST \
  -H "Authorization: Bearer hisab_live_***"

POST/api/v1/invoices/:id/pay

وضع علامة مدفوعة

يسجل دفعة، مع طريقة ومرجع اختياريين.

الصلاحياتinvoices:writeinvoice.paid

معاملات الجسم

`paid_at`	datetime (ISO 8601)
`payment_method`	string
`payment_reference`	string

أخطاء خاصةINVALID_STATUS_TRANSITION

cURL

curl https://hisab.ma/api/v1/invoices/{id}/pay \
  -X POST \
  -H "Authorization: Bearer hisab_live_***" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method": "bank_transfer",
    "payment_reference": "VIR-20260605"
  }'

POST/api/v1/invoices/:id/void

إلغاء فاتورة

يلغي فاتورة مثبتة بسبب إلزامي. الفاتورة المدفوعة لا يمكن إلغاؤها.

الصلاحياتinvoices:writeinvoice.voided

معاملات الجسم

reasonrequired string

أخطاء خاصةCANNOT_VOID_PAIDALREADY_VOIDED

cURL

curl https://hisab.ma/api/v1/invoices/{id}/void \
  -X POST \
  -H "Authorization: Bearer hisab_live_***" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Duplicate billing"
  }'

GET/api/v1/invoices/:id/pdf

تحميل PDF

يعيد ملف PDF المُتحقق منه بالفرنسية أو الإنجليزية أو العربية. متاح بعد التثبيت.

الصلاحياتinvoices:export

معاملات الاستعلام

locale

stringdefault: fr

frenar

أخطاء خاصةPDF_NOT_AVAILABLE

cURL

curl https://hisab.ma/api/v1/invoices/{id}/pdf \
  -H "Authorization: Bearer hisab_live_***"

GET/api/v1/invoices/:id/xml

تحميل XML

يعيد XML بصيغة UBL 2.1 للفاتورة المثبتة.

الصلاحياتinvoices:export

أخطاء خاصةXML_NOT_AVAILABLE

cURL

curl https://hisab.ma/api/v1/invoices/{id}/xml \
  -H "Authorization: Bearer hisab_live_***"

العملاء

عملاء B2B وB2C بمعرفات مغربية (ICE، السجل التجاري). الأرشفة تحافظ على سجل الفواتير.

GET/api/v1/customers

قائمة العملاء

تعيد العملاء، مع بحث في الاسم والبريد ورقم ICE.

الصلاحياتcustomers:read

معاملات الاستعلام

`page`	integerdefault: 1
`per_page`	integerdefault: 20 (max 100)
`order`	stringdefault: desc `ascdesc`
`search`	string
`type`	string `b2bb2c`
`status`	string `activeinactivearchived`

cURL

curl https://hisab.ma/api/v1/customers \
  -H "Authorization: Bearer hisab_live_***"

GET/api/v1/customers/:id

جلب عميل

يعيد عميلاً واحداً مع بيانات الاتصال والعنوان.

الصلاحياتcustomers:read

cURL

curl https://hisab.ma/api/v1/customers/{id} \
  -H "Authorization: Bearer hisab_live_***"

POST/api/v1/customers

إنشاء عميل

عملاء B2B يجب أن يحملوا رقم ICE من 15 رقماً. تُرفض التكرارات داخل مؤسستك.

الصلاحياتcustomers:writecustomer.created

معاملات الجسم

`name`required	string
`type`required	string `b2bb2c`
`ice`	string (15 digits)
`legal_name`	string
`rc`	string
`email`	string
`phone`	string
`address.street`	string
`address.city`	string
`address.postal_code`	string
`address.country`	stringdefault: MA
`notes`	string
`tags`	string[]

cURL

curl https://hisab.ma/api/v1/customers \
  -X POST \
  -H "Authorization: Bearer hisab_live_***" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MERIT Sarl",
    "type": "b2b",
    "ice": "001234567000089",
    "email": "compta@example.ma"
  }'

PATCH/api/v1/customers/:id

تعديل عميل

تحديث جزئي: أرسل الحقول المتغيرة فقط.

الصلاحياتcustomers:writecustomer.updated

معاملات الجسم

`name`	string
`type`	string `b2bb2c`
`ice`	string (15 digits)
`email`	string
`phone`	string
`address`	object
`notes`	string
`tags`	string[]
`status`	string `activeinactivearchived`

cURL

curl https://hisab.ma/api/v1/customers/{id} \
  -X PATCH \
  -H "Authorization: Bearer hisab_live_***" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "finance@example.ma"
  }'

DELETE/api/v1/customers/:id

أرشفة عميل

حذف ناعم. يُؤرشف العميل ويبقى سجل فواتيره سليماً.

الصلاحياتcustomers:deletecustomer.deleted

أخطاء خاصةALREADY_ARCHIVED

cURL

curl https://hisab.ma/api/v1/customers/{id} \
  -X DELETE \
  -H "Authorization: Bearer hisab_live_***"

الفواتير المتكررة

جداول تولّد الفواتير تلقائياً، من أسبوعية إلى سنوية، مع تثبيت وإرسال تلقائيين اختياريين.

GET/api/v1/recurring-invoices

قائمة الجداول

تعيد جداول الفواتير المتكررة. رشّح حسب الحالة أو العميل أو التكرار.

الصلاحياتinvoices:read

معاملات الاستعلام

`page`	integerdefault: 1
`per_page`	integerdefault: 20 (max 100)
`order`	stringdefault: desc `ascdesc`
`status`	string `activepausedcompletedcancelled`
`customer_id`	uuid
`frequency`	string `weeklybiweeklymonthlyquarterlybiannuallyyearly`
`search`	string

cURL

curl https://hisab.ma/api/v1/recurring-invoices \
  -H "Authorization: Bearer hisab_live_***"

GET/api/v1/recurring-invoices/:id

جلب جدول

يعيد جدولاً مع آخر سجل توليد.

الصلاحياتinvoices:read

cURL

curl https://hisab.ma/api/v1/recurring-invoices/{id} \
  -H "Authorization: Bearer hisab_live_***"

POST/api/v1/recurring-invoices

إنشاء جدول

يحدد التكرار وتاريخ البداية وبنود الفواتير القادمة.

الصلاحياتinvoices:write

معاملات الجسم

`customer_id`required	uuid
`frequency`required	string `weeklybiweeklymonthlyquarterlybiannuallyyearly`
`start_date`required	date (YYYY-MM-DD)
`name`	string
`interval_count`	integer (1-12)default: 1
`day_of_month`	integer (1-28)
`day_of_week`	integer (0-6)
`end_date`	date (YYYY-MM-DD)
`max_occurrences`	integer
`auto_finalize`	booleandefault: false
`auto_send`	booleandefault: false
`days_until_due`	integer (0-365)default: 30
`currency`	stringdefault: MAD
`items[].description`required	string
`items[].quantity`required	number
`items[].unit_price`required	number
`items[].tax_rate`	numberdefault: 20

أخطاء خاصةQUOTA_EXCEEDED

cURL

curl https://hisab.ma/api/v1/recurring-invoices \
  -X POST \
  -H "Authorization: Bearer hisab_live_***" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_2b81fe",
    "frequency": "monthly",
    "start_date": "2026-07-01",
    "auto_finalize": true,
    "items": [
      {
        "description": "Monthly retainer",
        "quantity": 1,
        "unit_price": 10400,
        "tax_rate": 20
      }
    ]
  }'

PUT/api/v1/recurring-invoices/:id

تعديل جدول

يضبط جدولاً نشطاً أو متوقفاً. الجداول المكتملة أو الملغاة للقراءة فقط.

الصلاحياتinvoices:write

معاملات الجسم

`frequency`	string `weeklybiweeklymonthlyquarterlybiannuallyyearly`
`end_date`	date (YYYY-MM-DD)
`auto_finalize`	boolean
`auto_send`	boolean
`days_until_due`	integer (0-365)
`items`	array

أخطاء خاصةINVALID_STATE

cURL

curl https://hisab.ma/api/v1/recurring-invoices/{id} \
  -X PUT \
  -H "Authorization: Bearer hisab_live_***" \
  -H "Content-Type: application/json" \
  -d '{
    "auto_send": true
  }'

DELETE/api/v1/recurring-invoices/:id

حذف جدول

يحذف الجدول وسجله. الفواتير المولدة سابقاً لا تتأثر.

الصلاحياتinvoices:write

cURL

curl https://hisab.ma/api/v1/recurring-invoices/{id} \
  -X DELETE \
  -H "Authorization: Bearer hisab_live_***"

POST/api/v1/recurring-invoices/:id/generate

توليد الآن

ينشئ الفاتورة التالية فوراً، مع احترام التثبيت والإرسال التلقائيين.

الصلاحياتinvoices:write

معاملات الجسم

issue_date date (YYYY-MM-DD)default: today

أخطاء خاصةINVALID_STATECUSTOMER_INACTIVE

cURL

curl https://hisab.ma/api/v1/recurring-invoices/{id}/generate \
  -X POST \
  -H "Authorization: Bearer hisab_live_***"

GET/api/v1/recurring-invoices/:id/history

سجل التوليد

يسرد التشغيلات السابقة بأرقام الفواتير المولدة وحالتها.

الصلاحياتinvoices:read

معاملات الاستعلام

limit integerdefault: 20 (max 100)

cURL

curl https://hisab.ma/api/v1/recurring-invoices/{id}/history \
  -H "Authorization: Bearer hisab_live_***"

POST/api/v1/recurring-invoices/:id/pause

إيقاف مؤقت

يوقف التوليد حتى استئناف الجدول.

الصلاحياتinvoices:write

أخطاء خاصةINVALID_STATE

cURL

curl https://hisab.ma/api/v1/recurring-invoices/{id}/pause \
  -X POST \
  -H "Authorization: Bearer hisab_live_***"

POST/api/v1/recurring-invoices/:id/resume

استئناف

يعيد تشغيل جدول متوقف، اختيارياً من تاريخ تشغيل جديد.

الصلاحياتinvoices:write

معاملات الجسم

next_run_date date (YYYY-MM-DD)

أخطاء خاصةINVALID_STATE

cURL

curl https://hisab.ma/api/v1/recurring-invoices/{id}/resume \
  -X POST \
  -H "Authorization: Bearer hisab_live_***"

المؤسسة

ملف مؤسستك وحالة الاشتراك وحصص API.

GET/api/v1/organization

جلب المؤسسة

يعيد المعرفات القانونية وبيانات الاتصال والاشتراك وحصص API.

الصلاحياتorganization:read

cURL

curl https://hisab.ma/api/v1/organization \
  -H "Authorization: Bearer hisab_live_***"

PATCH/api/v1/organization

تعديل المؤسسة

يحدث المعرفات القانونية وبيانات الاتصال وعنوان الفوترة.

الصلاحياتorganization:write

معاملات الجسم

`legal_name`	string
`ice`	string
`rc`	string
`if_number`	string
`vat_number`	string
`phone`	string
`email`	string
`website`	string (URL)
`billing_address`	object

cURL

curl https://hisab.ma/api/v1/organization \
  -X PATCH \
  -H "Authorization: Bearer hisab_live_***" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+212 5 22 00 00 01"
  }'

apiDocsPage.nav.organizations

إدارة المؤسسات للتكاملات متعددة الكيانات. تتطلب هذه النقاط مفتاح حساب (hisab_acct_). بعد الإنشاء، شغّل أي كيان عبر النقاط المعتادة بإرسال الترويسة X-Organization-Id مع نفس مفتاح الحساب. لا يمكن إعادة استخدام رقم ICE مسجل مسبقًا على المنصة، حتى من حساب آخر - فهو يحدد كيانًا قانونيًا واحدًا بالضبط.

GET/api/v1/organizations

قائمة مؤسساتك

تعيد جميع المؤسسات التي يملكها صاحب المفتاح. تُستبعد الكيانات المؤرشفة ما لم يُحدد include_archived=true.

الصلاحياتorganizations:read

معاملات الاستعلام

include_archived booleandefault: false

أخطاء خاصةACCOUNT_KEY_REQUIRED

cURL

curl https://hisab.ma/api/v1/organizations \
  -H "Authorization: Bearer hisab_live_***"

POST/api/v1/organizations

إنشاء مؤسسة

ينشئ كيانًا قانونيًا جديدًا ضمن حسابك. يُطبق حد الكيانات في باقتك؛ تواصل مع الدعم لرفعه.

الصلاحياتorganizations:write

معاملات الجسم

`legal_name`required	string
`ice`	string (15 digits)
`rc`	string
`if_number`	string
`phone`	string
`email`	string
`address_street`	string
`address_city`	string
`address_postal_code`	string

أخطاء خاصةACCOUNT_KEY_REQUIREDENTITY_CAP_REACHED

cURL

curl https://hisab.ma/api/v1/organizations \
  -X POST \
  -H "Authorization: Bearer hisab_live_***" \
  -H "Content-Type: application/json" \
  -d '{
    "legal_name": "Filiale Casablanca SARL",
    "ice": "002345678000071"
  }'

GET/api/v1/organizations/{id}

جلب مؤسسة

تعيد مؤسسة مملوكة واحدة. المعرفات المجهولة أو الأجنبية تعيد 404.

الصلاحياتorganizations:read

أخطاء خاصةACCOUNT_KEY_REQUIRED

cURL

curl https://hisab.ma/api/v1/organizations/{id} \
  -H "Authorization: Bearer hisab_live_***"

POST/api/v1/organizations/{id}/archive

أرشفة مؤسسة

أرشفة مرنة: يُجمّد الكيان في كل مكان (API ولوحة التحكم والمهام المجدولة) دون حذف أي شيء. قابلة للعكس تمامًا.

الصلاحياتorganizations:archive

أخطاء خاصةACCOUNT_KEY_REQUIREDALREADY_ARCHIVED

cURL

curl https://hisab.ma/api/v1/organizations/{id}/archive \
  -X POST \
  -H "Authorization: Bearer hisab_live_***"

POST/api/v1/organizations/{id}/restore

استعادة مؤسسة

تلغي الأرشفة؛ يستأنف الكيان عمله الطبيعي فورًا.

الصلاحياتorganizations:archive

أخطاء خاصةACCOUNT_KEY_REQUIREDNOT_ARCHIVED

cURL

curl https://hisab.ma/api/v1/organizations/{id}/restore \
  -X POST \
  -H "Authorization: Bearer hisab_live_***"