Мазмунга өтүү
HNROS Жардам борбору
Кыргызча
Акысыз баштоо
МазмунуЖазылуу түзүүОкуяларБилдирүүнүн мазмунуКол тамганы текшерүүЖеткирүү, кайра аракет жана жеткирилбеген катЖеткирүү журналы жана кайра жөнөтүүСервердин шифрлөө ачкычы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.

Телефондо

Телефондо жазылуулар карточка түрүндө көрүнөт; жаңы жазылуу үч кадамда ачылат (Дарек, Окуялар, Чыпка). Жеткирүү журналы карточкалардын тизмеси; ар бир карточкада Толук маалымат жана Кайра жөнөтүү баскычтары бар.

Тиешелүү колдонмолор