Langkau ke kandungan
HNROS Pusat Bantuan
Bahasa Melayu
Mula percuma
KandunganMencipta langgananPeristiwaKandungan pemberitahuanMengesahkan tandatanganPenghantaran, cuba semula dan surat matiLog penghantaran dan hantar semulaKunci penyulitan pelayanRingkasan titik akhir OpenAPIDi telefon

Webhook dan OpenAPI: pemberitahuan peristiwa kepada sistem lain

Apabila berlaku peristiwa dalam HNR (invois direkod, pesanan dipadam, penghantaran bertolak…), webhook menghantar pemberitahuan HTTP bertandatangan ke alamat yang anda tetapkan. Ia hanya membawa ringkasan dokumen dan pautan API-nya; penerima membaca rekod penuh daripada API dengan sesinya sendiri. Halaman ini menerangkan kontrak, bukan skema rasmi.

Mencipta langganan

Tetapan › Integrasi dan webhook hanya terbuka kepada pentadbir sistem. Langganan baharu memerlukan nama, alamat sasaran dan sekurang-kurangnya satu peristiwa. Alamat mesti bermula dengan https; sasaran dalam rangkaian setempat atau pada komputer ini (cth. 192.168.x.x, localhost) hanya diterima jika kotak kelulusan pentadbir ditanda. Langganan kedua untuk alamat yang sama tidak boleh dicipta.

Penapis pilihan: hanya akaun atau gudang tertentu. Jika penapis ditetapkan dan dokumen tiada medan itu, pemberitahuan tidak dihantar. Jumlah dan mata wang dokumen hanya dihantar jika “Tambah jumlah dan mata wang dokumen pada pemberitahuan” ditanda.

Semasa disimpan, kunci rahsia (bermula dengan whsec_) hanya dipaparkan sekali; simpan dalam sistem penerima. Ia disimpan tersulit pada pelayan dan tidak boleh dibaca semula. Jika hilang, jana yang baharu dengan “Baharui kunci”; tandatangan dengan kunci lama tidak lagi sah.

Peristiwa

invois, pesanan, sebut harga (fatura, siparis, teklif): yazildi, degisti, silindi · nota hantaran (irsaliye): yazildi, silindi · resit (makbuz): yazildi, degisti, silindi · stok.hareket (pindahan antara gudang dihantar, diterima atau susut; kelulusan kiraan) · sevkiyat.durum (bertolak, hentian diserahkan, pembetulan POD) · onay.karar · dof.acildi · servis.bilet (dibuka, status) · uretim.teyit (pengesahan atau pembatalan). Kod peristiwa terdapat dalam pengepala X-HNR-Event dan medan olay kandungan; butang ujian menghantar test.ping.

Kandungan pemberitahuan

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 ialah nombor dokumen muktamad; rekod penuh dibaca daripada API melalui baglanti. tutar dan doviz hanya ada pada langganan yang menyertakan jumlah; tanpa doviz jumlah dalam mata wang tempatan syarikat. Bagi peristiwa padam, ringkasan dibaca sebelum dokumen dipadam. surum ialah versi format muatan: medan baharu boleh ditambah, medan sedia ada tidak berubah.

Mengesahkan tandatangan

Setiap permintaan membawa pengepala X-HNR-Event, X-HNR-Delivery (ID penghantaran), X-HNR-Timestamp dan X-HNR-Signature: t=…,v1=…. v1 ialah HMAC-SHA256 (heks) bagi teks t + "." + kandungan mentah dengan kunci rahsia. Penerima patut mengesahkan tandatangan dengan perbandingan masa malar, menolak cap masa lebih 5 minit dan tidak memproses X-HNR-Delivery yang sama dua kali tetapi masih membalas 2xx (perlindungan ulangan).

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

Penghantaran, cuba semula dan surat mati

HNR menghantar POST ke alamat anda dan menunggu 10 saat; hanya jawapan 2xx dikira dihantar dan ubah hala tidak diikuti. Selepas cubaan gagal, tempoh menunggu lebih kurang 1 min, 3 min, 11 min, 38 min, 2 jam, 7 jam dan 24 jam. Jika kelapan-lapan cubaan gagal, penghantaran menjadi surat mati. Pemberitahuan bagi langganan dan dokumen yang sama dihantar mengikut urutan: yang seterusnya tidak dihantar sebelum yang terdahulu selesai. Paling banyak 4 penghantaran serentak bagi setiap syarikat.

Tanpa langganan pelayan tidak menghantar apa-apa. Penghantaran berjalan setiap minit dalam syarikat pelayan sendiri; dalam syarikat lain, setiap kali ada urusan baharu dalam syarikat itu. Bagi langganan yang dihentikan, pemberitahuan tertunggak menunggu dan dihantar setelah diaktifkan semula.

Log penghantaran dan hantar semula

Log penghantaran menunjukkan status setiap pemberitahuan (menunggu, dihantar, surat mati), bilangan cubaan dan kod HTTP terakhir; butiran menyenaraikan kandungan yang dihantar, 1 KB pertama respons dan setiap cubaan. “Hantar semula” menghantar pemberitahuan sekali lagi serta-merta dengan ID penghantaran yang sama; jika gagal, peraturan cuba semula bermula semula. Rekod tidak pernah dipadam. “Hantar ujian” menghantar peristiwa test.ping ke alamat langganan.

Kunci penyulitan pelayan

Kunci rahsia disimpan dengan AES-256-GCM di bawah kunci penyulitan pelayan yang sama dengan sambungan bank langsung (HNR_BANKA_KIMLIK_ANAHTARI). Jika kunci ini tidak ditetapkan, langganan tidak boleh disimpan. Jika kunci berubah, kunci rahsia tersimpan tidak dapat dinyahsulit dan setiap langganan perlu “Baharui kunci”.

Ringkasan titik akhir OpenAPI

GET /api/openapi.json (atau butang muat turun dalam bahagian Integrasi) menyenaraikan semua titik akhir API yang dibuka pelayan pada masa itu, dengan laluan, kaedah dan label modul. Kandungan permintaan dan respons tidak didokumenkan: ini ringkasan titik akhir, bukan skema rasmi. Pengesahan: kunci API Authorization: Bearer dan X-Oturum-Token.

Di telefon

Di telefon, langganan dipaparkan sebagai kad; langganan baharu dicipta dalam tiga langkah (Alamat, Peristiwa, Penapis). Log penghantaran ialah senarai kad; setiap kad mempunyai butang Butiran dan Hantar semula.

Panduan berkaitan