Kandungan
Mencipta langgananPeristiwaKandungan pemberitahuanMengesahkan tandatanganPenghantaran, cuba semula dan surat matiLog penghantaran dan hantar semulaKunci penyulitan pelayanRingkasan titik akhir OpenAPIDi telefonWebhook 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
- Jabatan - Panduan daripada Scratch untuk Pejabat BelakangJendela ini tidak melakukan satu kerja; ia memegang Pengurusan jabatan yang berbeza Jangan risau: tiada siapa yang menggunakan semua sepuluh.
- Katalog integrasi: HNR bersambung kepada apa?Halaman ini mengumpulkan di satu tempat cara HNR bersambung dengan bank, syarikat kurier, pasaran dalam talian, pihak cukai, fail perakaunan dan program lain.
- Form Print - anda merancang apa yang berlaku pada kertasTarikh, invoice dan penerimaan tataletak digunakan untuk dikebumikan di dalam program; mengubah satu memerlukan pemaju. Sekarang awak Membina bentuk.
- Laluan Audit, Pintu Keselamatan dan AnomaliPanduan ini meliputi tiga lapisan pertahanan yang berasingan. Surat: yang pertama Rekod, Kedua berhenti, yang ketiga menunjukkan.
- Kumpulan Nombor Dokumen - Panduan daripada ScratchSetiap dokumen akhir - invois, nota penghantaran, pesanan, kutipan, penerimaan, cek - mempunyai nombor yang ditunjukkan kepada pelanggan.
- Pusat Pemberitahuan dan Kelulusan - Panduan daripada ScratchKerja menunggu kelulusan duduk dalam sepuluh sudut yang berbeza program: had kredit di satu tempat, invois sepadan perbezaan di yang lain.