تخطَّ إلى المحتوى
موديول في أنظمة

واجهة API لربط النظام المحاسبي: اربط برنامج المحاسبة بمتجرك وتطبيقاتك عبر REST وويب هوك موقّع

رمز وصول بصلاحيات تحددها، وواجهة REST موثّقة تنشئ الفواتير وتقرأ المخزون والحجوزات، وويب هوك موقّع يبلغ نظامك عند كل حدث.

آخر تحديث: قراءة 6 دقائقكن أول من يقيّم هذه الصفحة
واجهة API لربط النظام المحاسبي: اربط برنامج المحاسبة بمتجرك وتطبيقاتك عبر REST وويب هوك موقّع

باختصار

واجهة API في أنظمة (Anzma) واجهة REST موثّقة بمعيار OpenAPI، تعمل برموز وصول محددة الصلاحيات وويب هوك موقّع بتوقيع HMAC، لربط النظام بالمتاجر والتطبيقات وأنظمة الشركاء دون إعادة إدخال البيانات. تناسب المطورين والمتكاملين وتتاح في الباقتين الشاملة والمؤسسات أو إضافةً مدفوعة على غيرهما.

لمن هذا؟

  • المتاجر الإلكترونية
  • شركات التجارة والجملة
  • شركات البرمجة والمتكاملون
  • الشركات ذات تطبيق خاص
  • فرق تقنية المعلومات
الواجهة
REST بصيغة JSON على الإصدار الأول v1، و68 عملية
المصادقة
رمز Bearer خاص بأنظمة، يظهر مرة واحدة ولا يتجاوز صلاحيات من أنشأه
التوثيق
ملف OpenAPI 3.1 عام وصفحة وثائق داخل التطبيق
الويب هوك
15 حدثًا بتوقيع HMAC-SHA256 وإعادة محاولة تلقائية
حد الطلبات
120 طلبًا في الدقيقة لكل رمز افتراضيًا
الباقات
الشاملة والمؤسسات، أو إضافة مدفوعة على الأساسية والمتقدمة

أبرز ما تحصل عليه

  • رموز بصلاحيات محددة

    تنشئ رمزًا باسم وصلاحيات تختارها، وقائمة عناوين IP مسموحة وتاريخ انتهاء. لا يعطى الرمز أكثر مما يملكه منشئه، وتلغيه بنقرة.

  • وثائق OpenAPI

    مواصفة OpenAPI 3.1 مولدة من الكود نفسه فلا تتقادم، وصفحة وثائق داخل التطبيق بأمثلة وسجل تغييرات.

  • فواتير وسندات وإشعارات

    أنشئ مسودة فاتورة والسيرفر يحسب الأسعار والضرائب والإجماليات، ثم أصدرها أو ألغها، وسجّل سند قبض ووزعه على الفواتير.

  • حجوزات بإتاحة حية

    اقرأ الأوقات الحرة لخدمة في يوم، وأنشئ الحجز بعد إعادة فحص الموعد وحجزه، وألغه وفق سياسة العربون.

  • ويب هوك موقّع

    اشترك في أحداث الفواتير والسندات والحجوزات والمخزون والدفع، فتصل نظامك رسالة موقّعة بالوقت لتتحقق منها.

  • إعادة محاولة وإعادة إرسال

    إذا تعذر الوصول إلى نظامك يعيد النظام المحاولة بفواصل متزايدة، ويحتفظ بسجل تسليم تعيد منه الإرسال بنقرة.

  • تكرار آمن

    ترسل Idempotency-Key مع الطلب، فإذا أعدت المحاولة بعد انقطاع الشبكة تحصل على الاستجابة الأولى بدل فاتورة مكررة.

  • حد طلبات لكل رمز

    يتحكم حد في الدقيقة بكل رمز، ويخفضه الرمز لنفسه ولا يرفعه فوق حد باقتك، ورؤوس الاستجابة تخبر عميلك بما تبقى.

من داخل المنتج

