Перейти к содержимому
HNROS Справочный центр
Русский
Начать бесплатно
СодержаниеСоздание подпискиСобытияСодержимое уведомленияПроверка подписиДоставка, повторы и недоставленныеЖурнал доставки и повторная отправкаКлюч шифрования сервераСводка конечных точек OpenAPIНа телефоне

Webhook и OpenAPI: уведомления о событиях для других систем

Когда в HNR происходит событие (счёт проведён, заказ удалён, отгрузка в пути…), webhook отправляет подписанное HTTP-уведомление на заданный вами адрес. Оно содержит только сводку документа и ссылку API; получатель читает полную запись через API своей сессией. Эта страница описывает соглашение, а не официальную схему.

Создание подписки

Настройки › Интеграция и webhook доступны только системному администратору. Для новой подписки нужны название, целевой адрес и хотя бы одно событие. Адрес должен начинаться с https; цель в локальной сети или на этом компьютере (например 192.168.x.x, localhost) принимается только при отмеченном одобрении администратора. Вторую подписку на тот же адрес создать нельзя.

Необязательные фильтры: только определённые контрагенты или склады. Если фильтр задан, а в документе такого поля нет, уведомление не отправляется. Сумма и валюта документа отправляются, только если отмечено «Добавлять сумму и валюту документа в уведомление».

При сохранении секрет подписи (начинается с whsec_) показывается только один раз; сохраните его в принимающей системе. На сервере он хранится в зашифрованном виде и повторно не читается. Если потеряете, создайте новый кнопкой «Обновить секрет»; подписи старым секретом перестают проходить проверку.

События

счёт, заказ, предложение (fatura, siparis, teklif): yazildi, degisti, silindi · накладная (irsaliye): yazildi, silindi · квитанция (makbuz): yazildi, degisti, silindi · stok.hareket (перемещение между складами отправлено, получено или списано; утверждение инвентаризации) · sevkiyat.durum (выезд, доставка в точке, исправление POD) · onay.karar · dof.acildi · servis.bilet (открыта, статус) · uretim.teyit (подтверждение или отмена). Код события передаётся в заголовке X-HNR-Event и в поле olay тела; кнопка теста отправляет test.ping.

Содержимое уведомления

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 — окончательный номер документа; полную запись читают через API по baglanti. tutar и doviz приходят только в подписках с суммой; без doviz сумма в местной валюте фирмы. Для события удаления сводка читается до удаления документа. surum — версия формата: новые поля могут добавляться, существующие не меняются.

Проверка подписи

Каждый запрос содержит заголовки X-HNR-Event, X-HNR-Delivery (идентификатор доставки), X-HNR-Timestamp и X-HNR-Signature: t=…,v1=…. v1 — HMAC-SHA256 (hex) текста t + "." + исходное тело с секретом подписи. Получатель должен проверять подпись сравнением за постоянное время, отклонять метки старше 5 минут и не обрабатывать один и тот же X-HNR-Delivery дважды, но всё равно отвечать 2xx (защита от повтора).

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

Доставка, повторы и недоставленные

HNR отправляет POST на ваш адрес и ждёт 10 секунд; доставкой считается только ответ 2xx, перенаправления не выполняются. После неудачи ожидание составляет примерно 1 мин, 3 мин, 11 мин, 38 мин, 2 ч, 7 ч и 24 ч. Если все восемь попыток неудачны, доставка становится недоставленной. Уведомления одной подписки по одному документу идут по порядку: следующее не отправляется, пока не завершена предыдущая доставка. Одновременно не более 4 доставок на фирму.

Без подписки сервер ничего не отправляет. Доставка выполняется каждую минуту в собственной фирме сервера; в других фирмах — при каждой новой операции в них. В остановленной подписке ожидающие уведомления ждут и уходят после повторного включения.

Журнал доставки и повторная отправка

Журнал доставки показывает статус каждого уведомления (ожидает, доставлено, недоставлено), число попыток и последний HTTP-код; в подробностях — отправленное тело, первый 1 КБ ответа и каждая попытка. «Отправить повторно» сразу отправляет уведомление ещё раз с тем же идентификатором доставки; при неудаче правило повторов начинается заново. Записи никогда не удаляются. «Отправить тест» шлёт событие test.ping на адрес подписки.

Ключ шифрования сервера

Секреты подписи хранятся с AES-256-GCM под тем же ключом шифрования сервера, что и прямое банковское подключение (HNR_BANKA_KIMLIK_ANAHTARI). Если ключ не задан, подписку сохранить нельзя. Если ключ изменится, сохранённые секреты не расшифровываются и для каждой подписки нужно «Обновить секрет».

Сводка конечных точек OpenAPI

GET /api/openapi.json (или кнопка скачивания в разделе Интеграция) перечисляет все открытые сейчас конечные точки API сервера с путём, методом и меткой модуля. Тела запросов и ответов не описываются: это сводка конечных точек, а не официальная схема. Аутентификация: API-ключ в Authorization: Bearer и X-Oturum-Token.

На телефоне

На телефоне подписки показываются карточками; новая подписка создаётся в три шага (Адрес, События, Фильтр). Журнал доставки — список карточек; на каждой есть кнопки «Подробнее» и «Отправить повторно».

Связанные руководства