مفاتيح API لكل شركة
ينشئ المالك أو المسؤول مفتاحًا من قسم التكاملات، للقراءة فقط أو للكتابة، مع تاريخ انتهاء. يُرسل في الترويسة Authorization: Bearer. يمكن إلغاؤه في أي وقت، ويتوقف إذا عُطّل منشئه.
المطورون ووكالات الويب
اربطوا موقعكم أو متجركم أو تطبيقكم المهني أو أداة زبونكم بـ SOGESTIO. واجهة REST موثقة، مفاتيح API لكل شركة، روابط Webhook موقعة، ونفس قواعد العمل المطبقة في التطبيق: الترقيم والضريبة على القيمة المضافة والمخزون والمحاسبة تبقى بيد SOGESTIO.
ينشئ المالك أو المسؤول مفتاحًا من قسم التكاملات، للقراءة فقط أو للكتابة، مع تاريخ انتهاء. يُرسل في الترويسة Authorization: Bearer. يمكن إلغاؤه في أي وقت، ويتوقف إذا عُطّل منشئه.
كل مسار موصوف بمخططاته المولدة من قواعد التحقق في الخادم، فلا يمكن أن تختلف الوثائق عن السلوك الفعلي. المبالغ بالسنتيم (أعداد صحيحة)، التواريخ بصيغة ISO، والأخطاء برمز ثابت.
تتوصلون بنداء HTTP عند المصادقة على فاتورة أو تسجيل أداء أو إنشاء زبون. كل إرسال موقع (HMAC-SHA256 مع طابع زمني) ويُعاد تلقائيًا لمدة 72 ساعة تقريبًا عند الفشل.
أرسلوا الترويسة Idempotency-Key مع عمليات الإنشاء: إذا أُعيد نفس النداء (انقطاع الشبكة، محاولة جديدة)، يعيد SOGESTIO نفس النتيجة دون إنشاء نسخة مكررة.
لا يصل كل مفتاح إلا إلى بيانات شركته، وتتبع صلاحياته الدور المختار له. الأرقام القانونية للفواتير يمنحها الخادم عند المصادقة، وليس التكامل.
يحمل كل رفض رمزًا مقروءًا برمجيًا (مثل invalid_input وamount_mismatch وperiod_locked) والحقل المعني عند الإدخال. الترقيم بالصفحات عبر page وpageSize (200 كحد أقصى).
عرض الزبناء، إنشاء فاتورة انطلاقًا من طلب في موقعكم، ثم التحقق من توقيع Webhook في الخادم (PHP).
curl https://sogestio.ma/api/customers?pageSize=50 \
-H "Authorization: Bearer sgk_xxxxxxxxxxxx_votre_secret"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$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 نوعه.