True API «Честного знака»: ошибки авторизации 401, 403 и проблемы с УКЭП

Ошибки 401 и 403 в True API часто объединяют в одну формулировку «не проходит авторизация», хотя причины находятся на разных уровнях. Запрос может не содержать действительный токен, пользователь может не иметь нужной роли, организация — доступа к товарной группе, а интеграция — обращаться к другому контуру или методу.

Диагностику удобнее проводить по цепочке доступа: организация и товарная группа → пользователь и роль → УКЭП → получение токена → адрес и версия API → права на конкретную операцию. Такой порядок экономит время и не требует бесконечно перевыпускать сертификат.

Чем обычно различаются 401 и 403

Точный смысл определяют по телу ответа и актуальной документации метода в личном кабинете. Один HTTP-код может сопровождать несколько бизнес-причин, поэтому журнал должен сохранять код, безопасную часть ответа, адрес метода, время и внутренний идентификатор операции.

Проверка учётной записи и товарной группы

Для работы с True API участник регистрируется в системе маркировки и подключает товарную группу. Официальная инструкция указывает на необходимость УКЭП руководителя или ИП для регистрации и подписания документов [1]. Работа методов API выполняется в рамках товарных групп, доступных участнику [2].

Если в браузере пользователь видит личный кабинет, это ещё не подтверждает право интеграции на любой метод. Проверьте организацию, выбранную товарную группу, роль пользователя, подписанные договоры и доступность операции в интерфейсе. Особенно часто расхождение возникает, когда сертификат принадлежит руководителю, а интеграция запускается от учётной записи сотрудника с ограниченной ролью.

УКЭП и получение токена

УКЭП участвует в подтверждении личности и подписании данных на этапе, который описан в документации True API. После успешной аутентификации методы API могут работать без браузерного криптоплагина, однако серверная интеграция всё равно должна корректно выполнять установленную последовательность получения и обновления токена [2].

Проверьте:

• срок действия сертификата и цепочку доверия;
• ИНН и сведения владельца сертификата;
• наличие закрытого ключа и доступ сервисной учётной записи к контейнеру;
• алгоритм подписи и формат передаваемых данных;
• системное время и часовой пояс сервера;
• порядок обновления токена до истечения, а не после первой ошибки рабочего запроса.

Статический токен, однажды скопированный в конфигурацию, становится источником аварий после изменения правил или ротации. Для интеграции нужен контролируемый жизненный цикл: получение, защищённое хранение, обновление, запрет вывода в логи и оповещение при повторном отказе.

Тестовый и промышленный контуры

Пара «правильный токен — неправильный адрес» даёт тот же внешний симптом, что и испорченная авторизация. В конфигурации явно разделяют базовый URL, идентификаторы участника, сертификаты и тестовые данные. Переменные разных контуров не должны смешиваться в одном наборе секретов.

Полезно выполнить минимальный диагностический запрос, указанный в документации доступного метода. Если он проходит, а отправка документа возвращает 403, проблема вероятнее связана с полномочиями или бизнес-условиями операции. Если не проходит и базовый запрос, проверяют саму авторизацию, адрес и токен.

Как вести журнал без утечки секретов

Полный токен, закрытый ключ, контейнер УКЭП и подписываемые персональные данные в журнал не записывают. Для расследования достаточно безопасных признаков: тип операции, контур, организация, товарная группа, отпечаток сертификата, последние символы идентификатора запроса, HTTP-код, код ошибки сервиса и время.

Каждый бизнес-документ получает собственный идентификатор в учётной системе. Повторная отправка должна учитывать уже созданную операцию и полученный статус. Иначе сбой авторизации после фактической приёмки документа может привести к дублю после восстановления связи.

Сначала определите, к какому API относится ошибка

Под названием «Честный знак API» в проектах часто объединяют разные контуры и операции: работу с документами ГИС МТ, Национальным каталогом, станцией управления заказами и отдельными товарными группами. У них могут различаться адреса, последовательность аутентификации, срок токена и полномочия. Поэтому скриншота с кодом 401 недостаточно: до проверки сертификата нужно зафиксировать подсистему, товарную группу, название метода, версию документации и базовый URL.

