Aller au contenu
HNROS Centre d'aide
Français
Commencer gratuitement
SommaireCréer un abonnementÉvénementsContenu de la notificationVérifier la signatureLivraison, nouvelles tentatives et lettres mortesJournal des livraisons et renvoiClé de chiffrement du serveurRésumé des points de terminaison OpenAPISur le téléphone

Webhooks et OpenAPI : notification d'événements vers d'autres systèmes

Lorsqu'un événement se produit dans HNR (facture comptabilisée, commande supprimée, expédition partie…), le webhook envoie une notification HTTP signée à l'adresse que vous définissez. Elle ne contient qu'un résumé du document et son lien d'API ; le destinataire lit l'enregistrement complet via l'API avec sa propre session. Cette page décrit un contrat, pas un schéma officiel.

Créer un abonnement

Paramètres › Intégration et webhooks est réservé à l'administrateur système. Un nouvel abonnement exige un nom, une adresse cible et au moins un événement. L'adresse doit commencer par https ; une cible sur le réseau local ou sur cet ordinateur (ex. 192.168.x.x, localhost) n'est acceptée que si la case d'approbation de l'administrateur est cochée. Un second abonnement pour la même adresse est impossible.

Filtres facultatifs : seulement certains comptes ou entrepôts. Si un filtre est défini et que le document n'a pas ce champ, aucune notification n'est envoyée. Le montant et la devise ne sont envoyés que si « Ajouter le montant et la devise du document à la notification » est coché.

À l'enregistrement, le secret de signature (commençant par whsec_) n'est affiché qu'une fois ; stockez-le dans le système destinataire. Il est conservé chiffré sur le serveur et ne peut plus être relu. En cas de perte, générez-en un nouveau avec « Renouveler le secret » ; les signatures faites avec l'ancien ne sont plus valides.

Événements

facture, commande, devis (fatura, siparis, teklif) : yazildi, degisti, silindi · bon de livraison (irsaliye) : yazildi, silindi · reçu (makbuz) : yazildi, degisti, silindi · stok.hareket (transfert entre entrepôts expédié, reçu ou perte ; approbation d'inventaire) · sevkiyat.durum (départ, arrêt livré, correction de POD) · onay.karar · dof.acildi · servis.bilet (ouvert, statut) · uretim.teyit (confirmation ou annulation). Le code d'événement figure dans l'en-tête X-HNR-Event et dans le champ olay du corps ; le bouton de test envoie test.ping.

Contenu de la notification

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 est le numéro définitif du document ; l'enregistrement complet se lit via l'API grâce à baglanti. tutar et doviz ne figurent que pour les abonnements avec montant ; sans doviz, le montant est dans la devise locale de la société. Pour une suppression, le résumé est lu avant l'effacement du document. surum est la version du format : des champs peuvent s'ajouter, les existants ne changent pas.

Vérifier la signature

Chaque requête porte les en-têtes X-HNR-Event, X-HNR-Delivery (identifiant de livraison), X-HNR-Timestamp et X-HNR-Signature: t=…,v1=…. v1 est le HMAC-SHA256 (hexadécimal) du texte t + "." + corps brut avec le secret. Le destinataire doit vérifier la signature par comparaison à temps constant, rejeter un horodatage de plus de 5 minutes et ne pas traiter deux fois le même X-HNR-Delivery tout en répondant 2xx (protection contre le rejeu).

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

Livraison, nouvelles tentatives et lettres mortes

HNR envoie un POST à votre adresse et attend 10 secondes ; seule une réponse 2xx compte comme livrée et les redirections ne sont pas suivies. Après un échec, les attentes sont d'environ 1 min, 3 min, 11 min, 38 min, 2 h, 7 h et 24 h. Si les huit tentatives échouent, la livraison devient une lettre morte. Les notifications d'un même abonnement et d'un même document partent dans l'ordre : la suivante n'est pas envoyée avant la fin de la précédente. Au plus 4 livraisons simultanées par société.

Sans abonnement, le serveur n'envoie rien. L'envoi s'exécute chaque minute dans la société propre du serveur ; dans les autres sociétés, à chaque nouvelle opération qui y est faite. Pour un abonnement arrêté, les notifications en attente patientent et partent dès sa réactivation.

Journal des livraisons et renvoi

Le journal des livraisons affiche pour chaque notification le statut (en attente, livrée, lettre morte), le nombre de tentatives et le dernier code HTTP ; le détail liste le corps envoyé, le premier 1 Ko de la réponse et chaque tentative. « Renvoyer » renvoie aussitôt la notification avec le même identifiant de livraison ; en cas d'échec, la règle de nouvelle tentative repart de zéro. Les enregistrements ne sont jamais supprimés. « Envoyer un test » envoie un événement test.ping à l'adresse de l'abonnement.

Clé de chiffrement du serveur

Les secrets de signature sont stockés en AES-256-GCM sous la même clé de chiffrement du serveur que la connexion bancaire en direct (HNR_BANKA_KIMLIK_ANAHTARI). Si cette clé n'est pas définie, aucun abonnement ne peut être enregistré. Si elle change, les secrets stockés ne peuvent plus être déchiffrés et chaque abonnement nécessite « Renouveler le secret ».

Résumé des points de terminaison OpenAPI

GET /api/openapi.json (ou le bouton de téléchargement de la section Intégration) liste tous les points de terminaison d'API exposés par le serveur, avec chemin, méthode et étiquette de module. Les corps de requête et de réponse ne sont pas documentés : c'est un résumé des points de terminaison, pas un schéma officiel. Authentification : la clé d'API Authorization: Bearer et X-Oturum-Token.

Sur le téléphone

Sur le téléphone, les abonnements s'affichent sous forme de cartes ; un nouvel abonnement se crée en trois étapes (Adresse, Événements, Filtre). Le journal des livraisons est une liste de cartes ; chaque carte a les boutons Détails et Renvoyer.

Guides associés