Luncat ka eusi
HNROS Puseur Bantosan
Basa Sunda
Mimitian gratis
Daptar eusiNgadamel langgananKajadianEusi béwaraMaluruh tandatanganPangiriman, cobian deui, sareng surat paéhLog pangiriman sareng kirim deuiKonci énkripsi serverRingkesan endpoint OpenAPIDina telepon

Webhook sareng OpenAPI: béwara kajadian ka sistem séjén

Nalika aya kajadian di HNR (faktur dicatet, pesenan dihapus, kiriman angkat…), webhook ngirim béwara HTTP anu ditandatanganan ka alamat anu ditetepkeun. Béwara ngan mawa ringkesan dokumén sareng tautan API-na; panarima maca catetan lengkep tina API ku sésina nyalira. Kaca ieu ngajelaskeun kontrak, sanés skéma resmi.

Ngadamel langganan

Setélan › Integrasi sareng webhook ngan kabuka pikeun administrator sistem. Langganan anyar butuh nami, alamat tujuan, sareng sahenteuna hiji kajadian. Alamat kedah dimimitian ku https; tujuan di jaringan lokal atanapi di komputer ieu (contona 192.168.x.x, localhost) ngan ditampi upami kotak persetujuan administrator dicentang. Langganan kadua pikeun alamat anu sami teu tiasa didamel.

Saringan pilihan: ngan kontak atanapi gudang tangtu. Upami saringan ditetepkeun sareng dokumén teu gaduh kolom éta, béwara henteu dikirim. Jumlah sareng mata uang dokumén ngan dikirim upami “Tambahkeun jumlah sareng mata uang dokumén kana béwara” dicentang.

Nalika disimpen, konci rusiah (dimimitian ku whsec_) ngan ditémbongkeun sakali; simpen dina sistem panarima. Disimpen kaénkripsi di server sareng teu tiasa dibaca deui. Upami leungit, jieun anu énggal ku “Énggalan konci”; tandatangan ku konci lami teu sah deui.

Kajadian

faktur, pesenan, panawaran (fatura, siparis, teklif): yazildi, degisti, silindi · surat jalan (irsaliye): yazildi, silindi · kuitansi (makbuz): yazildi, degisti, silindi · stok.hareket (transfer antar gudang dikirim, ditampi atanapi susut; persetujuan stok opname) · sevkiyat.durum (angkat, eureun ditampi, koréksi POD) · onay.karar · dof.acildi · servis.bilet (dibuka, status) · uretim.teyit (konfirmasi atanapi pembatalan). Kode kajadian aya dina header X-HNR-Event sareng kolom olay dina eusi; tombol uji ngirim test.ping.

Eusi béwara

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 mangrupikeun nomer dokumén final; catetan lengkep dibaca tina API ngalangkungan baglanti. tutar sareng doviz ngan aya dina langganan anu kalebet jumlah; tanpa doviz jumlah dina mata uang lokal pausahaan. Pikeun kajadian hapus, ringkesan dibaca saméméh dokumén dihapus. surum nyaéta vérsi format eusi: kolom anyar tiasa ditambah, kolom lami henteu robih.

Maluruh tandatangan

Unggal pamundut mawa header X-HNR-Event, X-HNR-Delivery (ID pangiriman), X-HNR-Timestamp, sareng X-HNR-Signature: t=…,v1=…. v1 nyaéta HMAC-SHA256 (héksadésimal) tina téks t + "." + eusi atah ku konci rusiah. Panarima kedah maluruh tandatangan ku babandingan waktos-konstan, nolak waktos langkung ti 5 menit, sareng henteu ngolah X-HNR-Delivery anu sami dua kali tapi tetep ngawaler 2xx (panyalindungan 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', ''))

Pangiriman, cobian deui, sareng surat paéh

HNR ngalakukeun POST ka alamat anjeun sareng ngantosan 10 detik; ngan waleran 2xx anu diitung kakirim sareng alihan henteu dituturkeun. Saatos cobian gagal, jeda sacara runtuy kirang langkung 1 mnt, 3 mnt, 11 mnt, 38 mnt, 2 jam, 7 jam, sareng 24 jam. Upami dalapan cobian gagal, pangiriman janten surat paéh. Béwara pikeun langganan sareng dokumén anu sami dikirim sacara runtuy: anu salajengna henteu dikirim saméméh pangiriman saméméhna réngsé. Per pausahaan paling seueur 4 pangiriman sakaligus.

Tanpa langganan server henteu ngirim nanaon. Pangiriman jalan unggal menit di pausahaan server nyalira; di pausahaan séjén jalan unggal aya transaksi anyar di pausahaan éta. Dina langganan anu dieureunkeun, béwara anu ngantosan tetep ngantosan sareng dikirim saatos diaktipkeun deui.

Log pangiriman sareng kirim deui

Log pangiriman némbongkeun status unggal béwara (ngantosan, kakirim, surat paéh), jumlah cobian, sareng kode HTTP pamungkas; rinciana ngamuat eusi anu dikirim, 1 KB munggaran réspon, sareng unggal cobian. “Kirim deui” langsung ngirim béwara sakali deui ku ID pangiriman anu sami; upami gagal, aturan cobian deui dimimitian ti awal. Catetan henteu kantos dihapus. “Kirim uji” ngirim kajadian test.ping ka alamat langganan.

Konci énkripsi server

Konci rusiah disimpen ku AES-256-GCM nganggo konci énkripsi server anu sami sareng sambungan bank langsung (HNR_BANKA_KIMLIK_ANAHTARI). Upami konci ieu teu acan ditetepkeun, langganan teu tiasa disimpen. Upami konci robih, konci rusiah anu disimpen teu tiasa didékripsi sareng unggal langganan peryogi “Énggalan konci”.

Ringkesan endpoint OpenAPI

GET /api/openapi.json (atanapi tombol unduh di bagian Integrasi) ngadaptarkeun sadaya endpoint API anu dibuka ku server ayeuna, kalayan path, métode, sareng labél modul. Eusi pamundut sareng réspon henteu didokuméntasikeun: ieu ringkesan endpoint, sanés skéma resmi. Autentikasi: konci API Authorization: Bearer sareng X-Oturum-Token.

Dina telepon

Dina telepon, langganan némbongan salaku kartu; langganan anyar didamel dina tilu léngkah (Alamat, Kajadian, Saringan). Log pangiriman mangrupi daptar kartu; unggal kartu gaduh tombol Rincian sareng Kirim deui.

Pituduh nu patali