Mục lục
Tạ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ạiWebhook 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
- Các bộ phận — Một hướng dẫn từ Scratch cho văn phòng saucửa sổ này không làm một công việc; nó giữ Các bộ phận của bộ phận khác nhau Đừng lo lắng: không ai sử dụng tất cả mười.
- Danh mục tích hợp: HNR kết nối với những gì?Trang này tập hợp ở một nơi cách HNR kết nối với ngân hàng, hãng vận chuyển, sàn thương mại điện tử, cơ quan thuế, tệp kế toán và các chương trình khác.
- Hình thức in - bạn thiết kế những gì đang diễn ra trên giấyCác bản ghi, hóa đơn và các bố trí nhận được sử dụng để được chôn cất bên trong chương trình; thay đổi một yêu cầu một nhà phát triển.
- Đường kiểm toán, cổng an ninh và bất thườngHướng dẫn này bao gồm ba lớp phòng thủ riêng biệt. Tập ngắn: đầu tiên hồ sơ, Thứ hai dừng, Thứ ba show. Mỗi người đều hữu ích cho riêng mình.
- Số tài liệu Series — A Guide from ScratchMỗi tài liệu cuối cùng - hóa đơn, ghi nhận giao hàng, đặt hàng, đề xuất, nhận, thanh toán - có một số được hiển thị cho khách hàng, kế toán và văn phòng thuế.
- Trung tâm thông báo và phê duyệt - Một hướng dẫn từ ScratchCông việc chờ đợi sự chấp thuận ngồi trong mười góc khác nhau của chương trình: giới hạn tín dụng ở một nơi, hóa đơn phù hợp với sự khác biệt ở nơi khác.