سكب للمطوّرين

أنت لا تستدعي وظائف سكب — أنت تصف ما حدث عندك في مغلّف، وسكب يقرر كيف يصبح مستندًا صحيحًا في الدفاتر.

• الوارد — نظامك يرسل مغلّفًا موقّعًا إلى عنوان ربطك. سكب يتحقق منه ووصفة الربط تحوّله إلى مستند ينتظر مراجعة المحاسب. لا «نقطة نهاية» لكل مستند — عنوان واحد ونوع رسالة داخل المغلّف.
• الصادر — سكب يدفع الأحداث الموقّعة إلى عناوينك (فاتورة صدرت، سند حُصّل…). أنت تشترك في الأحداث وتتحقق من توقيع كل تسليم — لا سحب دوريًا.

عنوان ربطك ومفتاحه وسر توقيعه داخل المنتج: الإعدادات ← الربط.

كل إرسال هو مغلّف وحمولة. المغلّف يحمل هوية الرسالة وتوجيهها — والحمولة بياناتك أنت بأي شكل تتفق عليه وصفتك:

POST https://api.sakb.sa/api/public/v1/inbound/custom
Authorization: Bearer sakb_gk_…
X-Sakb-Signature: sha256=…
X-Sakb-Timestamp: 2026-08-11T09:30:00Z

{
  "envelope": {
    "messageType": "sales.invoice.received",
    "version": "1.0",
    "idempotencyKey": "inv-10452-delivery-1",
    "occurredAt": "2026-08-11T09:30:00Z",
    "source": { "channel": "custom", "externalId": "INV-10452" }
  },
  "payload": { }
}

• messageType — «تيار.حدث» — الجزء الأخير هو الحدث والباقي التيار؛ وصفتك تُطابق عليهما.
• idempotencyKey — فريد لكل إرسال: الإعادة بنفس المفتاح والمحتوى تُجاب بنفس النتيجة ولا تُنشئ سجلًا ثانيًا.
• source.externalId — رقم مستندك عندك — به يعرف سكب المستند نفسه إذا وصل مرة أخرى.
• payload — بياناتك — الوصفة داخل سكب تحوّلها إلى حقول المستند.

كل طلب وارد يوقَّع بسر توقيع ربطك ويُحمل في ترويستي X-Sakb-Signature وX-Sakb-Timestamp (نافذة ±5 دقائق):

base      = rawBodyUtf8 + "\n" + X-Sakb-Timestamp
signature = "sha256=" + hex(HMAC-SHA256(base, signingSecret))

ما لا يُوقَّع أو أُسيء توقيعه أو تقادم يُرفض — لا مسار بلا تحقق.

تُستطلع النتيجة من GET /api/public/v1/messages/:id:

• PROCESSED — صار مستندًا — معرّفاته في الجواب.
• NEEDS_USER — وصل وتوقف لمراجعة المحاسب داخل سكب — ليس خطأك بالضرورة.
• REJECTED — رُفض — السبب في سجل الرسالة.

اشترك بعنوانك وأحداثك، وتحقق من توقيع كل تسليم بسر الاشتراك.

عند تدوير السر يبقى القديم صالحًا 7 أيام — سكب يوقّع بالاثنين خلالها.

أرسل المغلّف نفسه بعلم "sandbox": true — يمرّ بكل خطوات المعالجة ويتوقف قبل الكتابة، فترى النتيجة معاينةً دون أثر في الدفاتر.