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, когда пользователь вручную требует обновления данных - система получает тогда "здесь и сейчас" самые свежие доступные счета-фактуры от последней известной даты до Сейчас.

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

• Инкрементальное получение счетов-фактур