Почему не совпадают суммы в чеках из API Честного Знака и как расшифровать идентификаторы документов

При интеграции систем учета с ГИС МТ (Честный Знак) разработчики часто сталкиваются с тем, что данные в JSON-ответах API кажутся нелогичными или противоречат фискальным документам, полученным напрямую из ОФД. В этой статье мы подробно разберем, почему поле total может не совпадать с суммой строк, как расшифровать «магические» цифры в идентификаторах документов и по какому принципу Честный Знак обрабатывает содержимое чеков.

Анализ проблемы: расхождение суммы total и состава чека

Разберем ситуацию, когда в JSON-файле, полученном через v3/true-api/documents/list или запрос конкретного документа, поле total содержит сумму, значительно меньшую, чем сумма всех позиций в чеке. На первый взгляд это может показаться ошибкой на стороне ГИС МТ, но здесь кроется специфическая логика системы.

Важно понимать: Честный Знак — это не налоговый орган. Его задача — прослеживаемость маркированного товара. Поэтому система часто оперирует не «чеком в целом», а данными в разрезе товарных групп (ТГ). Рассмотрим основные причины расхождений:

1. Фильтрация по товарной группе: Если в одном чеке присутствуют товары разных категорий (например, молоко, вода и хлеб), то при обработке запроса по конкретной группе (допустим, «Молочная продукция»), поле total может отображать сумму только за товары этой группы. Немаркированные товары (хлеб) вообще игнорируются системой ГИС МТ и не попадают в состав items.
2. Дробление чека: Иногда один физический чек разбивается в системе ГИС МТ на несколько записей. Это происходит, если позиции обрабатываются разными подсистемами или имеют разные временные метки обработки (параметр receivedAt). В таком случае каждая запись будет иметь свой total, соответствующий своей части товаров.
3. Особенности ФФД 1.2: В новом формате фискальных данных информация передается в виде «Уведомлений о реализации». Если какой-то код маркировки не прошел проверку или был продан с ошибкой, он может быть обработан отдельно, что также влияет на итоговые показатели в API.

Расшифровка идентификатора документа (ID)

Многие разработчики замечают, что идентификаторы документов в Честном Знаке имеют огромную длину, например, 23637281440501109803482. Проанализируем структуру этого кода. Он не является случайным набором цифр, а формируется по строгому алгоритму.

Для документов формата ФФД 1.2 идентификатор состоит из трех сегментов:

[Номер ФД] + [Номер ФН] + [Тип документа (суффикс)]

Разберем на примере идентификатора 23637281440501109803482:

• 2363 — номер фискального документа (ФД).
• 7281440501109803 — номер фискального накопителя (ФН), состоящий из 16 цифр.
• 482 — суффикс, определяющий тип операции.

Рассмотрим подробнее значения суффиксов, которые встречаются в системе:

• 482 — основной код для чеков в ФФД 1.2, означающий «Уведомление о реализации маркированного товара». Цифра «4» здесь указывает на версию формата, а «82» на тип уведомления.
• 322 — запрос о коде маркировки (отправляется кассой перед продажей).
• 352 — ответ системы на запрос (квитанция).

Знание этой структуры позволяет нам программно сопоставлять данные из Честного Знака с данными в нашей учетной системе (например, 1С), используя имеющиеся реквизиты чека fiscalDocumentNumber и fiscalDriveNumber.

Почему в запросы по одной товарной группе попадают «чужие» товары

Часто возникает ситуация: мы делаем запрос по молочной продукции, но в ответе видим сигареты или воду. Проанализируем, почему это происходит. Согласно документации API (метод /v3/true-api/documents/list), если параметр productGroups не указан жестко в фильтре, система возвращает все документы, влияющие на баланс участника оборота.

Даже если мы указываем конкретную группу, Честный Знак постепенно переходит на архитектуру «единого окна». Ранее табачная продукция (МОТП) и молочная продукция находились в разных контурах, но сейчас данные объединяются. Если чек содержит товары разных групп, система может вернуть весь состав чека, который прошел через механизм уведомлений, независимо от того, к какой группе они относятся.

Методика сопоставления данных в 1С

Для надежной работы с данными ГИС МТ рекомендуем следующий алгоритм сопоставления чеков:

1. При получении списка документов из API используйте поля fiscalDocumentNumber и fiscalDriveNumber для поиска соответствующего документа в базе 1С.
2. Не полагайтесь на поле total как на сумму чека из ОФД. Если вам нужно проверить корректность списания, суммируйте значения в массиве items только по тем кодам маркировки, которые вас интересуют.
3. Учитывайте временной лаг. Поле docDate — это дата пробития чека на кассе, а receivedAt — время, когда документ был фактически обработан сервером ГИС МТ. Разница может составлять от нескольких минут до нескольких часов (в редких случаях — до суток).

Рассмотрим пример кода на языке 1С для формирования структуры поиска чека:

// Пример формирования ключа поиска чека
Функция СформироватьКлючПоиска(ДанныеJSON)
    // Извлекаем номер ФД и ФН из ответа API
    НомерФД = ДанныеJSON.fiscalDocumentNumber;
    НомерФН = ДанныеJSON.fiscalDriveNumber;
    
    // В ГИС МТ ФД часто дополняется ведущими нулями или объединяется в строку
    // Для сопоставления приводим к строковому виду
    КлючПоиска = СокрЛП(НомерФН) + "_" + СокрЛП(НомерФД);
    Возврат КлючПоиска;
КонецФункции

Резюме

Мы выяснили, что странное поведение поля total — это не баг, а особенность фильтрации данных внутри ГИС МТ. Система фокусируется на движении конкретных марок, а не на фискальной отчетности в понимании налоговой. Идентификатор чека 482 является комбинацией реквизитов ФФД 1.2, а дублирование строк с одним ID объясняется разными этапами или группами обработки данных. При проектировании отчетов в 1С всегда следует ориентироваться на детальный состав items и использовать связку ФН+ФД для однозначной идентификации документа.