Mündəricat
Abunə yaratmaqHadisələrBildirişin məzmunuİmzanı yoxlamaqÇatdırılma, təkrar cəhd və çatdırılmayan məktubÇatdırılma jurnalı və yenidən göndərməServer şifrələmə açarıOpenAPI son nöqtələrinin xülasəsiTelefondaWebhook və OpenAPI: başqa sistemlərə hadisə bildirişi
HNR-də hadisə baş verəndə (faktura yazıldı, sifariş silindi, göndəriş yola çıxdı…) webhook təyin etdiyiniz ünvana imzalı HTTP bildirişi göndərir. Bildiriş yalnız sənədin xülasəsini və API keçidini daşıyır; qəbul edən tam qeydi öz sessiyası ilə API-dən oxuyur. Bu səhifə müqavilənin təsviridir, rəsmi sxem deyil.
Abunə yaratmaq
Ayarlar › İnteqrasiya və webhooklar yalnız sistem inzibatçısına açıqdır. Yeni abunə üçün ad, hədəf ünvan və ən azı bir hadisə lazımdır. Ünvan https ilə başlamalıdır; yerli şəbəkədəki və ya bu kompüterdəki hədəf (məs. 192.168.x.x, localhost) yalnız inzibatçı təsdiqi qutusu işarələnərsə qəbul edilir. Eyni ünvan üçün ikinci abunə açılmır.
İstəyə bağlı süzgəclər: yalnız müəyyən kontragentlər və ya anbarlar. Süzgəc təyin olunub, sənəddə həmin sahə yoxdursa, bildiriş göndərilmir. Sənədin məbləği və valyutası yalnız “Bildirişə sənədin məbləğini və valyutasını əlavə et” işarələnərsə göndərilir.
Yadda saxlayanda gizli açar (whsec_ ilə başlayır) yalnız bir dəfə göstərilir; onu qəbul edən sistemdə saxlayın. Serverdə şifrəli saxlanılır və yenidən oxunmur. İtirsəniz, “Açarı yenilə” ilə yenisini yaradın; köhnə açarla imza artıq təsdiqlənmir.
Hadisələr
faktura, sifariş, təklif (fatura, siparis, teklif): yazildi, degisti, silindi · qaimə (irsaliye): yazildi, silindi · qəbz (makbuz): yazildi, degisti, silindi · stok.hareket (anbarlararası köçürmə göndərildi, qəbul edildi və ya itki; sayım təsdiqi) · sevkiyat.durum (yola çıxış, dayanacaqda təhvil, POD düzəlişi) · onay.karar · dof.acildi · servis.bilet (açıldı, vəziyyət) · uretim.teyit (təsdiq və ya ləğv). Hadisə kodu X-HNR-Event başlığında və məzmunun olay sahəsindədir; sınaq düyməsi test.ping göndərir.
Bildirişin məzmunu
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 sənədin yekun nömrəsidir; tam qeyd baglanti vasitəsilə API-dən oxunur. tutar və doviz yalnız məbləğ daxil olan abunələrdə gəlir; doviz yoxdursa məbləğ firmanın yerli valyutasındadır. Silmə hadisəsində xülasə sənəd silinməzdən əvvəl oxunur. surum yükün format versiyasıdır: yeni sahələr əlavə oluna bilər, mövcudlar dəyişmir.
İmzanı yoxlamaq
Hər sorğuda X-HNR-Event, X-HNR-Delivery (çatdırılma identifikatoru), X-HNR-Timestamp və X-HNR-Signature: t=…,v1=… başlıqları olur. v1 gizli açarla t + "." + xam məzmun mətninin HMAC-SHA256 (onaltılıq) cəmidir. Qəbul edən imzanı sabit zamanlı müqayisə ilə yoxlamalı, 5 dəqiqədən köhnə vaxtı rədd etməli və eyni X-HNR-Delivery-ni iki dəfə emal etməməli, amma yenə də 2xx qaytarmalıdır (təkrardan qorunma).
// 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', '')) Çatdırılma, təkrar cəhd və çatdırılmayan məktub
HNR ünvanınıza POST göndərir və 10 saniyə gözləyir; yalnız 2xx cavab çatdırılmış sayılır, yönləndirmələrə əməl edilmir. Uğursuz cəhddən sonra gözləmələr təxminən 1 dəq, 3 dəq, 11 dəq, 38 dəq, 2 saat, 7 saat və 24 saatdır. Səkkiz cəhdin hamısı uğursuz olarsa, çatdırılma çatdırılmayan məktuba çevrilir. Eyni abunə və eyni sənədin bildirişləri növbə ilə gedir: əvvəlki bitmədən növbəti göndərilmir. Hər firmada eyni anda ən çox 4 göndəriş.
Abunə olmasa server heç nə göndərmir. Göndəriş serverin öz firmasında hər dəqiqə, digər firmalarda isə həmin firmada yeni əməliyyat olanda işləyir. Dayandırılmış abunədə gözləyən bildirişlər gözləyir və yenidən aktivləşdiriləndə gedir.
Çatdırılma jurnalı və yenidən göndərmə
Çatdırılma jurnalı hər bildirişin vəziyyətini (gözləyən, çatdırılan, çatdırılmayan), cəhd sayını və son HTTP kodunu göstərir; təfərrüatda göndərilən məzmun, cavabın ilk 1 KB-ı və hər cəhd verilir. “Yenidən göndər” bildirişi eyni çatdırılma identifikatoru ilə dərhal bir dəfə də göndərir; uğursuz olarsa, təkrar cəhd qaydası başdan işləyir. Qeydlər heç vaxt silinmir. “Sınaq göndər” abunə ünvanına test.ping hadisəsi göndərir.
Server şifrələmə açarı
Gizli açarlar canlı bank bağlantısı ilə eyni server şifrələmə açarı (HNR_BANKA_KIMLIK_ANAHTARI) ilə AES-256-GCM vasitəsilə saxlanılır. Bu açar təyin edilməyibsə, abunə saxlanıla bilməz. Açar dəyişərsə, saxlanmış gizli açarlar açılmır və hər abunədə “Açarı yenilə” lazımdır.
OpenAPI son nöqtələrinin xülasəsi
GET /api/openapi.json (və ya İnteqrasiya bölməsindəki yükləmə düyməsi) serverin hazırda açıq olan bütün API son nöqtələrini yol, üsul və modul etiketi ilə sadalayır. Sorğu və cavab məzmunları sənədləşdirilmir: bu son nöqtələrin xülasəsidir, rəsmi sxem deyil. Autentifikasiya: Authorization: Bearer API açarı və X-Oturum-Token.
Telefonda
Telefonda abunələr kart kimi görünür; yeni abunə üç addımda açılır (Ünvan, Hadisələr, Süzgəc). Çatdırılma jurnalı kartlar siyahısıdır; hər kartda Təfərrüat və Yenidən göndər düymələri var.
Əlaqəli təlimatlar
- Qadınlar – Bakın Ofis üçün Scratch-dan bir rehberBu işdə bir şey yoxdur; bu işdə farklı departmanların Bu barədə xəbər verir ki, bu barədə “Müslərin bütün nəfərinin işini qəbul etməsi üçün bir neçə dəfə.
- İnteqrasiya kataloqu: HNR nəyə qoşulur?Bu səhifə HNR-in banklara, kargo şirkətlərinə, marketpleyslərə, vergi orqanına, mühasibat fayllarına və başqa proqramlara necə qoşulduğunu bir yerdə toplayır.
- “Müslər” – “Müslər”ın yazılı formlarıBu programın içində gömülmək üçün kullanılan cüt, fatur və alınma düzəltləri; birini dəyişmək bir geliştiricə lazımdır. Şimdilik Siz Şəkilini hazırlayın.
- “Gözlük” və “Gözlük” və “Gözlük”Bu qapı üç ayrı savunma layrını kapsamaktadır. kısaca: ilk Rekordlar, İkinci Qəzaq, Üçüncü Showqə. Hər biri özünə faydalıdır.
- “Dokument Number Series” – Scratch-dan bir rehberHər bir final belə – fatura, teslimat notu, sipariş, cütət, alınma, şeker paketinin – müştərinin, hesabçıın və vergi müdürünün göstərən bir sayı vardır.
- İzin və Onay Merkezi - Scratch-dan bir rehberİş, programın farklı köşesinde onaylanma üçün gözləməkdə yerlər: kredit limitı bir yerdə, faturanın bir başta eşlik etməsi farkı, tatil başvuru HR.