المحتويات
إنشاء اشتراكالأحداثمحتوى الإشعارالتحقق من التوقيعالتسليم وإعادة المحاولة والرسائل الميتةسجل التسليم وإعادة الإرسالمفتاح تشفير الخادمملخص نقاط نهاية 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.
على الهاتف
تظهر الاشتراكات على الهاتف كبطاقات، ويُنشأ الاشتراك الجديد في ثلاث خطوات (العنوان، الأحداث، المرشّح). سجل التسليم قائمة بطاقات، وفي كل بطاقة زرّا التفاصيل وإعادة الإرسال.
أدلة ذات صلة
- الأقسام - دليل من الصفر إلى الخلفيةهذا النوافذ لا تفعل عمل واحد؛ فإنه يحتفظ أطراف العشر من مختلف الأقسام لا تقلق: لا أحد يستخدم كل العشرة. اقرأ القسم الذي يتطابق مع عملك وتفوت الباقي.
- دليل التكاملات: بماذا يتصل HNR؟تجمع هذه الصفحة في مكان واحد كيفية اتصال HNR بالبنوك وشركات الشحن والأسواق الإلكترونية والإدارة الضريبية وملفات المحاسبة والبرامج الأخرى.
- طباعة النماذج - أنت تصميم ما يحدث على الورقكانت تصاميم عروض الأسعار والفواتير والإيصالات مدفونة داخل البرنامج، وتحتاج إلى مطوّر لتغييرها. الآن تبني أنت النموذج: يقدم مصمم الطباعة صفحة A4 فارغة.
- مسار التدقيق، أبواب الأمن والظروف غير المألوفةهذا الدليل يغطي ثلاثة طبقات منفصلة من الدفاع. سجلات, ثانياً توقف, ثالثاً عرض. كل واحد منهم مفيد من تلقاء نفسه، ولكن قوتهم الحقيقية تظهر عندما يتم استخدامها معا.
- سلسلة أرقام الوثيقة - دليل من الصفركل وثيقة نهائية - الفاتورة، ملاحظة التسليم، الطلب، الإقتباس، الاستلام، مجموعة الشك - لديها رقم يتم إظهاره للعميل والمحاسب والمكتب الضريبي.
- مركز الإشعار والموافقة - دليل من الصفرتنتظر الأعمال الموافقة في عشرة مواضع من البرنامج: حد الائتمان في موضع، وفرق مطابقة الفاتورة في آخر، وطلب الإجازة في الموارد البشرية.