رموز API والويب هوكشاشة توضيحية لإعدادات الرموز والاشتراكات، وليست بيانات حقيقية.
محتويات الصفحة
القسم 01

ماذا يمكن أن تربط عبر واجهة API؟

تربط بها كل ما يتكلم HTTP وJSON: متجرك الإلكتروني، وتطبيق جوال لشركتك، وموقعًا يحجز مواعيد، ولوحة بيانات، ونظام شريك. يبحث عنها الناس بأسماء مثل «ربط ERP بالمتجر الإلكتروني» و«ربط برنامج المحاسبة بالمتجر». وهي تعمل فوق بيانات برنامج المبيعات والفواتير وبرنامج حسابات العملاء وبرنامج حجز مواعيد للعملاء ودفاتر برنامج القيود اليومية ودليل الحسابات، فلا تحتاج مخزنًا ثانيًا للبيانات.

يجب أن تعرف أنها واجهة لمطور يكتب الربط، وليست موصّلات جاهزة. لا توجد إضافة جاهزة لمنصات المتاجر ولا ربط مع Zapier أو غيره، فيكتب فريقك أو متكامل تتعاقد معه الكود الذي يستدعي الواجهة ويستقبل الويب هوك. وإن لم تكن لديك قدرة برمجية فاحجز اجتماعًا ونتبين معك إن كان الربط يستحق ذلك.

موارد الواجهة: ما تقرؤه وما تكتبه
الموردالقراءةالكتابة
جهات الاتصالقائمة وتفاصيلإنشاء وتعديل وحذف ما لا حركة له
المنتجات والمخزونمنتجات وخدمات وأرصدة كل مخزن وقوائم الأسعارقراءة فقط
عروض الأسعارقائمة وتفاصيل بالبنودإنشاء مسودة وإرسال ورابط PDF
الفواتيرقائمة وتفاصيل ورابط صفحة العميلمسودة وتعديلها وحذفها وإصدار وإلغاء
السندات والإشعاراتقائمة وتفاصيلسند قبض وتوزيعه وإلغاؤه، وإشعار دائن أو مدين وترحيله
المشترياتأوامر الشراء وفواتير الشراء ومدفوعات الموردينمسودة أمر شراء وفاتورة شراء
الحجوزاتالإتاحة والحجوزات والخدمات والمواردإنشاء حجز وإلغاؤه
الموظفون والحضورالموظفون وبصمات الحضورتسجيل بصمة كساعة حضور
المحاسبةقيود اليومية وميزان المراجعةقراءة فقط
الويب هوكالأحداث والاشتراكات وسجل التسليمإنشاء الاشتراك وتعديله وإعادة الإرسال
القسم 02

كيف تعمل رموز الوصول وتُحمى؟

يُنشئ مدير الشركة الرمز من إعدادات API باسم وصلاحيات يختارها، وبقائمة عناوين IP مسموحة وتاريخ انتهاء اختيارين. يظهر الرمز الكامل مرة واحدة فقط ويبدأ بـ anz_، ويحفظ النظام بصمته لا الرمز نفسه، فلا يمكن استرجاعه، وإذا ضاع تُنشئ غيره. وهو رمز من إنتاج أنظمة، وليس من Sanctum أو غيره.

والصلاحيات المتاحة للرمز هي صلاحيات المستخدم الذي أنشأه، لا أكثر، وللموديولات المفعّلة في شركتك فقط. فمن لا يملك صلاحية إصدار الفواتير لا يستطيع منحها لرمز. ويُرفض الرمز الملغى أو المنتهي أو القادم من عنوان غير مسموح بخطأ واضح بدل التجاهل، ويسجَّل آخر استخدام وعدد الطلبات اليومية للرمز.

  • رمز لكل تكامل، حتى تلغي المتجر دون أن توقف التطبيق.
  • اختر أضيق صلاحيات تكفي: متجر يقرأ المخزون ويكتب الفواتير لا يحتاج الحسابات.
  • قيّد الرمز بعنوان خادمك إن كان ثابتًا.
  • الحد الافتراضي 120 طلبًا في الدقيقة لكل رمز، ويمكن للرمز خفضه ولا يرفعه فوق حد باقتك.
