Translation. Original: pobieranie-faktur/hwm.md

High Water Mark (HWM)

25.11.2025

Механізм High Water Mark (HWM) описує, як KSeF керує повнотою даних у часі для дати PermanentStorage.

У будь-який момент система знає момент у часі (HWM), до якого вона вже має впевненість, що всі рахунки-фактури були записані і не з'являться нові документи з датою PermanentStorage більш ранньою або рівною цьому моменту.

• Для часу ≤ HWM - всі рахунки-фактури з датою PermanentStorage у цьому проміжку вже були остаточно записані в KSeF. Система гарантує, що в майбутньому не з'явиться жоден новий рахунок-фактура з датою PermanentStorage ≤ HWM.
• У проміжку (HWM, Зараз):
  • частина рахунків-фактур уже видима і може бути повернена в запиті,
  • з огляду на асинхронний і багатопотоковий характер процесу запису, у цьому проміжку можуть ще з'явитися нові рахунки-фактури, тобто з датою PermanentStorage, що потрапляє в діапазон (HWM, Зараз].

Висновок:

• все, що ≤ HWM, можна розглядати як закритий і повний набір,
• все, що > HWM, є потенційно неповним і вимагає обережного ставлення при синхронізації.

Сценарій 1 - синхронізація "лише до HWM"

Система при кожному запиті отримує рахунки-фактури від "останньої відомої точки" лише до поточного значення HWM. Нове значення HWM стає початком наступного проміжку.

Переваги:

• дані до HWM є остаточними - не потрібно повторно перевіряти той самий проміжок,
• кількість дублікатів між послідовними завантаженнями є мінімальною.

Наслідки:

• частина найсвіжіших рахунків-фактур з діапазону (HWM, Зараз] не видима в локальній системі - з'явиться тільки після зміщення HWM у наступному циклі.

Цей сценарій рекомендується для поступової, автоматичної синхронізації даних, в яких важливішою за негайну доступність найсвіжіших рахунків-фактур є оптимізація трафіку і мінімізація кількості дублікатів.

Сценарій 2 - синхронізація "до Зараз"

Система, що інтегрується з KSeF, виконує циклічні, поступові запити від останньої початкової точки аж до Зараз і записує всі повернені рахунки-фактури, також з проміжку (HWM, Зараз].

Оскільки дані в цьому проміжку можуть бути неповними, наступний запит повторює частину діапазону - принаймні від попереднього HWM до нового Зараз. З боку локальної системи необхідна дедуплікація (наприклад, за номером KSeF).

Переваги:

• локальна система (і користувач) бачить найновіші рахунки-фактури якомога швидше, без очікування поки HWM їх "наздожене".

Наслідки:

• діапазон (HWM, Зараз] має бути перевірений знову при наступному запиті,
• з'являться дублікати, які слід видаляти з боку локальної системи.

Цей самий механізм може використовуватися також ad hoc, коли користувач вручну вимагає оновлення даних - система завантажує тоді "тут і зараз" найсвіжіші доступні рахунки-фактури від останньої відомої дати аж до Зараз.

Пов'язані документи

• Поступове завантаження рахунків-фактур