Conteúdo
Criar uma assinaturaEventosConteúdo da notificaçãoVerificar a assinaturaEntrega, novas tentativas e mensagens mortasRegistro de entregas e reenvioChave de criptografia do servidorResumo de endpoints OpenAPINo celularWebhooks 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
- Departamentos — Um guia do zero para o back officeEsta janela não faz um serviço só; ela mantém lado a lado os livros de dez departamentos diferentes. Não se assuste: ninguém usa os dez.
- Catálogo de integrações: a que o HNR se conecta?Esta página reúne num só lugar como o HNR se conecta a bancos, transportadoras, marketplaces, à administração fiscal, a arquivos contábeis e a outros programas.
- Formulários de Impressão — você desenha o que sai no papelAntigamente os layouts de orçamento, nota fiscal e recibo ficavam enterrados dentro do programa; para mudar um deles era preciso um programador.
- Trilha de Auditoria, Travas de Segurança e AnomaliasEste guia trata de três camadas de defesa distintas. Em resumo: a primeira registra, a segunda impede, a terceira mostra.
- Document Number Series – Um Guia de ScratchCada documento final – fatura, nota de entrega, encomenda, citação, receita, cheque batch – tem um número que é mostrado ao cliente.
- Centro de Notificação e Aprovação - Um Guia de ScratchO trabalho que espera a aprovação está localizado em dez ângulos diferentes do programa: o limite de crédito em um lugar, a diferença de fatura em outro.