القسم 03

كيف يبدو الطلب والاستجابة؟

كل طلب يحمل الرأس Authorization: Bearer ويرجع JSON. المبالغ سلاسل عشرية لا أعدادًا عشرية عائمة فلا يضيع كسر، والتواريخ بصيغة ISO 8601، ورسائل الخطأ بالعربية أو الإنجليزية بحسب الرأس Accept-Language. والخطأ بصيغة موحدة برمز نصي، كـ plan_required أو insufficient_scope أو invalid_filter.

القوائم تُرقَّم بمؤشر لا برقم صفحة، فتمرر page[size] من 1 إلى 100 وpage[after] من الاستجابة السابقة. وتقبل المرشحات والترتيب قائمة بيضاء لكل مورد، وأي مرشح خارجها يرجع خطأ 422 بدل أن يُتجاهل بصمت. وعند إنشاء فاتورة ترسل بنودها فيحسب السيرفر الأسعار والضرائب والإجماليات، ولا تثق بحساب العميل.

ويرجع كل رد الرأسين X-Request-Id وX-Api-Version، فتذكر الأول عند مراسلتنا عن طلب بعينه نتتبعه في السجل. وإن طلبت مسارًا لموديول غير مفعّل في شركتك أو لا تغطيه صلاحيات رمزك رجع خطأ 403 يذكر الصلاحية الناقصة، فتعرف ما تضيفه إلى الرمز بدل أن تخمّن.

  1. 1

    أنشئ الرمز

    من إعدادات API، واحفظه في خادمك فقط.

  2. 2

    أنشئ مسودة فاتورة

    POST على invoices مع Idempotency-Key، فيحسب السيرفر المجاميع.

  3. 3

    أصدر الفاتورة

    POST على invoices/{id}/issue فتُرحَّل إلى الدفاتر وتُقفل.

  4. 4

    احصل على رابط العميل

    GET على pdf-link لرابط صفحة الفاتورة وملف PDF.

  5. 5

    استقبل الدفع

    اشترك في invoice.paid أو payment.online_succeeded فتصلك رسالة عند السداد.

القسم 04

ماذا يحدث إذا انقطع الاتصال في منتصف الطلب؟

ترسل مع كل POST الرأس Idempotency-Key بقيمة فريدة من عندك. يحفظ النظام أول استجابة ناجحة لهذا المفتاح أربعًا وعشرين ساعة، وإذا أعدت الطلب بالمفتاح نفسه تحصل على الاستجابة نفسها وعلى الرأس Idempotent-Replayed، دون إنشاء فاتورة ثانية. وإن وصل طلب مكرر والأول لم ينتهِ بعد يرد خطأ 409 مع الرأس Retry-After. وبصمات الحضور تتجاهل المكرر بذاتها.

القسم 05

ما هي أحداث الويب هوك وكيف أتحقق من توقيعها؟

الويب هوك رسالة POST ترسلها أنظمة إلى عنوان تحدده عندما يقع حدث، بدل أن يسأل نظامك كل دقيقة. تنشئ اشتراكًا باسم وعنوان وأحداث، فيعطيك سرّ التوقيع مرة واحدة، ويمكنك لاحقًا تدويره أو إرسال حدث تجريبي. ويجب أن يكون العنوان http أو https ويحل إلى عناوين عامة، فلا يقبل النظام عنوانًا يشير إلى شبكة داخلية. ولا تُنشأ الرسالة إلا بعد اكتمال العملية في قاعدة البيانات، فلا تصلك فاتورة ثم تُلغى العملية.

