İçeriğe geç
HNROS Yardım Merkezi
Türkçe
Ücretsiz başla
İçindekilerAbonelik açmakOlaylarBildirimin içeriğiİmzayı doğrulamakTeslim, yeniden deneme ve ölü mektupTeslim günlüğü ve yeniden gönderSunucu şifreleme anahtarıOpenAPI uç özetiTelefonda

Webhook ve OpenAPI: başka sistemlere olay bildirimi

Webhook, HNR'de bir olay olduğunda (fatura yazıldı, sipariş silindi, sevkiyat yola çıktı…) belirlediğiniz adrese imzalı bir HTTP bildirimi gönderir. Bildirim yalnız belgenin özetini ve API bağlantısını taşır; alıcı tam kaydı kendi oturumuyla API'den okur. Bu sayfa bir sözleşme açıklamasıdır, resmî bir şema değildir.

Abonelik açmak

Ayarlar › Entegrasyon ve webhook'lar bölümü yalnız sistem yöneticisine açıktır. Yeni abonelikte bir ad, hedef adres ve en az bir olay seçilir. Adres https ile başlamalıdır; yerel ağdaki ya da bu bilgisayardaki bir hedef (ör. 192.168.x.x, localhost) ancak yönetici onayı kutusu işaretlenirse kabul edilir. Aynı adres için ikinci abonelik açılamaz.

İsteğe bağlı süzgeçler: yalnız belirli cariler ya da depolar. Süzgeç tanımlıysa ve belgede o alan yoksa bildirim gönderilmez. Belge tutarı ve dövizi yalnız “Belge tutarını ve dövizini bildirime ekle” işaretliyse gönderilir.

Kaydedince gizli anahtar (whsec_ ile başlar) yalnız bir kez gösterilir; alıcı sisteme kaydedin. Sunucuda şifreli saklanır ve bir daha okunamaz. Kaybederseniz “Anahtarı yenile” ile yenisini üretin; eski anahtarla imza artık doğrulanmaz.

Olaylar

fatura, sipariş, teklif: yazildi, degisti, silindi · irsaliye: yazildi, silindi · makbuz: yazildi, degisti, silindi · stok.hareket (depolar arası transfer sevki, teslimi ya da firesi; sayım onayı) · sevkiyat.durum (yola çıkış, durak teslimi, POD düzeltmesi) · onay.karar · dof.acildi · servis.bilet (açıldı, durum) · uretim.teyit (teyit ya da iptal). Olay kodu X-HNR-Event başlığında ve gövdenin olay alanındadır; test düğmesi test.ping gönderir.

Bildirimin içeriği

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 kesin belge numarasıdır; baglanti ile tam kayıt API'den okunur. tutar ve doviz yalnız tutar dâhil aboneliklerde gelir; doviz yoksa tutar firmanın yerel parasıdır. Silme olayında özet, belge silinmeden önce okunur. surum yük biçiminin sürümüdür: yeni alan eklenebilir, var olan alan değişmez.

İmzayı doğrulamak

Her istekte X-HNR-Event, X-HNR-Delivery (teslim kimliği), X-HNR-Timestamp ve X-HNR-Signature: t=…,v1=… başlıkları gelir. v1, gizli anahtarla t + "." + ham gövde metninin HMAC-SHA256 özetidir (onaltılık). Alıcı imzayı sabit zamanlı karşılaştırmayla doğrulamalı, 5 dakikadan eski zamanı reddetmeli ve aynı X-HNR-Delivery değerini ikinci kez işlememeli; ama yine 2xx dönmelidir (tekrar koruması).

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

Teslim, yeniden deneme ve ölü mektup

HNR adresinize POST eder ve 10 saniye bekler; yalnız 2xx yanıt teslim sayılır, yönlendirme izlenmez. Başarısız denemeden sonraki bekleme sırasıyla yaklaşık 1 dk, 3 dk, 11 dk, 38 dk, 2 sa, 7 sa ve 24 sa'tir. Sekiz deneme de başarısızsa teslim ölü mektuba düşer. Aynı abonelik ve aynı belge için bildirimler sırayla gider: önceki teslim bitmeden sonraki gönderilmez. Firma başına aynı anda en çok 4 gönderim yapılır.

Abonelik yoksa sunucu hiçbir şey göndermez. Gönderim sunucunun kendi firmasında dakikada bir; öteki firmalarda o firmada yeni bir işlem yapıldığında çalışır. Durdurulan abonelikte bekleyen bildirimler bekler, yeniden etkinleştirilince gider.

Teslim günlüğü ve yeniden gönder

Teslim günlüğü her bildirimin durumunu (bekliyor, teslim edildi, ölü mektup), deneme sayısını ve son HTTP kodunu gösterir; ayrıntıda gönderilen gövde, yanıtın ilk 1 KB'ı ve her deneme listelenir. “Yeniden gönder” bildirimi aynı teslim kimliğiyle hemen bir kez daha gönderir; başarısızsa yeniden deneme kuralı baştan işler. Kayıtlar silinmez. “Test gönder” abonelik adresine test.ping olayı yollar.

Sunucu şifreleme anahtarı

Gizli anahtarlar, canlı banka bağlantısıyla aynı sunucu şifreleme anahtarıyla (HNR_BANKA_KIMLIK_ANAHTARI) AES-256-GCM ile saklanır. Bu anahtar tanımlı değilse abonelik kaydedilemez. Anahtar değişirse kayıtlı gizli anahtarlar çözülemez; her abonelikte “Anahtarı yenile” gerekir.

OpenAPI uç özeti

GET /api/openapi.json (ya da Entegrasyon bölümündeki indirme düğmesi) sunucunun o anda açık bütün API uçlarını yol, yöntem ve modül etiketiyle listeler. İstek ve yanıt gövdeleri belgelenmez: bu bir uç özetidir, resmî şema değildir. Kimlik: Authorization: Bearer API anahtarı ve X-Oturum-Token.

Telefonda

Telefonda abonelikler kart olarak görünür; yeni abonelik üç adımda açılır (Adres, Olaylar, Süzgeç). Teslim günlüğü kart listesidir; her kartta Ayrıntı ve Yeniden gönder düğmeleri vardır.

İlgili rehberler