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

الـ Webhooks وOpenAPI: إشعار الأنظمة الأخرى بالأحداث

عند وقوع حدث في HNR (ترحيل فاتورة، حذف طلب، انطلاق شحنة…) يرسل الـ Webhook إشعار HTTP موقّعًا إلى العنوان الذي تحدده. يحمل الإشعار ملخص المستند ورابط الـ API فقط، ويقرأ المستقبِل السجل الكامل من الـ API بجلسته الخاصة. تصف هذه الصفحة اتفاقًا وليست مخططًا رسميًا.

إنشاء اشتراك

الإعدادات › التكامل والـ Webhooks متاح لمسؤول النظام فقط. يحتاج الاشتراك الجديد إلى اسم وعنوان وجهة وحدث واحد على الأقل. يجب أن يبدأ العنوان بـ https، ولا تُقبل وجهة على الشبكة المحلية أو على هذا الحاسوب (مثل 192.168.x.x أو localhost) إلا إذا حُدّد مربع موافقة المسؤول. لا يمكن إنشاء اشتراك ثانٍ للعنوان نفسه.

مرشّحات اختيارية: حسابات أو مستودعات معينة فقط. إذا عُيّن مرشّح ولم يكن في المستند ذلك الحقل فلا يُرسل الإشعار. لا يُرسل مبلغ المستند وعملته إلا إذا حُدّد «إضافة مبلغ المستند وعملته إلى الإشعار».

عند الحفظ يُعرض سر التوقيع (يبدأ بـ whsec_) مرة واحدة فقط؛ احفظه في النظام المستقبِل. يُخزَّن مشفرًا على الخادم ولا يمكن قراءته مجددًا. إن فقدته فأنشئ سرًا جديدًا عبر «تجديد السر»؛ ولن تُقبل التواقيع المصنوعة بالسر القديم.

الأحداث

الفاتورة والطلب وعرض السعر (fatura، siparis، teklif): yazildi وdegisti وsilindi · إذن التسليم (irsaliye): yazildi وsilindi · الإيصال (makbuz): yazildi وdegisti وsilindi · stok.hareket (تحويل بين المستودعات أُرسل أو استُلم أو فُقد؛ اعتماد الجرد) · sevkiyat.durum (الانطلاق، التسليم في محطة، تصحيح إثبات التسليم) · onay.karar · dof.acildi · servis.bilet (فُتحت، الحالة) · uretim.teyit (تأكيد أو إلغاء). رمز الحدث في الترويسة X-HNR-Event وفي الحقل olay من النص؛ وزر الاختبار يرسل test.ping.

محتوى الإشعار

POST https://alici.ornek.com/hnr
Content-Type: application/json; charset=utf-8
User-Agent: HNR-Webhook/1
X-HNR-Event: fatura.yazildi
X-HNR-Delivery: wh_2
X-HNR-Timestamp: 1791559000
X-HNR-Signature: t=1791559000,v1=5f1c…(64 hex)

{"surum":1,"id":"ev_3fa1…","olay":"fatura.yazildi","firma":"ornek","zaman":"2026-10-09T15:15:00.000Z",
 "belge":{"tur":"fatura","sira":9107041,"no":"SF2026000126","cari":"C001","depo":"MERKEZ","tarih":"2026-10-09","tutar":360},
 "baglanti":"/api/fatura/9107041"}

belge.no هو رقم المستند النهائي، ويُقرأ السجل الكامل من الـ API عبر baglanti. لا يأتي tutar وdoviz إلا في الاشتراكات التي تشمل المبلغ، ومن دون doviz يكون المبلغ بالعملة المحلية للشركة. في حدث الحذف يُقرأ الملخص قبل حذف المستند. surum هو إصدار صيغة الحمولة: قد تُضاف حقول جديدة ولا تتغير الحقول الموجودة.

التحقق من التوقيع

