Contenido
Crear una suscripciónEventosContenido de la notificaciónVerificar la firmaEntrega, reintentos y mensajes fallidosRegistro de entregas y reenvíoClave de cifrado del servidorResumen de endpoints OpenAPIEn el teléfonoWebhooks y OpenAPI: notificación de eventos a otros sistemas
Cuando ocurre un evento en HNR (factura registrada, pedido eliminado, envío en camino…), el webhook envía una notificación HTTP firmada a la dirección que usted defina. Solo lleva un resumen del documento y su enlace de API; el receptor lee el registro completo desde la API con su propia sesión. Esta página describe un contrato, no un esquema oficial.
Crear una suscripción
Ajustes › Integración y webhooks solo está disponible para el administrador del sistema. Una suscripción nueva necesita un nombre, una dirección de destino y al menos un evento. La dirección debe empezar por https; un destino en la red local o en este equipo (p. ej. 192.168.x.x, localhost) solo se acepta si se marca la casilla de aprobación del administrador. No se puede crear una segunda suscripción para la misma dirección.
Filtros opcionales: solo ciertas cuentas o almacenes. Si hay un filtro y el documento no tiene ese campo, no se envía la notificación. El importe y la moneda solo se envían si está marcado «Añadir el importe y la moneda del documento a la notificación».
Al guardar, el secreto de firma (empieza por whsec_) se muestra una sola vez; guárdelo en el sistema receptor. Se almacena cifrado en el servidor y no puede volver a leerse. Si lo pierde, genere uno nuevo con «Renovar secreto»; las firmas con el secreto anterior dejan de verificarse.
Eventos
factura, pedido, oferta (fatura, siparis, teklif): yazildi, degisti, silindi · albarán (irsaliye): yazildi, silindi · recibo (makbuz): yazildi, degisti, silindi · stok.hareket (traspaso entre almacenes enviado, recibido o con merma; aprobación de recuento) · sevkiyat.durum (salida, parada entregada, corrección de POD) · onay.karar · dof.acildi · servis.bilet (abierto, estado) · uretim.teyit (notificación o anulación). El código del evento va en la cabecera X-HNR-Event y en el campo olay del cuerpo; el botón de prueba envía test.ping.
Contenido de la notificación
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 es el número definitivo del documento; el registro completo se lee de la API mediante baglanti. tutar y doviz solo llegan en suscripciones con importe; sin doviz el importe está en la moneda local de la empresa. En un evento de eliminación el resumen se lee antes de borrar el documento. surum es la versión del formato: pueden añadirse campos nuevos, los existentes no cambian.
Verificar la firma
Cada petición lleva las cabeceras X-HNR-Event, X-HNR-Delivery (ID de entrega), X-HNR-Timestamp y X-HNR-Signature: t=…,v1=…. v1 es el HMAC-SHA256 (hexadecimal) del texto t + "." + cuerpo sin procesar con el secreto. El receptor debe verificar la firma con comparación de tiempo constante, rechazar marcas de tiempo de más de 5 minutos y no procesar dos veces el mismo X-HNR-Delivery, respondiendo igualmente 2xx (protección contra repetición).
// 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', '')) Entrega, reintentos y mensajes fallidos
HNR hace POST a su dirección y espera 10 segundos; solo una respuesta 2xx cuenta como entregada y no se siguen redirecciones. Tras un intento fallido, las esperas son de aproximadamente 1 min, 3 min, 11 min, 38 min, 2 h, 7 h y 24 h. Si fallan los ocho intentos, la entrega pasa a mensaje fallido. Las notificaciones de la misma suscripción y el mismo documento van en orden: la siguiente no se envía hasta que termina la anterior. Como máximo 4 envíos simultáneos por empresa.
Sin suscripción el servidor no envía nada. El envío se ejecuta cada minuto en la empresa propia del servidor; en otras empresas, cada vez que se realiza una operación nueva en ellas. En una suscripción detenida, las notificaciones pendientes esperan y salen al volver a activarla.
Registro de entregas y reenvío
El registro de entregas muestra el estado de cada notificación (pendiente, entregada, fallida), el número de intentos y el último código HTTP; el detalle lista el cuerpo enviado, el primer 1 KB de la respuesta y cada intento. «Reenviar» vuelve a enviar la notificación de inmediato con el mismo ID de entrega; si falla, la regla de reintento empieza de nuevo. Los registros nunca se borran. «Enviar prueba» envía un evento test.ping a la dirección de la suscripción.
Clave de cifrado del servidor
Los secretos se guardan con AES-256-GCM bajo la misma clave de cifrado del servidor que la conexión bancaria en vivo (HNR_BANKA_KIMLIK_ANAHTARI). Si esa clave no está definida, no se puede guardar una suscripción. Si la clave cambia, los secretos guardados no se pueden descifrar y cada suscripción necesita «Renovar secreto».
Resumen de endpoints OpenAPI
GET /api/openapi.json (o el botón de descarga de la sección Integración) enumera todos los endpoints de API que el servidor expone en ese momento, con ruta, método y etiqueta de módulo. No se documentan los cuerpos de petición ni de respuesta: es un resumen de endpoints, no un esquema oficial. Autenticación: la clave API Authorization: Bearer y X-Oturum-Token.
En el teléfono
En el teléfono las suscripciones aparecen como tarjetas; una suscripción nueva se crea en tres pasos (Dirección, Eventos, Filtro). El registro de entregas es una lista de tarjetas; cada tarjeta tiene los botones Detalles y Reenviar.
Guías relacionadas
- Departamentos — Guía desde cero para la oficina internaEsta ventana no hace un solo trabajo; mantiene juntos los libros de diez departamentos distintos. No se asuste: nadie usa los diez.
- Catálogo de integraciones: ¿con qué se conecta HNR?Esta página reúne en un solo lugar cómo se conecta HNR con bancos, transportistas, marketplaces, la administración tributaria.
- Formularios de impresión: usted diseña lo que sale en papelAntes, los formularios de oferta, factura y recibo estaban incrustados en el programa; cambiarlos exigía un programador.
- Rastro de auditoría, puertas de seguridad y anomalíasEsta guía explica tres capas de defensa distintas. En pocas palabras: la primera registra, la segunda detiene y la tercera muestra.
- Serie de números de documento — Un guía de ScratchCada documento final - factura, nota de entrega, pedido, citación, recepción, bolsa de cheque- tiene un número que se muestra al cliente.
- Centro de Notificación y Aprobación — Un Guía de ScratchEl trabajo que espera la aprobación se sitúa en diez rincones diferentes del programa: el límite de crédito en un lugar, la factura que corresponde a la.