Ir para o conteúdo
HNROS Central de ajuda
Português
Comece grátis
ConteúdoCriar uma assinaturaEventosConteúdo da notificaçãoVerificar a assinaturaEntrega, novas tentativas e mensagens mortasRegistro de entregas e reenvioChave de criptografia do servidorResumo de endpoints OpenAPINo celular

Webhooks e OpenAPI: notificação de eventos para outros sistemas

Quando um evento ocorre no HNR (nota lançada, pedido excluído, remessa em trânsito…), o webhook envia uma notificação HTTP assinada para o endereço definido. Ela leva apenas um resumo do documento e o link da API; o receptor lê o registro completo pela API com a própria sessão. Esta página descreve um contrato, não um esquema oficial.

Criar uma assinatura

Configurações › Integração e webhooks só está disponível ao administrador do sistema. Uma nova assinatura precisa de nome, endereço de destino e pelo menos um evento. O endereço deve começar com https; um destino na rede local ou neste computador (ex.: 192.168.x.x, localhost) só é aceito se a caixa de aprovação do administrador estiver marcada. Não é possível criar uma segunda assinatura para o mesmo endereço.

Filtros opcionais: apenas certas contas ou depósitos. Se houver filtro e o documento não tiver esse campo, a notificação não é enviada. O valor e a moeda só são enviados se «Incluir o valor e a moeda do documento na notificação» estiver marcado.

Ao salvar, o segredo de assinatura (começa com whsec_) é exibido uma única vez; guarde-o no sistema receptor. Ele fica criptografado no servidor e não pode ser lido de novo. Se perdê-lo, gere outro com «Renovar segredo»; assinaturas com o segredo antigo deixam de ser válidas.

Eventos

nota, pedido, proposta (fatura, siparis, teklif): yazildi, degisti, silindi · romaneio (irsaliye): yazildi, silindi · recibo (makbuz): yazildi, degisti, silindi · stok.hareket (transferência entre depósitos enviada, recebida ou com perda; aprovação de contagem) · sevkiyat.durum (saída, parada entregue, correção de POD) · onay.karar · dof.acildi · servis.bilet (aberto, status) · uretim.teyit (apontamento ou cancelamento). O código do evento vem no cabeçalho X-HNR-Event e no campo olay do corpo; o botão de teste envia test.ping.

Conteúdo da notificação

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 é o número definitivo do documento; o registro completo é lido na API por baglanti. tutar e doviz só vêm em assinaturas com valor; sem doviz o valor está na moeda local da empresa. Num evento de exclusão o resumo é lido antes de o documento ser excluído. surum é a versão do formato: campos novos podem ser adicionados, os existentes não mudam.

Verificar a assinatura

Cada requisição traz os cabeçalhos X-HNR-Event, X-HNR-Delivery (ID da entrega), X-HNR-Timestamp e X-HNR-Signature: t=…,v1=…. v1 é o HMAC-SHA256 (hexadecimal) do texto t + "." + corpo bruto com o segredo. O receptor deve verificar a assinatura com comparação de tempo constante, rejeitar carimbos com mais de 5 minutos e não processar duas vezes o mesmo X-HNR-Delivery, respondendo 2xx mesmo assim (proteção contra repetição).

// 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, novas tentativas e mensagens mortas

O HNR faz POST no seu endereço e espera 10 segundos; só uma resposta 2xx conta como entregue e redirecionamentos não são seguidos. Após uma tentativa falha, as esperas são de cerca de 1 min, 3 min, 11 min, 38 min, 2 h, 7 h e 24 h. Se as oito tentativas falharem, a entrega vira mensagem morta. Notificações da mesma assinatura e do mesmo documento seguem em ordem: a seguinte não é enviada antes de a anterior terminar. No máximo 4 envios simultâneos por empresa.

Sem assinatura o servidor não envia nada. O envio roda a cada minuto na empresa do próprio servidor; nas demais empresas, sempre que houver uma nova operação nelas. Numa assinatura parada, as notificações pendentes aguardam e saem quando ela é reativada.

Registro de entregas e reenvio

O registro de entregas mostra o status de cada notificação (pendente, entregue, morta), o número de tentativas e o último código HTTP; o detalhe lista o corpo enviado, o primeiro 1 KB da resposta e cada tentativa. «Reenviar» envia a notificação mais uma vez na hora com o mesmo ID de entrega; se falhar, a regra de nova tentativa recomeça. Os registros nunca são excluídos. «Enviar teste» envia um evento test.ping ao endereço da assinatura.

Chave de criptografia do servidor

Os segredos são guardados com AES-256-GCM sob a mesma chave de criptografia do servidor usada na conexão bancária ao vivo (HNR_BANKA_KIMLIK_ANAHTARI). Se essa chave não estiver definida, não é possível salvar uma assinatura. Se a chave mudar, os segredos guardados não podem ser decifrados e cada assinatura precisa de «Renovar segredo».

Resumo de endpoints OpenAPI

GET /api/openapi.json (ou o botão de download na seção Integração) lista todos os endpoints de API expostos pelo servidor no momento, com caminho, método e rótulo do módulo. Os corpos de requisição e resposta não são documentados: é um resumo de endpoints, não um esquema oficial. Autenticação: a chave de API Authorization: Bearer e X-Oturum-Token.

No celular

No celular as assinaturas aparecem como cartões; uma nova assinatura é criada em três etapas (Endereço, Eventos, Filtro). O registro de entregas é uma lista de cartões; cada cartão tem os botões Detalhes e Reenviar.

Guias relacionados