Эчтәлеккә күчү
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.

Телефонда

Телефонда язылулар карточка булып күренә; яңа язылу өч адымда ачыла (Адрес, Вакыйгалар, Фильтр). Тапшыру журналы карточкалар исемлеге; һәр карточкада Җентекле һәм Кабат җибәрү төймәләре бар.

Бәйле кулланмалар