ГИС «Налог-3» API: подключаем 1С:Бухгалтерию к новому формату отправки отчётности ФНС

ФНС расширила API ГИС «Налог-3» - теперь бухгалтерские системы могут обмениваться данными с налоговой без промежуточных операторов ЭДО в части новых сценариев. Новость пришла фоном к рабочей задаче: у нас как раз лежит клиент, которому нужно перевести отправку отчётности из 1С:Бухгалтерии на новый формат. Совпало удачно - вместо того чтобы изучать изменения в теории, изучаем на живом проекте.

Делимся тем, что видим на практике. Без обещаний что всё будет хорошо - пока работа в процессе.

Что изменилось в API

Старый механизм взаимодействия с ФНС для большинства бухгалтерских систем выглядел так: отчёт формируется в XML по утверждённому формату, подписывается КЭП, упаковывается в транспортный контейнер и уходит через спецоператора. ГИС «Налог-3» в этой схеме - принимающая сторона, которую вы не трогаете напрямую, она существует где-то за спецоператором.

Расширение API меняет схему: у ГИС «Налог-3» появился прямой программный интерфейс, позволяющий бухгалтерским системам отправлять ряд документов напрямую, получать статусы в реальном времени и забирать входящие данные из налоговой. Ключевые изменения, с которыми мы столкнулись:

• Транспортный формат. Новый API работает через REST с JWT-авторизацией. Старая схема с транспортными контейнерами в формате СМЭВ 3.x никуда не делась - она продолжает работать для тех, кто через неё ходит. Но для новых сценариев взаимодействия транспорт другой.
• Аутентификация. Подпись КЭП остаётся обязательной для самих документов, но авторизация в API - отдельная история. Нужна регистрация системы в личном кабинете ФНС и выдача API-ключей организации.
• Форматы данных. Для НДФЛ-отчётности (6-НДФЛ, 2-НДФЛ в новом формате) появились обновлённые XSD-схемы. Часть полей переименована, изменилась структура разделов. Это не радикальная переработка, но совместимость со старыми схемами не гарантируется.
• Статусы в реальном времени. Старая модель - отправил, жди квитанцию асинхронно. Новый API возвращает синхронный ответ с первичным статусом приёма и позволяет подписаться на обновления через коллбэк или опросить статус дополнительным запросом.

Как это выглядит на стороне 1С

Клиент использует 1С:Бухгалтерия 8.3, конфигурация свежая - обновляется штатно через сервис 1С. Теоретически всё, что связано с регламентированной отчётностью, фирма 1С закрывает сама через обновления: новые форматы приходят вместе с обновлением конфигурации, настройки канала отправки - в регламентированной отчётности.

Практически - не совсем. Штатный механизм 1С работает через подключённого спецоператора (у клиента - Контур). Новый прямой API ФНС в типовой конфигурации пока не поддерживается как отдельный канал - это надстройка, которую нужно делать через доработку или внешнюю обработку.

Мы пошли путём внешней обработки. Схема такая:

1. Регламентированная отчётность в 1С формирует XML по стандартным форматам - это остаётся без изменений.
2. Внешняя обработка забирает сформированный XML, адаптирует под актуальную XSD-схему нового формата (там несколько переименований полей в разделе налогового агента).
3. Подпись через КриптоПро CSP - отдельный вызов, уже привычный.
4. Отправка через HTTP-запрос к новому API ФНС с JWT-токеном.
5. Получение и запись статусов обратно в базу 1С.

Звучит несложно. На деле пункты 2 и 4 съели больше времени, чем ожидалось.

Где возникли трудности

XSD-схемы. ФНС публикует актуальные схемы на сайте, но документация к ним - скромная. Часть семантики полей нигде не описана явно, приходится ориентироваться на примеры из методических указаний, которые к новому API не актуализированы в полном объёме. Небольшая разница в заполнении поля кода налогового периода привела к тому, что документ уходил с ошибкой валидации на стороне ФНС - ошибка неинформативная, потратили пару часов на диагностику.

JWT и токены. Авторизационная схема нормальная, но нюанс в том, что токен привязан к ИНН организации и к конкретному ключу, который зарегистрирован в ЛК ФНС. Ротацию токенов нужно закладывать в логику обработки - они живут ограниченное время. Это не проблема, просто момент, который надо учесть сразу, а не потом, когда токен протухнет в продакшне в первый раз.

Тестовая среда. У ФНС есть тестовый контур для разработчиков. Хорошо, что он есть. Не очень хорошо, что его доступность периодически подводит - несколько раз в ходе тестирования контур был недоступен без каких-либо объяснений. Если вы работаете с дедлайном - закладывайте запас.

КриптоПро и HTTP. КриптоПро CSP 5.0 умеет подписывать и работает с нашей схемой нормально. Но сборка цепочки из «сформировать документ - подписать - упаковать запрос» в рамках одной обработки 1С потребовала аккуратности с кодировками и с порядком подписания атрибутов. Мелочи, которые не видны в тестовом контуре с простыми файлами, но проявляются на реальных документах с расширенными данными.

Где сейчас

Базовый сценарий - отправка 6-НДФЛ через новый API и получение статуса - работает в тестовом режиме. Клиент смотрит результаты. До перевода в продакшн остаётся отработать сценарий входящих документов от ФНС (требования, уведомления) и настроить нормальное логирование статусов в базе 1С - сейчас это пишется во временную таблицу, что неудобно для поддержки.

Старый канал через Контур пока оставляем параллельно - до полной проверки нового не трогаем то, что работает. Лишние расходы на спецоператора в переходный период - это цена спокойствия.

По интеграции бухгалтерских систем с регуляторными API готовы разбирать кейсы - здесь есть специфика, которая не решается стандартными обновлениями конфигурации 1С.