跳到正文
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(投递 ID)、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 以及每次尝试。“重新发送”会立即以相同的投递 ID 再发送一次;若失败,重试规则从头开始。记录不会被删除。“发送测试”向订阅地址发送 test.ping 事件。

服务器加密密钥

签名密钥使用与实时银行连接相同的服务器加密密钥(HNR_BANKA_KIMLIK_ANAHTARI)以 AES-256-GCM 保存。未定义该密钥时无法保存订阅。密钥变更后已保存的签名密钥无法解密,每个订阅都需要“更新密钥”。

OpenAPI 端点摘要

GET /api/openapi.json(或集成部分的下载按钮)列出服务器当前开放的所有 API 端点,包括路径、方法和模块标签。不记录请求和响应正文:这是端点摘要,不是官方模式。认证:Authorization: Bearer API 密钥和 X-Oturum-Token。

在手机上

在手机上,订阅以卡片显示;新订阅分三步创建(地址、事件、筛选)。投递日志是卡片列表;每张卡片都有“详情”和“重新发送”按钮。

相关指南