ويحمل كل طلب رؤوسًا: X-Anzma-Event وX-Anzma-Event-Id وX-Anzma-Delivery وX-Anzma-Timestamp وX-Anzma-Signature. والتوقيع هو sha256= متبوعًا بنتيجة HMAC-SHA256 على النص «الوقت ثم نقطة ثم جسم الطلب كما وصل» بسرّ الاشتراك. فتحسبه عندك وتقارنه مقارنة ثابتة الزمن، وترفض الرسالة إن تجاوز فارق الوقت خمس دقائق، فلا يمكن لمن التقط رسالة قديمة أن يعيد إرسالها. واحفظ معرّف الحدث لتتجاهل ما سبق وعالجته.

أحداث الويب هوك المتاحة
الحدثمتى يقعالموديول
invoice.issued / invoice.paid / invoice.cancelledإصدار فاتورة، وسدادها كاملة، وإلغاؤهاالمبيعات
credit_note.postedترحيل إشعار دائن أو مدينالمبيعات
receipt.createdإنشاء سند قبضالمبيعات
quotation.acceptedقبول العميل عرض سعرالمبيعات
purchase_bill.issuedإصدار فاتورة مشترياتالمشتريات
booking.created / cancelled / completedإنشاء الحجز وإلغاؤه واكتمالهالحجوزات
stock.lowوصول صنف إلى حد إعادة الطلبالمخازن
payment.online_succeededنجاح دفع إلكترونيبوابات الدفع
employee.created / contact.createdإضافة موظف أو جهة اتصالالموظفون وجهات الاتصال
membership.renewedتجديد اشتراك عضويةالعضويات
القسم 06

ماذا يحدث إذا تعذر الوصول إلى نظامي؟

يعتبر النظام التسليم ناجحًا إذا ردّ خادمك برمز 2xx، وإلا يعيد المحاولة بعد دقيقة ثم خمس دقائق ثم نصف ساعة ثم ساعتين ثم ست ساعات، فتصل محاولات التسليم الواحد إلى ست. وإذا تتابعت الإخفاقات على اشتراك بعدد يحدده مدير الشركة، وهو عشرة افتراضيًا، أوقفه النظام وأرسل إشعارًا، وتُعلَّم التسليمات المعلقة فاشلة. فتصلح العنوان وتعيد تفعيل الاشتراك.

ولكل اشتراك سجل تسليم يعرض رمز الاستجابة والزمن ومقتطفًا من الرد وسبب الخطأ، ومنه تعيد إرسال أي تسليم بالمعرّف نفسه. ويُحذف السجل القديم بعد ثلاثين يومًا.

القسم 07

كيف يُربط متجر إلكتروني بأنظمة في الواقع؟

مثال توضيحي لمتجر يبيع عبر موقعه الخاص ويدير حساباته في أنظمة. ينشئ مطور المتجر رمزًا بصلاحيات قراءة المخزون وإنشاء الفواتير والسندات فقط. عند كل طلب مدفوع يستدعي موقع المتجر إنشاء مسودة فاتورة بمفتاح تكرار هو رقم الطلب، ثم يصدرها، ثم يسجّل سند القبض ويوزعه عليها، فيرى المحاسب الطلب في الدفاتر دون أن يكتبه أحد.

وفي الاتجاه المعاكس يقرأ الموقع أرصدة المخزون بالمخزن من نقطة stock-levels ليعرض المتاح، ويشترك في الحدث stock.low ليخفي الصنف حين يبلغ حد إعادة الطلب. ويشترك في invoice.paid ليغيّر حالة الطلب في المتجر حين يسدد العميل من رابط الفاتورة. هكذا يبقى سجل البيع واحدًا في أنظمة، ويبقى المتجر واجهة عرض وطلب لا مصدرًا ثانيًا للحقيقة.

ولا يغني هذا عن اختبار الربط على شركة تجريبية قبل التشغيل. يتحقق فريقك من التوقيع ومن حالات الفشل وإعادة المحاولة، ثم تنتقل إلى الشركة الفعلية برمز جديد.

القسم 08

أين التوثيق، وهل الواجهة متاحة في كل الباقات؟