Особенно важно не переносить правила токена СУЗ на все методы True API. В официальной инструкции для СУЗ описан динамический clientToken со сроком действия не более 10 часов и получение через механизм единой аутентификации [5]. Это конкретный сценарий станции управления заказами. Для другого метода нужно открыть документацию именно того раздела, из которого он вызывается, и сверить требуемые заголовки и тип токена.

На каком этапе может остановиться авторизация

Диагностику полезно разделить на четыре этапа. Первый — соединение: DNS, TLS, доверие к сертификату сервера и доступ к адресу из сети компании. Ошибка здесь обычно возникает до получения HTTP-ответа и не исправляется перевыпуском пользовательской УКЭП.

Второй этап — получение данных для подписи и формирование подписи. Проверяются сертификат, закрытый ключ, криптопровайдер, формат подписи и исходная последовательность байтов. Если одна система подписывает строку в UTF-8, а другая передаёт её после изменения кодировки или переносов, криптографическая проверка не совпадёт. Подписывать нужно именно те данные и в том формате, которые вернул текущий метод документации.

Третий этап — получение токена и его передача в последующих запросах. Здесь появляются ошибки из-за истечения срока, неправильного заголовка, смешения контуров и параллельного обновления. Четвёртый — проверка прав на бизнес-операцию. Действительный токен ещё не означает, что участнику доступна нужная товарная группа, документ или действие.

Что меняется после замены УКЭП

Плановая замена сертификата способна остановить серверную интеграцию, даже если вход в личный кабинет с новым ключом уже работает. В конфигурации приложения может оставаться отпечаток прежнего сертификата, служба может не видеть новый контейнер, а процесс — работать от пользователя, которому закрытый ключ недоступен. Также нужно проверить соответствие сведений владельца и организации данным ЕГРЮЛ или ЕГРИП. Официальная справка указывает, что для регистрации используется УКЭП руководителя или ИП, имеющего право действовать без доверенности, и перечисляет сведения квалифицированного сертификата [3].

Перед окончанием срока действия действующего сертификата проводят контрольное получение токена новым сертификатом на согласованном контуре. Затем обновляют ссылку на контейнер или отпечаток, перезапускают только нужную службу и проверяют один безопасный запрос. Старый ключ удаляют из рабочей конфигурации после подтверждения результата, а не в начале переключения. Такой порядок оставляет понятный путь возврата.

Если используется обезличенная УКЭП юридического лица, нужно учитывать ограничения ролей и доступных разделов. В официальном описании ОУКЭП перечислены функции, которые для такого пользователя недоступны, в том числе отдельные операции через интерфейс и API [6]. Возможность работы конкретного метода проверяют заранее, а не по факту промышленной ошибки 403.

Как построить жизненный цикл токена

Токен хранится как секрет: вне исходного кода и репозитория, с доступом только у процесса интеграции. Вместе с ним система сохраняет время получения и срок, после которого выполняется обновление. Обновляться лучше заранее, оставляя запас на временную недоступность сервиса и расхождение часов.

Если несколько процессов одновременно замечают истечение, они не должны все запускать авторизацию. Один экземпляр получает новый токен, остальные ждут результат и используют обновлённое значение. Это называют защитой от «лавины обновления»: без неё единичное истечение превращается в десятки криптографических операций и повторных запросов.

После первого 401 интеграция может один раз обновить токен и повторить безопасный запрос. Бесконечный цикл обновления маскирует настоящую проблему — неверный контур, отозванный сертификат или потерянные права. После контролируемой повторной попытки событие остаётся в очереди, а ответственному отправляется уведомление с методом, временем и кодом ответа.

Как проверить полномочия при 403

Права сверяют не вообще «у пользователя», а для конкретной операции. Участник должен быть зарегистрирован в нужной товарной группе, пользователь — добавлен в организацию с подходящей ролью, а требуемые договоры и действия — доступны в личном кабинете. Для СУЗ официальная инструкция отдельно указывает, что раздел устройств доступен руководителю или администратору, тогда как обычной роли сотрудника недостаточно [5].

Удобно вести матрицу доступа: строки — методы интеграции, столбцы — организация, товарная группа, контур, пользователь, необходимая роль и контрольный запрос. Матрица обновляется после добавления товарной группы, смены руководителя, сертификата или состава пользователей. Она быстрее показывает расхождение, чем многократный запуск одного и того же документа.

