Мазмуну
Жазылуу түзүүОкуяларБилдирүүнүн мазмунуКол тамганы текшерүүЖеткирүү, кайра аракет жана жеткирилбеген катЖеткирүү журналы жана кайра жөнөтүүСервердин шифрлөө ачкычы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.
Телефондо
Телефондо жазылуулар карточка түрүндө көрүнөт; жаңы жазылуу үч кадамда ачылат (Дарек, Окуялар, Чыпка). Жеткирүү журналы карточкалардын тизмеси; ар бир карточкада Толук маалымат жана Кайра жөнөтүү баскычтары бар.
Тиешелүү колдонмолор
- Ар бир иштин жетекчисиБул терезе бир жумушта иштебейт, ал колдойт Он бөлүмдөгү маалымат Ал эми ар бир адам окуп чыгышы керек. Бөлүм 1 жана 2 — Иштин кайсы жерде жашап жатканын.
- Интеграциялар каталогу: HNR эмнелерге туташат?Бул барак HNR банктарга, курьердик кызматтарга, маркетплейстерге, салык органына, бухгалтердик файлдарга жана башка программаларга кантип туташаарын бир жерге.
- Кагаздагы маалыматтарды басып салгыла.Түшүндүрмөлөр, коштоолор программанын ичинде көмүлүшү жана репродуктивдүү түзүлүштөрдү өзгөртүү үчүн, кайсы бир куруучунун өзгөрүшүн талап кылган.
- Коопсуздук дарбазалары жана аномаларАл жетекчи үч катты камтыйт. маалыматы, экинчи Токтотулган, үчүнчү Көрсөткүч. Ар бири өз пайдасына пайдалуу. Бөлүм 1–2 Ар бир менеджер эмне айтса.
- Документтин номери — кубулуп чыккан жетекчиБул документтин ар бир бөлүгүн: инсвоицес, цикл, цикл, шишик, шишик, салык төлөөчүлөр менен жабдылган. HNR Бул сандагы жараяндар элемент түрүндөгү элемент Бул.
- Кабар айтуу жана аны кабыл алуу борбору — сестентерлик жетекчиликПрограмманын ар кайсы бөлүктөрүнүн бир бөлүгүндө анын жактыруусуна ээ болуу үчүн бир эле орунда турган жумуш: кредит чектелүү, башка жагынан.