Chuyển đến nội dung
HNROS Trung tâm trợ giúp
Tiếng Việt
Bắt đầu miễn phí
Mục lụcTạo đăng kýSự kiệnNội dung thông báoXác minh chữ kýGửi, thử lại và thư chếtNhật ký gửi và gửi lạiKhóa mã hóa máy chủTóm tắt điểm cuối OpenAPITrên điện thoại

Webhook và OpenAPI: thông báo sự kiện tới hệ thống khác

Khi có sự kiện trong HNR (ghi hóa đơn, xóa đơn hàng, chuyến hàng xuất phát…), webhook gửi thông báo HTTP có chữ ký đến địa chỉ bạn đặt. Thông báo chỉ mang tóm tắt chứng từ và liên kết API; bên nhận đọc bản ghi đầy đủ từ API bằng phiên của mình. Trang này mô tả một hợp đồng, không phải lược đồ chính thức.

Tạo đăng ký

Cài đặt › Tích hợp và webhook chỉ dành cho quản trị viên hệ thống. Đăng ký mới cần tên, địa chỉ đích và ít nhất một sự kiện. Địa chỉ phải bắt đầu bằng https; đích trong mạng cục bộ hoặc trên máy này (vd. 192.168.x.x, localhost) chỉ được chấp nhận khi đánh dấu ô phê duyệt của quản trị viên. Không thể tạo đăng ký thứ hai cho cùng địa chỉ.

Bộ lọc tùy chọn: chỉ một số đối tác hoặc kho. Nếu có bộ lọc mà chứng từ không có trường đó thì không gửi thông báo. Số tiền và loại tiền chỉ được gửi khi đánh dấu “Thêm số tiền và loại tiền của chứng từ vào thông báo”.

Khi lưu, khóa bí mật ký (bắt đầu bằng whsec_) chỉ hiển thị một lần; hãy lưu vào hệ thống nhận. Khóa được mã hóa trên máy chủ và không thể đọc lại. Nếu mất, tạo khóa mới bằng “Làm mới khóa”; chữ ký bằng khóa cũ không còn hợp lệ.

Sự kiện

hóa đơn, đơn hàng, báo giá (fatura, siparis, teklif): yazildi, degisti, silindi · phiếu giao hàng (irsaliye): yazildi, silindi · phiếu thu chi (makbuz): yazildi, degisti, silindi · stok.hareket (chuyển kho đã xuất, đã nhận hoặc hao hụt; duyệt kiểm kê) · sevkiyat.durum (xuất phát, giao tại điểm dừng, sửa POD) · onay.karar · dof.acildi · servis.bilet (mở, trạng thái) · uretim.teyit (xác nhận hoặc hủy). Mã sự kiện nằm ở tiêu đề X-HNR-Event và trường olay của nội dung; nút thử gửi test.ping.

Nội dung thông báo

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 là số chứng từ chính thức; bản ghi đầy đủ đọc từ API qua baglanti. tutar và doviz chỉ có ở đăng ký kèm số tiền; không có doviz thì số tiền theo đồng nội tệ của công ty. Với sự kiện xóa, tóm tắt được đọc trước khi xóa chứng từ. surum là phiên bản định dạng: có thể thêm trường mới, trường hiện có không đổi.

Xác minh chữ ký

Mỗi yêu cầu có các tiêu đề X-HNR-Event, X-HNR-Delivery (mã lần gửi), X-HNR-Timestamp và X-HNR-Signature: t=…,v1=…. v1 là HMAC-SHA256 (hex) của chuỗi t + "." + nội dung gốc với khóa bí mật. Bên nhận nên xác minh chữ ký bằng so sánh thời gian hằng, từ chối dấu thời gian cũ hơn 5 phút và không xử lý hai lần cùng X-HNR-Delivery nhưng vẫn trả 2xx (chống phát lại).

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

Gửi, thử lại và thư chết

HNR gửi POST tới địa chỉ của bạn và chờ 10 giây; chỉ phản hồi 2xx mới tính là đã gửi và không theo chuyển hướng. Sau lần thử thất bại, thời gian chờ lần lượt khoảng 1 phút, 3 phút, 11 phút, 38 phút, 2 giờ, 7 giờ và 24 giờ. Nếu cả tám lần đều thất bại, lần gửi thành thư chết. Thông báo của cùng đăng ký và cùng chứng từ đi theo thứ tự: lần sau không gửi trước khi lần trước xong. Mỗi công ty tối đa 4 lần gửi đồng thời.

Không có đăng ký thì máy chủ không gửi gì. Việc gửi chạy mỗi phút ở công ty của chính máy chủ; ở công ty khác, chạy mỗi khi có giao dịch mới trong công ty đó. Với đăng ký đã dừng, các thông báo chờ sẽ đợi và được gửi khi bật lại.

Nhật ký gửi và gửi lại

Nhật ký gửi hiển thị trạng thái mỗi thông báo (chờ, đã gửi, thư chết), số lần thử và mã HTTP cuối; phần chi tiết liệt kê nội dung đã gửi, 1 KB đầu của phản hồi và từng lần thử. “Gửi lại” gửi ngay thêm một lần với cùng mã lần gửi; nếu thất bại, quy tắc thử lại bắt đầu từ đầu. Bản ghi không bao giờ bị xóa. “Gửi thử” gửi sự kiện test.ping đến địa chỉ đăng ký.

Khóa mã hóa máy chủ

Khóa bí mật ký được lưu bằng AES-256-GCM với cùng khóa mã hóa máy chủ như kết nối ngân hàng trực tiếp (HNR_BANKA_KIMLIK_ANAHTARI). Nếu chưa định nghĩa khóa này thì không thể lưu đăng ký. Nếu khóa thay đổi, các khóa bí mật đã lưu không giải mã được và mỗi đăng ký cần “Làm mới khóa”.

Tóm tắt điểm cuối OpenAPI

GET /api/openapi.json (hoặc nút tải xuống trong mục Tích hợp) liệt kê mọi điểm cuối API máy chủ đang mở, kèm đường dẫn, phương thức và nhãn mô-đun. Nội dung yêu cầu và phản hồi không được mô tả: đây là bản tóm tắt điểm cuối, không phải lược đồ chính thức. Xác thực: khóa API Authorization: Bearer và X-Oturum-Token.

Trên điện thoại

Trên điện thoại, đăng ký hiển thị dạng thẻ; đăng ký mới được tạo trong ba bước (Địa chỉ, Sự kiện, Bộ lọc). Nhật ký gửi là danh sách thẻ; mỗi thẻ có nút Chi tiết và Gửi lại.

Hướng dẫn liên quan