تجد مواصفة OpenAPI 3.1 على المسار /api/v1/openapi.json في نطاق شركتك، وتفتحها دون رمز، وتستوردها في أي أداة تدعم المعيار الذي تصونه مبادرة OpenAPI. وفي التطبيق صفحة وثائق المطورين بالعربية والإنجليزية فيها المصادقة وأمثلة curl وسجل التغييرات وكيفية التحقق من التوقيع.

الواجهة والويب هوك ميزة في الباقتين الشاملة والمؤسسات. وعلى الأساسية والمتقدمة تُضاف بإضافة مدفوعة، واطلع على السعر في صفحة الأسعار. وإذا لم تشمل باقتك الواجهة يرد الطلب بخطأ 402 plan_required. وما لم يُنفَّذ بعد: لا OAuth ولا رموز تجريبية ببيئة اختبار منفصلة، ولا ETag للتعديل المشروط. وللتجربة استخدم شركة اختبار منفصلة.

القسم 09

من يستفيد من الواجهة؟

يستفيد منها كل من يبيع أو يحجز خارج شاشة النظام. برنامج إدارة المتجر الإلكتروني ينزل طلبات المتجر فواتير ويقرأ المخزون، وبرنامج إدارة تجارة الجملة يربط بوابة طلبات تجار الجملة، وبرنامج إدارة شركة خدمات تقنية يبني تكاملاته لعملائه. ولا يفعّل أي قالب نشاط الواجهة تلقائيًا لأنها ميزة باقة، فتطلبها عند الحاجة.

وللمقارنة العامة بين أنظمة إدارة الأعمال راجع دليل اختيار نظام ERP، ولعرض عملي على سيناريو الربط عندك احجز اجتماعًا أونلاين.

الأسئلة الشائعة

هل توجد واجهة API في أنظمة؟

نعم، واجهة REST بصيغة JSON على الإصدار الأول، فيها 68 عملية تغطي جهات الاتصال والمنتجات والمخزون وعروض الأسعار والفواتير والسندات والمشتريات والحجوزات والموظفين والمحاسبة والويب هوك، وموثقة بمعيار OpenAPI 3.1.

ما الذي يمكن ربطه؟

أي نظام يستدعي HTTP: متجر إلكتروني أو تطبيق أو موقع حجز أو لوحة بيانات. تنشئ الفواتير وعروض الأسعار والسندات والحجوزات وتقرأ المخزون والقيود. ولا توجد موصّلات جاهزة لمنصات المتاجر، فيُكتب الربط.

كيف تُحمى رموز الوصول؟

يظهر الرمز مرة واحدة ويحفظ النظام بصمته فقط، وصلاحياته لا تتجاوز صلاحيات منشئه، ويمكن تقييده بعناوين IP وتاريخ انتهاء، وتلغيه في أي لحظة، ولكل رمز حد طلبات في الدقيقة.

كيف أتحقق من توقيع الويب هوك؟

احسب HMAC-SHA256 على النص الوقت ثم نقطة ثم جسم الطلب كما وصل، بسرّ الاشتراك، وقارنه بالقيمة بعد sha256= في الرأس X-Anzma-Signature مقارنة ثابتة الزمن. ارفض الرسالة إن زاد فارق الوقت عن خمس دقائق.

أين التوثيق؟

مواصفة OpenAPI 3.1 العامة على المسار /api/v1/openapi.json في نطاق شركتك تفتحها دون رمز وتستوردها في أدوات المطورين، وصفحة وثائق المطورين داخل التطبيق بالعربية والإنجليزية فيها أمثلة curl وسجل التغييرات وطريقة التحقق من التوقيع.

هل الربط متاح في كل الباقات؟

الواجهة والويب هوك ميزة ضمن الباقتين الشاملة والمؤسسات. على الباقتين الأساسية والمتقدمة تُضاف بإضافة مدفوعة تفعّلها لشركتك، وبدونها يرد أي طلب بخطأ 402 plan_required. وتفاصيل السعر والباقات في صفحة الأسعار.

