Məzmuna keç
HNROS Yardım mərkəzi
Azərbaycan dili
Pulsuz başla
MündəricatAbunə 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əsiTelefonda

Webhook 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