Dhaftar isi
Nggawe langgananKedadeyanIsi kabarVerifikasi tandha tanganPangiriman, nyoba maneh, lan layang matiLog pangiriman lan kirim manehKunci enkripsi serverRingkesan endpoint OpenAPIIng teleponWebhook lan OpenAPI: kabar kedadeyan menyang sistem liya
Nalika ana kedadeyan ing HNR (faktur dicathet, pesenan dibusak, kiriman mangkat…), webhook ngirim kabar HTTP sing ditandatangani menyang alamat sing ditetepake. Kabar mung nggawa ringkesan dokumen lan tautan API-ne; panampa maca cathetan lengkap saka API nganggo sesine dhewe. Kaca iki nerangake kontrak, dudu skema resmi.
Nggawe langganan
Setelan › Integrasi lan webhook mung kanggo administrator sistem. Langganan anyar butuh jeneng, alamat tujuan, lan paling ora siji kedadeyan. Alamat kudu diwiwiti https; tujuan ing jaringan lokal utawa ing komputer iki (upamane 192.168.x.x, localhost) mung ditampa yen kothak persetujuan administrator dicenthang. Langganan kapindho kanggo alamat sing padha ora bisa digawe.
Saringan pilihan: mung kontak utawa gudang tartamtu. Yen saringan ditetepake lan dokumen ora duwe kolom kuwi, kabar ora dikirim. Jumlah lan mata uang dokumen mung dikirim yen “Tambahake jumlah lan mata uang dokumen menyang kabar” dicenthang.
Nalika disimpen, kunci rahasia (diwiwiti whsec_) mung ditampilake sapisan; simpen ing sistem panampa. Disimpen kanthi enkripsi ing server lan ora bisa diwaca maneh. Yen ilang, gawe sing anyar nganggo “Anyarake kunci”; tandha tangan nganggo kunci lawas ora sah maneh.
Kedadeyan
faktur, pesenan, penawaran (fatura, siparis, teklif): yazildi, degisti, silindi · surat jalan (irsaliye): yazildi, silindi · kuitansi (makbuz): yazildi, degisti, silindi · stok.hareket (transfer antar gudang dikirim, ditampa utawa susut; persetujuan stok opname) · sevkiyat.durum (mangkat, mandheg ditampa, koreksi POD) · onay.karar · dof.acildi · servis.bilet (dibukak, status) · uretim.teyit (konfirmasi utawa pembatalan). Kode kedadeyan ana ing header X-HNR-Event lan kolom olay ing isi; tombol uji ngirim test.ping.
Isi kabar
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 yaiku nomer dokumen final; cathetan lengkap diwaca saka API liwat baglanti. tutar lan doviz mung ana ing langganan sing kalebu jumlah; tanpa doviz jumlah ing mata uang lokal perusahaan. Kanggo kedadeyan busak, ringkesan diwaca sadurunge dokumen dibusak. surum yaiku versi format isi: kolom anyar bisa ditambah, kolom lawas ora owah.
Verifikasi tandha tangan
Saben panjaluk nggawa header X-HNR-Event, X-HNR-Delivery (ID pangiriman), X-HNR-Timestamp, lan X-HNR-Signature: t=…,v1=…. v1 yaiku HMAC-SHA256 (heksadesimal) saka teks t + "." + isi mentah nganggo kunci rahasia. Panampa kudu verifikasi tandha tangan kanthi bandhingan wektu-konstan, nolak wektu luwih saka 5 menit, lan ora ngolah X-HNR-Delivery sing padha kaping pindho nanging tetep mangsuli 2xx (pangreksan baleni).
// 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', '')) Pangiriman, nyoba maneh, lan layang mati
HNR nindakake POST menyang alamat sampeyan lan ngenteni 10 detik; mung wangsulan 2xx sing diétung wis dikirim lan pangalihan ora dituruti. Sawise cobanan gagal, jeda urut-urutan kira-kira 1 mnt, 3 mnt, 11 mnt, 38 mnt, 2 jam, 7 jam, lan 24 jam. Yen wolung cobanan gagal, pangiriman dadi layang mati. Kabar kanggo langganan lan dokumen sing padha dikirim urut: sing sabanjure ora dikirim sadurunge pangiriman sadurunge rampung. Saben perusahaan paling akeh 4 pangiriman bebarengan.
Tanpa langganan server ora ngirim apa-apa. Pangiriman mlaku saben menit ing perusahaan server dhewe; ing perusahaan liya mlaku saben ana transaksi anyar ing perusahaan kuwi. Ing langganan sing dimandhegake, kabar sing ngenteni tetep ngenteni lan dikirim sawise diaktifake maneh.
Log pangiriman lan kirim maneh
Log pangiriman nuduhake status saben kabar (ngenteni, wis dikirim, layang mati), cacahing cobanan, lan kode HTTP pungkasan; rinciane ngemot isi sing dikirim, 1 KB kapisan wangsulan, lan saben cobanan. “Kirim maneh” langsung ngirim kabar sapisan maneh nganggo ID pangiriman sing padha; yen gagal, aturan nyoba maneh diwiwiti saka awal. Cathetan ora tau dibusak. “Kirim uji” ngirim kedadeyan test.ping menyang alamat langganan.
Kunci enkripsi server
Kunci rahasia disimpen nganggo AES-256-GCM kanthi kunci enkripsi server sing padha karo sambungan bank langsung (HNR_BANKA_KIMLIK_ANAHTARI). Yen kunci iki durung ditetepake, langganan ora bisa disimpen. Yen kunci owah, kunci rahasia sing disimpen ora bisa didekripsi lan saben langganan butuh “Anyarake kunci”.
Ringkesan endpoint OpenAPI
GET /api/openapi.json (utawa tombol unduh ing bagean Integrasi) nyathet kabeh endpoint API sing dibukak server saiki, kanthi path, metode, lan label modul. Isi panjaluk lan wangsulan ora didokumentasikake: iki ringkesan endpoint, dudu skema resmi. Autentikasi: kunci API Authorization: Bearer lan X-Oturum-Token.
Ing telepon
Ing telepon, langganan katon minangka kertu; langganan anyar digawe ing telung langkah (Alamat, Kedadeyan, Saringan). Log pangiriman awujud dhaptar kertu; saben kertu duwe tombol Rincian lan Kirim maneh.
Pandhuan sing gegandhengan
- Departemèn — Pandhuan saka Nol kanggo Kantor MburiJendhéla iki ora nglakoni siji gawéan; dhèwèké nyekel buku saka sepuluh departemèn sing béda bebarengan. Aja wedi: ora ana sing nganggo kabèh sepuluh.
- Katalog integrasi: HNR nyambung dhateng punapa kémawon?Kaca punika nglempakaken ing satunggal panggènan kados pundi HNR nyambung dhateng bank, jasa kirim, marketplace, kantor pajeg, berkas akuntansi.
- Formulir Cetak — panjenengan sing ngrancang isiné kertasBiyèn tata létak penawaran, faktur, lan kuitansi kepenthok ing njero program; ngowahi kudu programer. Saiki panjenengan sing nyusun formulir.
- Tapak Audit, Gerbang Keamanan, lan AnomaliPandhuan iki ngrembug telung lapis pertahanan sing béda. Cekaké: sing kapisan nyathet, sing kapindho mandhegaké, sing katelu nuduhaké.
- Seri Nomer Dokumèn — Pandhuan saka NolSaben dokumèn final — faktur, surat jalan, pesenan, penawaran, kuitansi, dhaptar cek — duwé nomer sing dituduhaké marang pelanggan, akuntan, lan kantor pajeg.
- Pusat Kabar lan Persetujuan — Pandhuan saka NolGawéan sing ngenteni persetujuan ana ing sepuluh pojok program: limit kredit ing siji panggonan, bedané nyocogaké faktur ing panggonan liya.