Mazmuna geç
HNROS Kömek merkezi
Türkmençe
Mugt başlaň
MazmunyAbuna döretmekWakalarHabarnamanyň mazmunyGoly barlamakGowşuryş, gaýtadan synanyşyk we gowşurylmadyk hatGowşuryş žurnaly we gaýtadan ibermekSerwer şifrleme açaryOpenAPI nokatlarynyň gysgaça mazmunyTelefonda

Webhook we OpenAPI: başga ulgamlara waka habarnamasy

HNR-de waka bolanda (faktura ýazyldy, sargyt pozuldy, iberiş ýola çykdy…) webhook siziň kesgitlän salgyňyza gol çekilen HTTP habarnamasyny iberýär. Habarnama diňe resminamanyň gysgaça mazmunyny we API baglanyşygyny göterýär; kabul ediji doly ýazgyny öz sessiýasy bilen API-den okaýar. Bu sahypa şertnamanyň düşündirişi, resmi shema däl.

Abuna döretmek

Sazlamalar › Integrasiýa we webhooklar diňe ulgam dolandyryjysyna açyk. Täze abuna at, maksat salgysy we iň bolmanda bir waka gerek. Salgy https bilen başlamaly; ýerli tordaky ýa-da bu kompýuterdäki maksat (meselem 192.168.x.x, localhost) diňe dolandyryjy tassyklama gutusy bellense kabul edilýär. Şol bir salgy üçin ikinji abuna açylmaýar.

Islege bagly süzgüçler: diňe käbir kontragentler ýa-da ammarlar. Süzgüç bellenen, ýöne resminamada şol meýdan ýok bolsa, habarnama iberilmeýär. Resminamanyň mukdary we walýutasy diňe “Habarnama resminamanyň mukdaryny we walýutasyny goş” bellense iberilýär.

Saklananda gizlin açar (whsec_ bilen başlaýar) diňe bir gezek görkezilýär; ony kabul ediji ulgamda saklaň. Serwerde şifrlenip saklanýar we täzeden okalyp bilinmeýär. Ýitirseňiz, “Açary täzele” bilen täzesini dörediň; köne açar bilen gol indi tassyklanmaýar.

Wakalar

faktura, sargyt, teklip (fatura, siparis, teklif): yazildi, degisti, silindi · ýük haty (irsaliye): yazildi, silindi · kwitansiýa (makbuz): yazildi, degisti, silindi · stok.hareket (ammarlaryň arasynda geçiriş iberildi, kabul edildi ýa-da ýitgi; sanaw tassyklamasy) · sevkiyat.durum (ugramak, duralgada tabşyrmak, POD düzedişi) · onay.karar · dof.acildi · servis.bilet (açyldy, ýagdaý) · uretim.teyit (tassyklama ýa-da ýatyrma). Waka kody X-HNR-Event sözbaşysynda we mazmunyň olay meýdanynda; synag düwmesi test.ping iberýär.

Habarnamanyň mazmuny

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 — resminamanyň jemleýji belgisi; doly ýazgy baglanti arkaly API-den okalýar. tutar we doviz diňe mukdar goşulan abunalarda gelýär; doviz ýok bolsa mukdar kärhananyň ýerli puly. Pozmak wakasynda gysgaça mazmun resminama pozulmazdan öň okalýar. surum — ýük formatynyň wersiýasy: täze meýdan goşulyp bilner, bar bolanlar üýtgemeýär.

Goly barlamak

Her haýyşda X-HNR-Event, X-HNR-Delivery (gowşuryş belgisi), X-HNR-Timestamp we X-HNR-Signature: t=…,v1=… sözbaşylary bar. v1 — gizlin açar bilen t + "." + çig mazmun tekstiniň HMAC-SHA256 (onaltylyk) jemi. Kabul ediji goly hemişelik wagtly deňeşdirme bilen barlamaly, 5 minutdan köne wagty ret etmeli we şol bir X-HNR-Delivery-ni iki gezek işlemeli däl, ýöne ýene 2xx gaýtarmaly (gaýtalamadan gorag).

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

Gowşuryş, gaýtadan synanyşyk we gowşurylmadyk hat

HNR salgyňyza POST iberýär we 10 sekunt garaşýar; diňe 2xx jogap gowşurylan hasaplanýar, gönükdirmelere eýerilmeýär. Şowsuz synanyşykdan soňky garaşmalar takmynan 1 min, 3 min, 11 min, 38 min, 2 sag, 7 sag we 24 sag. Sekiz synanyşygyň hemmesi şowsuz bolsa, gowşuryş gowşurylmadyk hata öwrülýär. Şol bir abunanyň we resminamanyň habarnamalary yzygiderli gidýär: öňküsi gutarmanka indikisi iberilmeýär. Her kärhanada bir wagtda iň köp 4 iberiş.

Abuna bolmasa serwer hiç zat ibermeýär. Iberiş serweriň öz kärhanasynda her minutda, beýleki kärhanalarda bolsa şol kärhanada täze amal edilende işleýär. Duruzylan abunadaky garaşylýan habarnamalar garaşýar we täzeden işjeňleşdirilende gidýär.

Gowşuryş žurnaly we gaýtadan ibermek

Gowşuryş žurnaly her habarnamanyň ýagdaýyny (garaşylýan, gowşurylan, gowşurylmadyk), synanyşyk sanyny we soňky HTTP koduny görkezýär; jikme-jiklikde iberilen mazmun, jogabyň ilkinji 1 KB-y we her synanyşyk bar. “Gaýtadan iber” habarnamany şol bir gowşuryş belgisi bilen derrew ýene bir gezek iberýär; şowsuz bolsa, gaýtadan synanyşmak düzgüni başdan işleýär. Ýazgylar pozulmaýar. “Synag iber” abuna salgysyna test.ping wakasyny iberýär.

Serwer şifrleme açary

Gizlin açarlar göni bank birikmesi bilen şol bir serwer şifrleme açary (HNR_BANKA_KIMLIK_ANAHTARI) arkaly AES-256-GCM bilen saklanýar. Bu açar kesgitlenmedik bolsa, abuna saklanyp bilinmeýär. Açar üýtgese, saklanan gizlin açarlar açylmaýar we her abunada “Açary täzele” gerek.

OpenAPI nokatlarynyň gysgaça mazmuny

GET /api/openapi.json (ýa-da Integrasiýa bölümindäki ýükleme düwmesi) serweriň häzir açan ähli API nokatlaryny ýol, usul we modul belligi bilen sanaýar. Haýyş we jogap mazmunlary resminamalaşdyrylmaýar: bu nokatlaryň gysgaça mazmuny, resmi shema däl. Tassyklama: Authorization: Bearer API açary we X-Oturum-Token.

Telefonda

Telefonda abunalar kartoçka görnüşinde görünýär; täze abuna üç ädimde açylýar (Salgy, Wakalar, Süzgüç). Gowşuryş žurnaly kartoçkalaryň sanawy; her kartoçkada Jikme-jiklik we Gaýtadan iber düwmeleri bar.

Degişli gollanmalar