ماذا لو أعدت إرسال طلب إنشاء فاتورة؟

أرسل Idempotency-Key فريدًا مع كل طلب POST، كرقم الطلب في متجرك. إذا أعدت الطلب بالمفتاح نفسه خلال أربع وعشرين ساعة حصلت على الاستجابة الأولى نفسها دون فاتورة مكررة، ويظهر في الاستجابة الرأس Idempotent-Replayed ليعرف كودك أنها إعادة.

ماذا يحدث إذا فشل التسليم؟

يعيد النظام المحاولة بعد دقيقة ثم خمس دقائق ثم نصف ساعة ثم ساعتين ثم ست ساعات، ثم يعلّم التسليم فاشلًا. وتوقف الإخفاقات المتتالية الاشتراك بعد حد يحدده المدير ويصلك إشعار، وتعيد الإرسال من سجل التسليم بالمعرّف نفسه.

هل يدعم OAuth أو بيئة اختبار؟

لا، المصادقة اليوم برمز Bearer خاص بأنظمة تنشئه من إعدادات الشركة، ولا يوجد OAuth ولا رموز تجريبية ببيئة اختبار منفصلة ولا ETag للتعديل المشروط. ننصح بإنشاء شركة اختبار منفصلة للتطوير والتجربة قبل ربط الشركة الفعلية.

هل يوجد ربط مجاني؟

الواجهة ميزة مدفوعة: ضمن الباقتين الشاملة والمؤسسات، أو بإضافة على الأساسية والمتقدمة. والربط نفسه يحتاج مطورًا يكتب الكود، وتصدير التقارير إلى Excel بديل بلا برمجة للحالات البسيطة. احجز اجتماعًا مجانيًا أونلاين نحدد معك الأنسب لحالتك.

قيّم هذه الصفحة

هل وجدت المعلومات مفيدة؟ تقييمك يساعد غيرك.

لا توجد تقييمات بعد.

شارك الصفحةWhatsAppXLinkedInFacebook

موديولات مرتبطة

الأسعار

باقات واضحة تنمو معك

تقريبًا كل الموديولات في كل الباقات، والفرق في الحدود.

أساسي

للأنشطة الصغيرة التي تبدأ رحلتها

450ج.م / شهر

يُحاسب 5,400 ج.م سنويًا

وفّر 24%

تشمل الباقة:

  • 3 مستخدمين وفرع واحد
  • 150 فاتورة شهريًا
  • كل الموديولات المناسبة لنشاطك
  • 5GB مساحة تخزين
احجز اجتماعًا
الأكثر طلبًا

متقدم

للأنشطة النامية بفروع ومخازن متعددة

790ج.م / شهر

يُحاسب 9,480 ج.م سنويًا

وفّر 20%

كل ما في أساسي بالإضافة إلى:

  • 7 مستخدمين وفرعان و3 مخازن
  • 750 فاتورة شهريًا
  • جهازا نقطة بيع
  • 15GB مساحة تخزين
احجز اجتماعًا

شامل

كل شيء: فواتير غير محدودة والتصنيع والدومين الخاص وAPI

1,590ج.م / شهر

يُحاسب 19,080 ج.م سنويًا

وفّر 20%

كل ما في متقدم بالإضافة إلى:

  • 15 مستخدمًا و3 فروع و5 مخازن
  • فواتير غير محدودة
  • التصنيع والدومين الخاص وواجهة API
  • 30GB مساحة تخزين
احجز اجتماعًا

مؤسسات

للمؤسسات: حدود مفتوحة وخادم مخصص واتفاقية خدمة

حسب الطلب

كل ما في شامل بالإضافة إلى:

  • مستخدمون وفروع ومخازن بلا حدود
  • خادم مخصص واتفاقية مستوى خدمة
  • مساحة تخزين حسب الطلب
  • مدير حساب وتهيئة مخصصة
تواصل معنا