Mazmuny
Abuna 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 mazmunyTelefondaWebhook 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
- Departamentler — Back Office üçin Täzeden Başlanmak üçin Ýörite RehberBu äpişgäniň başynda ol işlemeýär, düşer. On bölümiň kitaplary Hiç kim gaýgy - aladalanmajak bol: işiňe daýanyp, dynç alsaň.
- Integrasiýa katalogy: HNR nämelere birikýär?Bu sahypa HNR-iň banka, kargo kompaniýasyna, marketpleýse, salgyt edarasyna, buhgalteriýa faýllaryna we beýleki programmalara nähili birikýändigini bir ýere.
- Print Forms — kagyza düşjek zatlary siz dizaýn edýärsiňiz.Töwratda, programyň içinde jaýlanýan teleýaýlymlar; ilki gerekli bejeriş usulyny, indi bolsa gerekli terertoriýasyny etdirmeli.
- Audit ýoly, howpsuzlyk gapylary we anomaliýalarBu maslahat goraýan üç sany galakga degişli. _Wasp, Ikinji _Ýerme, Üçünji Ýardam. Olaryň her biri özünə peýdaly, emma bir - birini ünsli diňleýän mahaly.
- Dokumenleriň San Seriýasy — Başdan başlap ýolgöterçilik — A Guide from ScratchÇünki her nutgyda: desgat, nutuk bilen çykyş etmek, habar bermegi, tabşyrylan bu çemedana hut şeýle - de boldy: adamlaryň sany dindeşlerine.
- Duýduryş we tassyklama merkezi — Başdan başlap ýol görkezijiGoşmaça maglumatda şeýle düşündirilmeýär: Baýyrlyk birmeňzeş görünmän galýar, soňra onuň haýyşyny bir ýerde amala aşyrýar HR.