محتويات الصفحة
ماذا يمكن أن تربط عبر واجهة API؟
تربط بها كل ما يتكلم HTTP وJSON: متجرك الإلكتروني، وتطبيق جوال لشركتك، وموقعًا يحجز مواعيد، ولوحة بيانات، ونظام شريك. يبحث عنها الناس بأسماء مثل «ربط ERP بالمتجر الإلكتروني» و«ربط برنامج المحاسبة بالمتجر». وهي تعمل فوق بيانات برنامج المبيعات والفواتير وبرنامج حسابات العملاء وبرنامج حجز مواعيد للعملاء ودفاتر برنامج القيود اليومية ودليل الحسابات، فلا تحتاج مخزنًا ثانيًا للبيانات.
يجب أن تعرف أنها واجهة لمطور يكتب الربط، وليست موصّلات جاهزة. لا توجد إضافة جاهزة لمنصات المتاجر ولا ربط مع Zapier أو غيره، فيكتب فريقك أو متكامل تتعاقد معه الكود الذي يستدعي الواجهة ويستقبل الويب هوك. وإن لم تكن لديك قدرة برمجية فاحجز اجتماعًا ونتبين معك إن كان الربط يستحق ذلك.
| المورد | القراءة | الكتابة |
|---|---|---|
| جهات الاتصال | قائمة وتفاصيل | إنشاء وتعديل وحذف ما لا حركة له |
| المنتجات والمخزون | منتجات وخدمات وأرصدة كل مخزن وقوائم الأسعار | قراءة فقط |
| عروض الأسعار | قائمة وتفاصيل بالبنود | إنشاء مسودة وإرسال ورابط PDF |
| الفواتير | قائمة وتفاصيل ورابط صفحة العميل | مسودة وتعديلها وحذفها وإصدار وإلغاء |
| السندات والإشعارات | قائمة وتفاصيل | سند قبض وتوزيعه وإلغاؤه، وإشعار دائن أو مدين وترحيله |
| المشتريات | أوامر الشراء وفواتير الشراء ومدفوعات الموردين | مسودة أمر شراء وفاتورة شراء |
| الحجوزات | الإتاحة والحجوزات والخدمات والموارد | إنشاء حجز وإلغاؤه |
| الموظفون والحضور | الموظفون وبصمات الحضور | تسجيل بصمة كساعة حضور |
| المحاسبة | قيود اليومية وميزان المراجعة | قراءة فقط |
| الويب هوك | الأحداث والاشتراكات وسجل التسليم | إنشاء الاشتراك وتعديله وإعادة الإرسال |
كيف تعمل رموز الوصول وتُحمى؟
يُنشئ مدير الشركة الرمز من إعدادات API باسم وصلاحيات يختارها، وبقائمة عناوين IP مسموحة وتاريخ انتهاء اختيارين. يظهر الرمز الكامل مرة واحدة فقط ويبدأ بـ anz_، ويحفظ النظام بصمته لا الرمز نفسه، فلا يمكن استرجاعه، وإذا ضاع تُنشئ غيره. وهو رمز من إنتاج أنظمة، وليس من Sanctum أو غيره.
والصلاحيات المتاحة للرمز هي صلاحيات المستخدم الذي أنشأه، لا أكثر، وللموديولات المفعّلة في شركتك فقط. فمن لا يملك صلاحية إصدار الفواتير لا يستطيع منحها لرمز. ويُرفض الرمز الملغى أو المنتهي أو القادم من عنوان غير مسموح بخطأ واضح بدل التجاهل، ويسجَّل آخر استخدام وعدد الطلبات اليومية للرمز.
- رمز لكل تكامل، حتى تلغي المتجر دون أن توقف التطبيق.
- اختر أضيق صلاحيات تكفي: متجر يقرأ المخزون ويكتب الفواتير لا يحتاج الحسابات.
- قيّد الرمز بعنوان خادمك إن كان ثابتًا.
- الحد الافتراضي 120 طلبًا في الدقيقة لكل رمز، ويمكن للرمز خفضه ولا يرفعه فوق حد باقتك.
كيف يبدو الطلب والاستجابة؟
كل طلب يحمل الرأس 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
أنشئ الرمز
من إعدادات API، واحفظه في خادمك فقط.
- 2
أنشئ مسودة فاتورة
POST على invoices مع Idempotency-Key، فيحسب السيرفر المجاميع.
- 3
أصدر الفاتورة
POST على invoices/{id}/issue فتُرحَّل إلى الدفاتر وتُقفل.
- 4
احصل على رابط العميل
GET على pdf-link لرابط صفحة الفاتورة وملف PDF.
- 5
استقبل الدفع
اشترك في invoice.paid أو payment.online_succeeded فتصلك رسالة عند السداد.
ماذا يحدث إذا انقطع الاتصال في منتصف الطلب؟
ترسل مع كل POST الرأس Idempotency-Key بقيمة فريدة من عندك. يحفظ النظام أول استجابة ناجحة لهذا المفتاح أربعًا وعشرين ساعة، وإذا أعدت الطلب بالمفتاح نفسه تحصل على الاستجابة نفسها وعلى الرأس Idempotent-Replayed، دون إنشاء فاتورة ثانية. وإن وصل طلب مكرر والأول لم ينتهِ بعد يرد خطأ 409 مع الرأس Retry-After. وبصمات الحضور تتجاهل المكرر بذاتها.
ما هي أحداث الويب هوك وكيف أتحقق من توقيعها؟
الويب هوك رسالة 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 | تجديد اشتراك عضوية | العضويات |
ماذا يحدث إذا تعذر الوصول إلى نظامي؟
يعتبر النظام التسليم ناجحًا إذا ردّ خادمك برمز 2xx، وإلا يعيد المحاولة بعد دقيقة ثم خمس دقائق ثم نصف ساعة ثم ساعتين ثم ست ساعات، فتصل محاولات التسليم الواحد إلى ست. وإذا تتابعت الإخفاقات على اشتراك بعدد يحدده مدير الشركة، وهو عشرة افتراضيًا، أوقفه النظام وأرسل إشعارًا، وتُعلَّم التسليمات المعلقة فاشلة. فتصلح العنوان وتعيد تفعيل الاشتراك.
ولكل اشتراك سجل تسليم يعرض رمز الاستجابة والزمن ومقتطفًا من الرد وسبب الخطأ، ومنه تعيد إرسال أي تسليم بالمعرّف نفسه. ويُحذف السجل القديم بعد ثلاثين يومًا.
كيف يُربط متجر إلكتروني بأنظمة في الواقع؟
مثال توضيحي لمتجر يبيع عبر موقعه الخاص ويدير حساباته في أنظمة. ينشئ مطور المتجر رمزًا بصلاحيات قراءة المخزون وإنشاء الفواتير والسندات فقط. عند كل طلب مدفوع يستدعي موقع المتجر إنشاء مسودة فاتورة بمفتاح تكرار هو رقم الطلب، ثم يصدرها، ثم يسجّل سند القبض ويوزعه عليها، فيرى المحاسب الطلب في الدفاتر دون أن يكتبه أحد.
وفي الاتجاه المعاكس يقرأ الموقع أرصدة المخزون بالمخزن من نقطة stock-levels ليعرض المتاح، ويشترك في الحدث stock.low ليخفي الصنف حين يبلغ حد إعادة الطلب. ويشترك في invoice.paid ليغيّر حالة الطلب في المتجر حين يسدد العميل من رابط الفاتورة. هكذا يبقى سجل البيع واحدًا في أنظمة، ويبقى المتجر واجهة عرض وطلب لا مصدرًا ثانيًا للحقيقة.
ولا يغني هذا عن اختبار الربط على شركة تجريبية قبل التشغيل. يتحقق فريقك من التوقيع ومن حالات الفشل وإعادة المحاولة، ثم تنتقل إلى الشركة الفعلية برمز جديد.
أين التوثيق، وهل الواجهة متاحة في كل الباقات؟
تجد مواصفة OpenAPI 3.1 على المسار /api/v1/openapi.json في نطاق شركتك، وتفتحها دون رمز، وتستوردها في أي أداة تدعم المعيار الذي تصونه مبادرة OpenAPI. وفي التطبيق صفحة وثائق المطورين بالعربية والإنجليزية فيها المصادقة وأمثلة curl وسجل التغييرات وكيفية التحقق من التوقيع.
الواجهة والويب هوك ميزة في الباقتين الشاملة والمؤسسات. وعلى الأساسية والمتقدمة تُضاف بإضافة مدفوعة، واطلع على السعر في صفحة الأسعار. وإذا لم تشمل باقتك الواجهة يرد الطلب بخطأ 402 plan_required. وما لم يُنفَّذ بعد: لا OAuth ولا رموز تجريبية ببيئة اختبار منفصلة، ولا ETag للتعديل المشروط. وللتجربة استخدم شركة اختبار منفصلة.
من يستفيد من الواجهة؟
يستفيد منها كل من يبيع أو يحجز خارج شاشة النظام. برنامج إدارة المتجر الإلكتروني ينزل طلبات المتجر فواتير ويقرأ المخزون، وبرنامج إدارة تجارة الجملة يربط بوابة طلبات تجار الجملة، وبرنامج إدارة شركة خدمات تقنية يبني تكاملاته لعملائه. ولا يفعّل أي قالب نشاط الواجهة تلقائيًا لأنها ميزة باقة، فتطلبها عند الحاجة.
وللمقارنة العامة بين أنظمة إدارة الأعمال راجع دليل اختيار نظام 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 بديل بلا برمجة للحالات البسيطة. احجز اجتماعًا مجانيًا أونلاين نحدد معك الأنسب لحالتك.
قيّم هذه الصفحة
هل وجدت المعلومات مفيدة؟ تقييمك يساعد غيرك.
لا توجد تقييمات بعد.


