المطورون ووكالات الويب

واجهة برمجة SOGESTIO

اربطوا موقعكم أو متجركم أو تطبيقكم المهني أو أداة زبونكم بـ SOGESTIO. واجهة REST موثقة، مفاتيح API لكل شركة، روابط Webhook موقعة، ونفس قواعد العمل المطبقة في التطبيق: الترقيم والضريبة على القيمة المضافة والمخزون والمحاسبة تبقى بيد SOGESTIO.

مفاتيح API لكل شركة

ينشئ المالك أو المسؤول مفتاحًا من قسم التكاملات، للقراءة فقط أو للكتابة، مع تاريخ انتهاء. يُرسل في الترويسة Authorization: Bearer. يمكن إلغاؤه في أي وقت، ويتوقف إذا عُطّل منشئه.

مرجع OpenAPI 3.1

كل مسار موصوف بمخططاته المولدة من قواعد التحقق في الخادم، فلا يمكن أن تختلف الوثائق عن السلوك الفعلي. المبالغ بالسنتيم (أعداد صحيحة)، التواريخ بصيغة ISO، والأخطاء برمز ثابت.

روابط Webhook موقعة

تتوصلون بنداء HTTP عند المصادقة على فاتورة أو تسجيل أداء أو إنشاء زبون. كل إرسال موقع (HMAC-SHA256 مع طابع زمني) ويُعاد تلقائيًا لمدة 72 ساعة تقريبًا عند الفشل.

عدم التكرار

أرسلوا الترويسة Idempotency-Key مع عمليات الإنشاء: إذا أُعيد نفس النداء (انقطاع الشبكة، محاولة جديدة)، يعيد SOGESTIO نفس النتيجة دون إنشاء نسخة مكررة.

العزل والصلاحيات

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

أخطاء واضحة

يحمل كل رفض رمزًا مقروءًا برمجيًا (مثل invalid_input وamount_mismatch وperiod_locked) والحقل المعني عند الإدخال. الترقيم بالصفحات عبر page وpageSize (200 كحد أقصى).

أمثلة

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

عرض الزبناء (curl)
curl https://sogestio.ma/api/customers?pageSize=50 \
  -H "Authorization: Bearer sgk_xxxxxxxxxxxx_votre_secret"
إنشاء فاتورة مسودة (Node.js)
const res = await fetch("https://sogestio.ma/api/invoices", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SOGESTIO_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": order.id, // safe to retry: never creates a duplicate
  },
  body: JSON.stringify({
    kind: "invoice",
    customerId: "c_123",
    customerName: "Supérette Al Baraka",
    issueDate: "2026-10-07",
    currency: "MAD",
    lines: [{ label: "Terminal de caisse", quantity: 1, unitPriceHt: 490000, vatRate: 20 }],
  }),
});
const invoice = await res.json(); // amounts in centimes: 490000 = 4 900,00 DH
التحقق من Webhook (PHP)
$payload = file_get_contents('php://input');
$header  = $_SERVER['HTTP_X_SOGESTIO_SIGNATURE']; // "t=1760000000,v1=ab12…"
parse_str(str_replace(',', '&', $header), $sig);
$expected = hash_hmac('sha256', $sig['t'] . '.' . $payload, getenv('SOGESTIO_WEBHOOK_SECRET'));
if (!hash_equals($expected, $sig['v1']) || abs(time() - (int)$sig['t']) > 300) {
  http_response_code(400); exit;
}
$event = json_decode($payload, true); // $_SERVER['HTTP_X_SOGESTIO_EVENT'] = "invoice.validated"

الأحداث المتاحة

اربطوا عنوان HTTPS بحدث أو أكثر من قسم التكاملات. يحتوي الطلب على الكائن المعني، وتحدد الترويسة X-Sogestio-Event نوعه.

  • invoice.validated
  • creditNote.validated
  • quote.validated
  • order.validated
  • delivery.validated
  • purchase.validated
  • payment.created
  • payment.deleted
  • customer.created

أسئلة شائعة

هل الواجهة البرمجية مؤداة؟
لا. الواجهة البرمجية وروابط Webhook مشمولة في جميع الباقات (Starter وPro والمجموعة) دون أي إضافة. ولا يمكن الوصول عبرها إلا إلى وظائف باقتكم.
كيف أختبر دون مخاطرة؟
أنشئوا حسابًا تجريبيًا مجانيًا لمدة 14 يومًا: إنها شركة منفصلة يمكنكم فيها إنشاء مفاتيح وإرسال فواتير تجريبية وربط روابط Webhook. وتبقى الفواتير المصادق عليها مرقمة كما في الإنتاج.
هل هناك حد لعدد النداءات؟
نعم، حد للمعدل يحمي الخدمة؛ عند تجاوزه تجيب الواجهة بالرمز 429 ويكفي إعادة المحاولة بعد قليل. للأحجام الكبيرة (المزامنة الأولى) اجمعوا النداءات واستعملوا الاستيراد عبر Excel/CSV.
ما الفرق بين القراءة والكتابة؟
مفتاح القراءة يسمح بالاطلاع فقط. مفتاح الكتابة يسمح بالإنشاء والتعديل في حدود الدور المختار له (مثل محاسب أو مسؤول تجاري).
أنا وكالة ويب: كيف أدمج SOGESTIO لزبون؟
ينشئ زبونكم مفتاح API في شركته ويسلمه لكم. تربطون موقعه أو متجره بالواجهة، وتتوصلون عند الحاجة بأحداثه عبر Webhook. ويبقى SOGESTIO قلب تسييره: الفوترة القانونية والضريبة والمخزون والمحاسبة.
هل يحتاج متجر Shopify أو WooCommerce إلى الواجهة البرمجية؟
لا: يستورد SOGESTIO تلقائيًا طلبات Shopify وWooCommerce. الواجهة البرمجية مخصصة لما عدا ذلك: المواقع الخاصة، التطبيقات المهنية، أدوات التقارير.