فہرست
سبسکرپشن بناناواقعاتاطلاع کا مواددستخط کی تصدیقترسیل، دوبارہ کوشش اور ناکام پیغامترسیل لاگ اور دوبارہ بھیجناسرور کی خفیہ کاری کلیدOpenAPI اینڈ پوائنٹ خلاصہفون پرویب ہکس اور OpenAPI: دوسرے نظاموں کو واقعات کی اطلاع
جب HNR میں کوئی واقعہ ہو (انوائس درج، آرڈر حذف، شپمنٹ روانہ…) تو ویب ہک آپ کے مقرر کردہ پتے پر دستخط شدہ HTTP اطلاع بھیجتا ہے۔ اطلاع میں صرف دستاویز کا خلاصہ اور API لنک ہوتا ہے؛ وصول کنندہ مکمل ریکارڈ اپنے سیشن سے API سے پڑھتا ہے۔ یہ صفحہ ایک معاہدے کی وضاحت ہے، سرکاری اسکیما نہیں۔
سبسکرپشن بنانا
ترتیبات › انضمام اور ویب ہکس صرف سسٹم منتظم کے لیے ہے۔ نئی سبسکرپشن کے لیے نام، ہدف پتہ اور کم از کم ایک واقعہ ضروری ہے۔ پتہ https سے شروع ہونا چاہیے؛ مقامی نیٹ ورک یا اسی کمپیوٹر کا ہدف (مثلاً 192.168.x.x، localhost) صرف منتظم کی منظوری کے خانے پر نشان ہو تو قبول ہوتا ہے۔ ایک ہی پتے کے لیے دوسری سبسکرپشن نہیں بن سکتی۔
اختیاری فلٹر: صرف مخصوص کھاتے یا گودام۔ فلٹر مقرر ہو اور دستاویز میں وہ خانہ نہ ہو تو اطلاع نہیں بھیجی جاتی۔ دستاویز کی رقم اور کرنسی صرف تب بھیجی جاتی ہے جب “اطلاع میں دستاویز کی رقم اور کرنسی شامل کریں” پر نشان ہو۔
محفوظ کرتے وقت دستخطی راز (whsec_ سے شروع) صرف ایک بار دکھایا جاتا ہے؛ اسے وصول کنندہ نظام میں محفوظ کریں۔ یہ سرور پر خفیہ شکل میں رکھا جاتا ہے اور دوبارہ پڑھا نہیں جا سکتا۔ گم ہو جائے تو “راز نیا کریں” سے نیا بنائیں؛ پرانے راز والے دستخط درست نہیں رہتے۔
واقعات
انوائس، آرڈر، کوٹیشن (fatura، siparis، teklif): yazildi، degisti، silindi · ڈیلیوری نوٹ (irsaliye): yazildi، silindi · رسید (makbuz): yazildi، degisti، silindi · stok.hareket (گوداموں کے درمیان منتقلی روانہ، وصول یا ضائع؛ گنتی کی منظوری) · sevkiyat.durum (روانگی، اسٹاپ پر ترسیل، POD درستی) · 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 حتمی دستاویز نمبر ہے؛ مکمل ریکارڈ baglanti کے ذریعے API سے پڑھا جاتا ہے۔ tutar اور doviz صرف رقم شامل سبسکرپشنز میں آتے ہیں؛ doviz نہ ہو تو رقم کمپنی کی مقامی کرنسی میں ہے۔ حذف کے واقعے میں خلاصہ دستاویز حذف ہونے سے پہلے پڑھا جاتا ہے۔ surum مواد کی شکل کا ورژن ہے: نئے خانے شامل ہو سکتے ہیں، موجودہ نہیں بدلتے۔
دستخط کی تصدیق
ہر درخواست میں X-HNR-Event، X-HNR-Delivery (ترسیل شناخت)، X-HNR-Timestamp اور X-HNR-Signature: t=…,v1=… ہیڈر ہوتے ہیں۔ v1 دستخطی راز کے ساتھ متن t + "." + خام مواد کا HMAC-SHA256 (ہیکس) ہے۔ وصول کنندہ دستخط کو مستقل وقت موازنے سے جانچے، 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 منٹ، 2 گھنٹے، 7 گھنٹے اور 24 گھنٹے ہیں۔ آٹھوں کوششیں ناکام ہوں تو ترسیل ناکام پیغام بن جاتی ہے۔ ایک ہی سبسکرپشن اور دستاویز کی اطلاعات ترتیب سے جاتی ہیں: پچھلی مکمل ہونے سے پہلے اگلی نہیں جاتی۔ فی کمپنی بیک وقت زیادہ سے زیادہ 4 ترسیلات۔
سبسکرپشن نہ ہو تو سرور کچھ نہیں بھیجتا۔ سرور کی اپنی کمپنی میں ترسیل ہر منٹ چلتی ہے؛ دوسری کمپنیوں میں جب اس کمپنی میں کوئی نیا عمل ہو۔ رکی ہوئی سبسکرپشن کی زیر التوا اطلاعات انتظار کرتی ہیں اور دوبارہ فعال ہونے پر جاتی ہیں۔
ترسیل لاگ اور دوبارہ بھیجنا
ترسیل لاگ ہر اطلاع کی حالت (زیر التوا، پہنچ گئی، ناکام)، کوششوں کی تعداد اور آخری HTTP کوڈ دکھاتا ہے؛ تفصیل میں بھیجا گیا مواد، جواب کا پہلا 1 KB اور ہر کوشش درج ہوتی ہے۔ “دوبارہ بھیجیں” اسی ترسیل شناخت سے فوراً ایک بار پھر بھیجتا ہے؛ ناکام ہو تو دوبارہ کوشش کا اصول شروع سے چلتا ہے۔ ریکارڈ کبھی حذف نہیں ہوتے۔ “آزمائش بھیجیں” سبسکرپشن کے پتے پر test.ping واقعہ بھیجتا ہے۔
سرور کی خفیہ کاری کلید
دستخطی راز براہِ راست بینک کنکشن والی اسی سرور خفیہ کاری کلید (HNR_BANKA_KIMLIK_ANAHTARI) کے ساتھ AES-256-GCM سے محفوظ ہوتے ہیں۔ یہ کلید متعین نہ ہو تو سبسکرپشن محفوظ نہیں ہو سکتی۔ کلید بدل جائے تو محفوظ راز ڈی کرپٹ نہیں ہوتے اور ہر سبسکرپشن میں “راز نیا کریں” درکار ہے۔
OpenAPI اینڈ پوائنٹ خلاصہ
GET /api/openapi.json (یا انضمام حصے میں ڈاؤن لوڈ بٹن) سرور کے اس وقت کھلے تمام API اینڈ پوائنٹس کو راستے، طریقے اور ماڈیول ٹیگ کے ساتھ دکھاتا ہے۔ درخواست اور جواب کا مواد درج نہیں: یہ اینڈ پوائنٹ خلاصہ ہے، سرکاری اسکیما نہیں۔ تصدیق: Authorization: Bearer API کلید اور X-Oturum-Token۔
فون پر
فون پر سبسکرپشنز کارڈ کی صورت میں دکھتی ہیں؛ نئی سبسکرپشن تین مراحل میں بنتی ہے (پتہ، واقعات، فلٹر)۔ ترسیل لاگ کارڈوں کی فہرست ہے؛ ہر کارڈ پر تفصیل اور دوبارہ بھیجیں بٹن ہیں۔
متعلقہ رہنما
- سیکشنز — اسکرٹچ سے پیچھے دفتر کے لئے ایک گائیڈیہ فہرست ایک کام نہیں کرتا؛ یہ مختلف اداروں کے رہنماؤں کی فہرست ایک طرف ایک طرف. نہیں پریشان ہو: کوئی بھی تمام دس استعمال نہیں کرتا.
- انٹیگریشن کیٹلاگ: HNR کن چیزوں سے جڑتا ہے؟یہ صفحہ ایک جگہ بتاتا ہے کہ HNR بینکوں، کوریئر کمپنیوں، مارکیٹ پلیسز، ٹیکس اتھارٹی، اکاؤنٹنگ فائلوں اور دوسرے پروگراموں سے کیسے جڑتا ہے۔ ہر سطر کے آگے لگا.
- پرنٹ فارم - آپ کاغذ پر کیا جا رہا ہے ڈیزائنانٹرویو، فیکٹری اور رسیپٹ ڈائریکٹس پروگرام کے اندر دفن کرنے کے لئے استعمال کیا جاتا ہے؛ ایک تبدیل کرنے کے لئے ایک ڈویلپر کی ضرورت ہوتی ہے.
- ٹیسٹ ٹریل، سیکورٹی دروازے اور غیر معمولیاتاس گائیڈ میں تین مختلف دفاعی طبقات پر مشتمل ہے. مختصر طور پر: پہلا ریکارڈ, دوسری طرف روکیں, تیسری دکھائی دیتا ہے. ہر ایک اپنے آپ میں فائدہ مند ہے.
- دستاویز نمبر سیریز — ایک گائیڈ سے Scratchہر آخری دستاویز - فیکٹری، تحویل نوٹ، آرڈر، نقل و حمل، وصولی، چیک باچ - ایک نمبر ہے جو صارف، اکاؤنٹنٹ اور ٹیکس دفتر کو دکھایا جاتا ہے.
- نوٹس اور تصدیق کے مرکز — ایک گائیڈ سے Scratchکام کی تصدیق کے لئے انتظار کر رہے ہیں سیٹوں میں دس مختلف کورس پروگرام: ایک جگہ میں کریڈٹ حد، فیکٹری دوسرے میں فرق مطابقت رکھتا ہے، اجازت نامہ کی درخواست HR.