Daftar isi
Membuat langgananPeristiwaIsi notifikasiMemverifikasi tanda tanganPengiriman, percobaan ulang, dan surat matiLog pengiriman dan kirim ulangKunci enkripsi serverRingkasan endpoint OpenAPIDi ponselWebhook dan OpenAPI: notifikasi peristiwa ke sistem lain
Saat terjadi peristiwa di HNR (faktur dicatat, pesanan dihapus, pengiriman berangkat…), webhook mengirim notifikasi HTTP bertanda tangan ke alamat yang Anda tetapkan. Notifikasi hanya membawa ringkasan dokumen dan tautan API-nya; penerima membaca catatan lengkap dari API dengan sesinya sendiri. Halaman ini menjelaskan kontrak, bukan skema resmi.
Membuat langganan
Pengaturan › Integrasi dan webhook hanya terbuka bagi administrator sistem. Langganan baru memerlukan nama, alamat tujuan, dan minimal satu peristiwa. Alamat harus diawali https; tujuan di jaringan lokal atau di komputer ini (mis. 192.168.x.x, localhost) hanya diterima bila kotak persetujuan administrator dicentang. Langganan kedua untuk alamat yang sama tidak dapat dibuat.
Filter opsional: hanya kontak atau gudang tertentu. Jika filter ditetapkan dan dokumen tidak memiliki kolom itu, notifikasi tidak dikirim. Jumlah dan mata uang dokumen hanya dikirim bila “Tambahkan jumlah dan mata uang dokumen ke notifikasi” dicentang.
Saat disimpan, kunci rahasia (diawali whsec_) hanya ditampilkan sekali; simpan di sistem penerima. Kunci disimpan terenkripsi di server dan tidak dapat dibaca lagi. Jika hilang, buat yang baru dengan “Perbarui kunci”; tanda tangan dengan kunci lama tidak lagi valid.
Peristiwa
faktur, pesanan, penawaran (fatura, siparis, teklif): yazildi, degisti, silindi · surat jalan (irsaliye): yazildi, silindi · kuitansi (makbuz): yazildi, degisti, silindi · stok.hareket (transfer antar gudang dikirim, diterima atau susut; persetujuan stok opname) · sevkiyat.durum (berangkat, perhentian diterima, koreksi POD) · onay.karar · dof.acildi · servis.bilet (dibuka, status) · uretim.teyit (konfirmasi atau pembatalan). Kode peristiwa ada di header X-HNR-Event dan di kolom olay pada isi; tombol uji mengirim test.ping.
Isi notifikasi
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 adalah nomor dokumen final; catatan lengkap dibaca dari API lewat baglanti. tutar dan doviz hanya ada pada langganan yang menyertakan jumlah; tanpa doviz jumlah dalam mata uang lokal perusahaan. Untuk peristiwa hapus, ringkasan dibaca sebelum dokumen dihapus. surum adalah versi format muatan: kolom baru bisa ditambah, kolom lama tidak berubah.
Memverifikasi tanda tangan
Setiap permintaan membawa header X-HNR-Event, X-HNR-Delivery (ID pengiriman), X-HNR-Timestamp, dan X-HNR-Signature: t=…,v1=…. v1 adalah HMAC-SHA256 (heksadesimal) dari teks t + "." + isi mentah dengan kunci rahasia. Penerima sebaiknya memverifikasi tanda tangan dengan perbandingan waktu-konstan, menolak waktu lebih dari 5 menit, dan tidak memproses X-HNR-Delivery yang sama dua kali namun tetap menjawab 2xx (perlindungan pengulangan).
// 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', '')) Pengiriman, percobaan ulang, dan surat mati
HNR melakukan POST ke alamat Anda dan menunggu 10 detik; hanya jawaban 2xx yang dihitung terkirim dan pengalihan tidak diikuti. Setelah percobaan gagal, jeda berturut-turut sekitar 1 mnt, 3 mnt, 11 mnt, 38 mnt, 2 jam, 7 jam, dan 24 jam. Jika delapan percobaan gagal, pengiriman menjadi surat mati. Notifikasi untuk langganan dan dokumen yang sama dikirim berurutan: yang berikutnya tidak dikirim sebelum pengiriman sebelumnya selesai. Per perusahaan paling banyak 4 pengiriman berjalan bersamaan.
Tanpa langganan server tidak mengirim apa pun. Pengiriman berjalan tiap menit di perusahaan milik server; di perusahaan lain berjalan setiap ada transaksi baru di perusahaan itu. Pada langganan yang dihentikan, notifikasi tertunda menunggu dan dikirim setelah diaktifkan kembali.
Log pengiriman dan kirim ulang
Log pengiriman menampilkan status setiap notifikasi (menunggu, terkirim, surat mati), jumlah percobaan, dan kode HTTP terakhir; rinciannya memuat isi yang dikirim, 1 KB pertama respons, dan setiap percobaan. “Kirim ulang” langsung mengirim notifikasi sekali lagi dengan ID pengiriman yang sama; jika gagal, aturan percobaan ulang dimulai dari awal. Catatan tidak pernah dihapus. “Kirim uji” mengirim peristiwa test.ping ke alamat langganan.
Kunci enkripsi server
Kunci rahasia disimpan dengan AES-256-GCM memakai kunci enkripsi server yang sama dengan koneksi bank langsung (HNR_BANKA_KIMLIK_ANAHTARI). Jika kunci ini belum ditetapkan, langganan tidak dapat disimpan. Jika kunci berubah, kunci rahasia tersimpan tidak dapat didekripsi dan setiap langganan perlu “Perbarui kunci”.
Ringkasan endpoint OpenAPI
GET /api/openapi.json (atau tombol unduh di bagian Integrasi) mencantumkan semua endpoint API yang sedang dibuka server, dengan path, metode, dan label modul. Isi permintaan dan respons tidak didokumentasikan: ini ringkasan endpoint, bukan skema resmi. Autentikasi: kunci API Authorization: Bearer dan X-Oturum-Token.
Di ponsel
Di ponsel, langganan tampil sebagai kartu; langganan baru dibuat dalam tiga langkah (Alamat, Peristiwa, Filter). Log pengiriman berupa daftar kartu; setiap kartu punya tombol Detail dan Kirim ulang.
Panduan terkait
- Departemen — Panduan dari Nol untuk Kantor BelakangJendela ini tidak mengerjakan satu hal; ia menyimpan buku dari sepuluh departemen berbeda berdampingan. Jangan cemas: tak seorang pun memakai kesepuluhnya.
- Katalog integrasi: HNR terhubung ke apa saja?Halaman ini mengumpulkan di satu tempat bagaimana HNR terhubung ke bank, jasa kirim, marketplace, kantor pajak, berkas akuntansi, dan program lain.
- Formulir Cetak — Anda yang merancang isi kertasDulu tata letak penawaran, faktur, dan kuitansi tertanam di dalam program; mengubahnya butuh pemrogram. Sekarang Anda yang menyusun formulir.
- Jejak Audit, Gerbang Keamanan, dan AnomaliPanduan ini membahas tiga lapis pertahanan yang berbeda. Singkatnya: yang pertama mencatat, yang kedua menghentikan, yang ketiga menunjukkan.
- Seri Nomor Dokumen — Panduan dari NolSetiap dokumen final — faktur, surat jalan, pesanan, penawaran, kuitansi, daftar cek — memiliki nomor yang ditunjukkan kepada pelanggan, akuntan.
- Pusat Notifikasi dan Persetujuan — Panduan dari NolPekerjaan yang menunggu persetujuan tersebar di sepuluh sudut program: limit kredit di satu tempat, selisih pencocokan faktur di tempat lain.