Asosiy matnga oʻtish
HNROS Yordam markazi
Oʻzbekcha
Bepul boshlash
MundarijaObuna yaratishHodisalarXabar mazmuniImzoni tekshirishYetkazish, qayta urinish va yetkazilmagan xabarYetkazish jurnali va qayta yuborishServer shifrlash kalitiOpenAPI nuqtalari qisqachasiTelefonda

Webhook va OpenAPI: boshqa tizimlarga hodisa xabari

HNR'da hodisa yuz berganda (hisob-faktura yozildi, buyurtma o‘chirildi, jo‘natma yo‘lga chiqdi…) webhook siz belgilagan manzilga imzolangan HTTP xabar yuboradi. Xabarda faqat hujjat qisqachasi va API havolasi bo‘ladi; qabul qiluvchi to‘liq yozuvni o‘z sessiyasi bilan API'dan o‘qiydi. Bu sahifa shartnoma tavsifi, rasmiy sxema emas.

Obuna yaratish

Sozlamalar › Integratsiya va webhooklar faqat tizim ma’muriga ochiq. Yangi obunaga nom, manzil va kamida bitta hodisa kerak. Manzil https bilan boshlanishi kerak; mahalliy tarmoq yoki shu kompyuterdagi manzil (masalan 192.168.x.x, localhost) faqat ma’mur tasdig‘i belgilansa qabul qilinadi. Bir manzil uchun ikkinchi obuna ochilmaydi.

Ixtiyoriy filtrlar: faqat ayrim kontragentlar yoki omborlar. Filtr belgilangan, ammo hujjatda bu maydon bo‘lmasa, xabar yuborilmaydi. Hujjat summasi va valyutasi faqat “Xabarga hujjat summasi va valyutasini qo‘shish” belgilansa yuboriladi.

Saqlanganda maxfiy kalit (whsec_ bilan boshlanadi) faqat bir marta ko‘rsatiladi; uni qabul qiluvchi tizimda saqlang. Serverda shifrlangan holda saqlanadi va qayta o‘qib bo‘lmaydi. Yo‘qotsangiz, “Kalitni yangilash” bilan yangisini yarating; eski kalitdagi imzo endi tasdiqlanmaydi.

Hodisalar

hisob-faktura, buyurtma, taklif (fatura, siparis, teklif): yazildi, degisti, silindi · yuk xati (irsaliye): yazildi, silindi · kvitansiya (makbuz): yazildi, degisti, silindi · stok.hareket (omborlar orasidagi ko‘chirish jo‘natildi, qabul qilindi yoki yo‘qotildi; sanoq tasdig‘i) · sevkiyat.durum (jo‘nash, to‘xtash joyida topshirish, POD tuzatish) · onay.karar · dof.acildi · servis.bilet (ochildi, holat) · uretim.teyit (tasdiq yoki bekor qilish). Hodisa kodi X-HNR-Event sarlavhasida va matnning olay maydonida; sinov tugmasi test.ping yuboradi.

Xabar mazmuni

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 — yakuniy hujjat raqami; to‘liq yozuv baglanti orqali API'dan o‘qiladi. tutar va doviz faqat summa kiritilgan obunalarda keladi; doviz bo‘lmasa summa firmaning milliy valyutasida. O‘chirish hodisasida qisqacha hujjat o‘chirilishidan oldin o‘qiladi. surum — yuk formati versiyasi: yangi maydon qo‘shilishi mumkin, mavjudlari o‘zgarmaydi.

Imzoni tekshirish

Har bir so‘rovda X-HNR-Event, X-HNR-Delivery (yetkazish identifikatori), X-HNR-Timestamp va X-HNR-Signature: t=…,v1=… sarlavhalari bo‘ladi. v1 — maxfiy kalit bilan t + "." + xom matn uchun HMAC-SHA256 (o‘n oltilik). Qabul qiluvchi imzoni doimiy vaqtli taqqoslash bilan tekshirishi, 5 daqiqadan eski vaqtni rad etishi va bir xil X-HNR-Deliveryni ikki marta ishlamasligi, lekin baribir 2xx qaytarishi kerak (takrordan himoya).

// 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', ''))

Yetkazish, qayta urinish va yetkazilmagan xabar

HNR manzilingizga POST yuboradi va 10 soniya kutadi; faqat 2xx javob yetkazilgan hisoblanadi, yo‘naltirishlarga ergashilmaydi. Muvaffaqiyatsiz urinishdan keyingi kutish taxminan 1 daq, 3 daq, 11 daq, 38 daq, 2 soat, 7 soat va 24 soat. Sakkizta urinish ham muvaffaqiyatsiz bo‘lsa, yetkazish yetkazilmagan xabarga aylanadi. Bir obuna va bir hujjat xabarlari navbat bilan ketadi: oldingisi tugamaguncha keyingisi yuborilmaydi. Har firmada bir vaqtda ko‘pi bilan 4 ta yuborish.

Obuna bo‘lmasa server hech narsa yubormaydi. Yuborish serverning o‘z firmasida har daqiqada, boshqa firmalarda esa o‘sha firmada yangi amal bajarilganda ishlaydi. To‘xtatilgan obunadagi kutilayotgan xabarlar kutadi va qayta faollashtirilganda ketadi.

Yetkazish jurnali va qayta yuborish

Yetkazish jurnali har bir xabar holatini (kutilmoqda, yetkazilgan, yetkazilmagan), urinishlar sonini va oxirgi HTTP kodini ko‘rsatadi; tafsilotda yuborilgan matn, javobning dastlabki 1 KB va har bir urinish bo‘ladi. “Qayta yuborish” xabarni o‘sha yetkazish identifikatori bilan darhol yana bir bor yuboradi; muvaffaqiyatsiz bo‘lsa, qayta urinish qoidasi boshidan ishlaydi. Yozuvlar o‘chirilmaydi. “Sinov yuborish” obuna manziliga test.ping hodisasini yuboradi.

Server shifrlash kaliti

Maxfiy kalitlar jonli bank ulanishi bilan bir xil server shifrlash kaliti (HNR_BANKA_KIMLIK_ANAHTARI) yordamida AES-256-GCM bilan saqlanadi. Bu kalit belgilanmagan bo‘lsa, obunani saqlab bo‘lmaydi. Kalit o‘zgarsa, saqlangan maxfiy kalitlar ochilmaydi va har bir obunada “Kalitni yangilash” kerak.

OpenAPI nuqtalari qisqachasi

GET /api/openapi.json (yoki Integratsiya bo‘limidagi yuklab olish tugmasi) server hozir ochgan barcha API nuqtalarini yo‘l, usul va modul belgisi bilan ro‘yxatlaydi. So‘rov va javob matnlari hujjatlashtirilmaydi: bu nuqtalar qisqachasi, rasmiy sxema emas. Autentifikatsiya: Authorization: Bearer API kaliti va X-Oturum-Token.

Telefonda

Telefonda obunalar kartochka ko‘rinishida chiqadi; yangi obuna uch qadamda ochiladi (Manzil, Hodisalar, Filtr). Yetkazish jurnali kartochkalar ro‘yxati; har bir kartochkada Tafsilot va Qayta yuborish tugmalari bor.

Tegishli qoʻllanmalar