Мазмұны
Жазылым құруОқиғаларХабарлама мазмұныҚолтаңбаны тексеруЖеткізу, қайталау және жеткізілмеген хатЖеткізу журналы және қайта жіберуСервер шифрлау кілтіOpenAPI соңғы нүктелерінің қысқаша мазмұныТелефондаWebhook және OpenAPI: басқа жүйелерге оқиға хабарламасы
HNR-де оқиға болғанда (шот-фактура жазылды, тапсырыс жойылды, жөнелту жолға шықты…) webhook сіз белгілеген мекенжайға қол қойылған HTTP хабарламасын жібереді. Хабарламада тек құжаттың қысқаша мазмұны мен API сілтемесі болады; қабылдаушы толық жазбаны өз сессиясымен API-ден оқиды. Бұл бет келісімнің сипаттамасы, ресми схема емес.
Жазылым құру
Баптаулар › Интеграция және webhookтар тек жүйе әкімшісіне ашық. Жаңа жазылымға атау, мақсатты мекенжай және кемінде бір оқиға қажет. Мекенжай 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-дің банктерге, курьерлік қызметтерге, маркетплейстерге, салық органына, бухгалтерлік файлдарға және басқа бағдарламаларға қалай қосылатынын бір.
- «Жеңіске» АҚШ-ның ең көне ұшыратын қабығыБұрын ұсыныс, шот-фактура және түбіртек пішімдері бағдарламаға кірістірілген, өзгерту үшін әзірлеуші керек еді. Енді форманы өзіңіз жасайсыз.
- Аудиттық тралгі, қабығы және аномалияБұл қабығы жылдан кейінгі қарастырылған. Секреттер: Рекорды, қаңтар Одан, қаңтар Есімдік. Оның басты себебі – иманның кемдігінде.
- «Аяқтық-қатынас» - Серіктің қабығыӘр түпкілікті құжаттың — шот-фактура, жеткізу құжаты, тапсырыс, ұсыныс, түбіртек, чек жиыны — клиентке, бухгалтерге, салық органына көрсетілетін нөмірі бар.
- Олардың ішіндегі ең көне апеллятив – үңгір.Мақұлдау күткен жұмыс бағдарламаның он жерінде: кредит лимиті бірде, шот сәйкестік айырмасы басқада, демалыс сұрауы кадрларда.