विषय-सूची
सब्सक्रिप्शन बनानाइवेंटसूचना की सामग्रीहस्ताक्षर सत्यापित करनाडिलीवरी, पुनः प्रयास और डेड लेटरडिलीवरी लॉग और फिर से भेजनासर्वर एन्क्रिप्शन कुंजी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 (रवानगी, पड़ाव पर डिलीवरी, 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.