Ir al contenido
HNROS Centro de ayuda
Español
Empieza gratis
ContenidoCrear 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éfono

Webhooks 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