يحمل كل طلب الترويسات X-HNR-Event وX-HNR-Delivery (معرّف التسليم) وX-HNR-Timestamp وX-HNR-Signature: t=…,v1=…. v1 هو HMAC-SHA256 (ست عشري) للنص t + "." + النص الخام بسر التوقيع. على المستقبِل التحقق من التوقيع بمقارنة ثابتة الزمن، ورفض الطوابع الأقدم من 5 دقائق، وعدم معالجة X-HNR-Delivery نفسه مرتين مع الرد بـ 2xx رغم ذلك (الحماية من الإعادة).

// Node.js (express.raw ile ham gövde / raw body)
import { createHmac, timingSafeEqual } from 'node:crypto';
const seen = new Set();
export function verify(secret, headers, rawBody) {
  const p = Object.fromEntries(String(headers['x-hnr-signature']).split(',').map((x) => x.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(p.t)) > 300) return 'old';
  const expected = createHmac('sha256', secret).update(`${p.t}.${rawBody}`).digest();
  const got = Buffer.from(p.v1 || '', 'hex');
  if (got.length !== expected.length || !timingSafeEqual(got, expected)) return 'bad';
  const id = headers['x-hnr-delivery'];
  if (seen.has(id)) return 'duplicate';   // answer 2xx, do not process again
  seen.add(id); return 'ok';
}
# Python 3
import hmac, hashlib, time
def verify(secret: str, signature: str, raw_body: bytes) -> bool:
    p = dict(x.split('=', 1) for x in signature.split(','))
    if abs(time.time() - int(p['t'])) > 300:
        return False
    expected = hmac.new(secret.encode(), p['t'].encode() + b'.' + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, p.get('v1', ''))

التسليم وإعادة المحاولة والرسائل الميتة

يرسل HNR طلب POST إلى عنوانك وينتظر 10 ثوانٍ؛ لا يُحتسب تسليمًا إلا الرد 2xx ولا تُتبع إعادات التوجيه. بعد المحاولة الفاشلة تكون فترات الانتظار تقريبًا 1 دقيقة ثم 3 دقائق و11 دقيقة و38 دقيقة وساعتين و7 ساعات و24 ساعة. إذا فشلت المحاولات الثماني صار التسليم رسالة ميتة. إشعارات الاشتراك نفسه والمستند نفسه تُرسل بالترتيب: لا يُرسل التالي قبل انتهاء السابق. ويُجرى 4 تسليمات متزامنة كحد أقصى لكل شركة.

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

سجل التسليم وإعادة الإرسال

يعرض سجل التسليم حالة كل إشعار (قيد الانتظار، تم التسليم، رسالة ميتة) وعدد المحاولات وآخر رمز HTTP، وتسرد التفاصيل النص المرسل وأول 1 كيلوبايت من الاستجابة وكل محاولة. يعيد «إعادة الإرسال» إرسال الإشعار فورًا مرة أخرى بمعرّف التسليم نفسه، وإن فشل تبدأ قاعدة إعادة المحاولة من جديد. لا تُحذف السجلات أبدًا. يرسل «إرسال اختبار» حدث test.ping إلى عنوان الاشتراك.

مفتاح تشفير الخادم

تُخزَّن أسرار التوقيع بتشفير AES-256-GCM بمفتاح تشفير الخادم نفسه المستخدم في الاتصال المصرفي المباشر (HNR_BANKA_KIMLIK_ANAHTARI). إذا لم يُعرَّف هذا المفتاح فلا يمكن حفظ الاشتراك. وإذا تغيّر المفتاح فلا يمكن فك تشفير الأسرار المحفوظة ويحتاج كل اشتراك إلى «تجديد السر».

ملخص نقاط نهاية OpenAPI

يسرد GET /api/openapi.json (أو زر التنزيل في قسم التكامل) كل نقاط نهاية الـ API المفتوحة حاليًا على الخادم مع المسار والطريقة ووسم الوحدة. لا تُوثَّق نصوص الطلب والاستجابة: إنه ملخص لنقاط النهاية وليس مخططًا رسميًا. المصادقة: مفتاح الـ API في Authorization: Bearer وX-Oturum-Token.

على الهاتف

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

أدلة ذات صلة