Проверка через интерфейс дополняет API, но не заменяет его. Успешный вход подтверждает, что сертификат распознан и пользователь связан с организацией. Доступ к нужному разделу и возможность выполнить аналогичное действие помогают локализовать проблему, однако окончательный вывод делают по требованиям конкретного метода и телу ответа.

Почему очередь нельзя отправлять целиком сразу после восстановления

За время сбоя в очереди могут накопиться документы, часть которых сервис уже принял до потери ответа. Для каждого документа нужен устойчивый идентификатор и сохранённая история попыток. Сначала запрашивают состояние уже отправленных операций, затем повторяют только те, для которых приём не подтверждён. Это защищает от дублей и конфликтующих статусов.

Восстановление начинают с одного контрольного документа. Проверяют HTTP-ответ, идентификатор операции и конечный статус в системе маркировки. После этого очередь открывают небольшими партиями, контролируя частоту ошибок и время обработки. Если первые запросы снова возвращают 401 или 403, массовая отправка останавливается автоматически.

Какие тесты провести до промышленного запуска

• получение токена после перезапуска службы без ручного входа в личный кабинет;
• заблаговременное обновление токена и одновременный запрос из нескольких процессов;
• понятное поведение при истёкшем токене, недоступном контейнере и неверном контуре;
• раздельная проверка пользователя с достаточной и недостаточной ролью;
• однократный безопасный повтор после 401 без дублирования бизнес-документа;
• сохранение очереди при недоступности API и контролируемое восстановление;
• отсутствие токенов, закрытых ключей и содержимого подписи в логах и уведомлениях.

В акте проверки фиксируют дату, контур, методы и сертификат по безопасному отпечатку. Это превращает «авторизация работает» в воспроизводимый результат и упрощает следующую замену УКЭП.

Что подготовить для технической поддержки

Если собственная диагностика не выявила причину, обращение должно позволять воспроизвести отказ без передачи секретов. Укажите ИНН организации, товарную группу, подсистему, тестовый или промышленный контур, метод, точное время с часовым поясом, HTTP-код, код и текст ошибки, а также идентификатор операции. Для сертификата достаточно серийного номера или отпечатка и срока действия; закрытый ключ, PIN-код, полный токен и контейнер УКЭП не прикладывают.

К обращению полезно добавить последовательность: получение данных для подписи прошло успешно, подпись сформирована, токен получен, контрольный метод работает, а конкретная операция возвращает 403. Такая запись сразу показывает, на каком уровне находится проблема. Если сбой появился после изменения, укажите дату замены УКЭП, добавления товарной группы, смены роли, версии интеграции или базового URL.

Ответ поддержки сохраняют рядом с внутренним инцидентом и превращают в проверку конфигурации или тест. Тогда при следующем обновлении система сама обнаружит отсутствующую роль, истекающий сертификат или смешение контуров до остановки промышленной очереди.

Порядок диагностики рабочего сбоя

1. Зафиксируйте время, метод, контур, HTTP-код и безопасное тело ответа.
2. Проверьте системное время и срок действия токена.
3. Выполните контрольный запрос теми же данными авторизации.
4. Сверьте организацию, товарную группу и роль пользователя в личном кабинете.
5. Проверьте сертификат и доступ процесса к закрытому ключу.
6. Сопоставьте адрес и версию API с актуальной документацией промышленного контура.
7. После исправления повторите один документ и дождитесь конечного статуса до массового запуска очереди.

Общая схема подключения и обмена разобрана в материале «True API: подключение, авторизация и обмен данными». Отдельно перед обновлением версии API полезен чек-лист перехода с v3 на v4.

Официальные источники

1. «Честный знак»: процесс регистрации в системе маркировки.
2. «Честный знак»: техническая документация True API — актуальные методы и ограничения доступны в разделе «Помощь» промышленного контура.
3. «Честный знак»: требования к УКЭП.
4. «Честный знак»: получение динамического клиентского токена.
5. Честный знак: получение динамического клиентского токена в СУЗ — Порядок динамического токена СУЗ, срок не более 10 часов и необходимые роли..
6. Честный знак: использование обезличенных УКЭП — Официальные ограничения ролей и операций для ОУКЭП..
7. Честный знак: сведения в УКЭП для регистрации — Требования к владельцу и сведениям квалифицированного сертификата..
8. Честный знак: True API получения токена аутентификации — Практический официальный материал сообщества разработчиков; актуальную спецификацию метода следует сверять в разделе «Помощь» промышленного контура..