Доступ к ЭДО Лайт по API: механика работы с временным токеном авторизации

Статья описывает пошаговый процесс получения временного JWT‑токена для доступа к API ЭДО Лайт через электронную подпись (УКЭП). Рассматриваются запрос случайной строки, её подпись в CryptoPro CSP и использование токена в заголовке Authorization для работы с документами.

Подготовка к работе с API ЭДО Lite: активация и документация

Активация сервиса в личном кабинете

Для начала работы необходимо зайти в личный кабинет Честного Знака и включить сервис «ЭДО Lite». При включении система предложит принять пользовательское соглашение. После подтверждения соглашения в интерфейсе появляется уникальный ID участника – он будет использоваться во всех запросах к API и служит идентификатором вашей организации.

Получение официальной спецификации

В разделе «Помощь» → «Справочный центр» доступно официальное руководство — «Руководство по интеграции API ЭДО Lite». Скачайте документ и изучите его полностью: в нём перечислены все доступные эндпоинты, требуемые форматы запросов и структуры ответов, а также правила аутентификации и ограничения по частоте запросов.

Тестирование в тестовом контуре

Прежде чем отправлять запросы в боевую среду, рекомендуется отработать интеграцию в тестовом контуре (песочнице) по адресу https://crpt.ru. Песочница полностью имитирует работу продакшн‑системы, но не затрагивает реальные документы и операции. Это позволяет безопасно проверить:

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

Практический пример запроса

После того как вы получили ID участника и ознакомились со спецификацией, типичный запрос к API выглядит так:

POST https://api.crpt.ru/edolite/v1/documents
Content-Type: application/json
Authorization: Bearer <токен>

{
  "participantId": "<ваш ID участника>",
  "documentType": "invoice",
  "payload": { … }
}

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

Следуя этим шагам, вы сможете быстро перейти от настройки сервиса к полноценной интеграции с API ЭДО Lite, минимизируя риски влияния на рабочую систему.

Двухэтапная авторизация через УКЭП: получение временного JWT‑токена

Принцип работы

Авторизация в системе реализована в два этапа: сначала клиент получает «соль» — уникальный набор данных, который затем подписывается квалифицированной электронной подписью (УКЭП). После проверки подписи сервер выдаёт JWT‑токен, действующий от 10 до 24 часов. Токен хранится в оперативной памяти и используется до истечения срока жизни; при необходимости процесс повторяется полностью.

Шаг 1 — запрос «соли»

1. Клиент отправляет GET‑запрос к эндпоинту авторизации, например https://crpt.ru.
2. В ответ сервер возвращает JSON‑объект, содержащий два поля:
   • uuid — идентификатор текущей сессии;
   • data — строку, подлежащую подписи.

Эти данные формируют основу для последующего криптографического подтверждения личности.

Шаг 2 — подпись строки УКЭП

Локальный скрипт (или конфигурация 1С) берёт значение поля data и подписывает его с помощью квалифицированной электронной подписи. Возможные варианты реализации:

• КриптоПро CSP (компонент Windows);
• COM‑объект КриптоПро (удобен в 1С);
• CLI‑утилита КриптоПро (для скриптов без COM).

Подпись должна быть отсоединённой (detached) в формате CMS/PKCS#7 и закодирована в Base64. Результат — строка, которую клиент передаёт серверу.

Шаг 3 — получение JWT‑токена

Клиент формирует POST‑запрос к тому же эндпоинту (или к специализированному токен‑сервису) с телом JSON вида:

{
  "uuid": "полученный‑uuid",
  "data": "<Base64‑подпись>"
}

При корректной подписи сервер отвечает:

• HTTP‑статус 200;
• Тело ответа — объект {"access_token":"Bearer <jwt>", "expires_in":3600} (время жизни 10–24 ч).

Токен сохраняется в памяти приложения и добавляется в заголовок Authorization: Bearer <jwt> всех последующих запросов к защищённым ресурсам.

Практические рекомендации для 1С

• Для HTTP‑взаимодействия используйте объект HTTPService (или HTTPConnection в новых версиях).
• Для подписи применяйте COM‑объекты КриптоПро (CAdESCOM.CPSigner, CAdESCOM.CadesSignedData). Они позволяют получить отсоединённую подпись в требуемом формате без обращения к внешним утилитам.
• Храните полученный JWT‑токен в переменной сеанса; при получении кода ошибки 401 Unauthorized инициируйте повторный цикл авторизации.

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

Работа с API после получения токена: запросы, примеры и типичные ошибки

Формат передачи токена

Токен, полученный после подписи данных, должен присутствовать в заголовке каждого HTTP‑запроса к API:

Authorization: Bearer <токен>

Отсутствие слова Bearer, лишние пробелы или переносы строк приводят к отклонению запроса сервером.

Основные эндпоинты и примеры запросов

Для работы с документами API предоставляет несколько простых методов:

• GET /api/v1/incoming-documents – возвращает список входящих документов (УПД).
• GET /api/v1/incoming-documents/{id}/body – возвращает тело выбранного документа в формате XML.

При формировании запросов достаточно указать URL и добавить заголовок Authorization с действующим токеном. Тело ответа приходит в JSON (для списка) или в XML (для тела документа).

Пошаговый сценарий в Postman

1. Получить UUID и data – выполните GET‑запрос к эндпоинту, который выдаёт uuid и data (обычно это отдельный сервис).
2. Подписать data – откройте страницу КриптоПро, выберите режим detached signature и подпишите полученные data. В результате будет отдельный файл подписи.
3. Отправить подпись – сформируйте POST‑запрос, в теле которого укажите поля uuid и signature (подпись). В ответе придёт токен.
4. Работать с документами – используйте полученный токен в заголовке Authorization для всех последующих запросов к API (см. предыдущий раздел).

Автоматизация этих четырёх шагов позволяет избежать задержек, которые часто приводят к ошибкам.

Типичные ошибки и способы их устранения

При работе с реальными УПД подпись электронной цифровой подписи (ЭЦП) применяется только к XML‑теле документа; токен остаётся в заголовке Authorization и не меняется в процессе подписи. Соблюдение этих правил гарантирует стабильную работу с API без лишних перебоев.

Безопасность и практические рекомендации при работе с токен‑авторизацией

Преимущества токен‑авторизации

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

Риски и потенциальные уязвимости

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

Рекомендации по безопасному использованию

• Защищённое хранилище – размещайте токен в специализированных сервисах (HashiCorp Vault, Azure Key Vault) либо в переменных окружения, доступных только процессу приложения.
• Ограниченный срок жизни – задавайте минимально необходимый TTL, например, 10 ч, чтобы даже при утечке токен быстро стал недействительным.
• Логирование без раскрытия токена – фиксируйте факт выполнения запросов с токеном, но исключайте сам токен из журналов. Это позволяет отслеживать подозрительные активности, не создавая новых точек утечки.
• Интеграция с 1С – используйте объект HTTPService и передавайте токен через заголовок Headers. Такой подход сохраняет совместимость с типовыми механизмами 1С и упрощает настройку.
• Синхронизация сертификатов – регулярно проверяйте соответствие сертификатов, используемых в тестовой и боевой средах. Несоответствие может привести к отказу в аутентификации даже при корректном токене.

Типичные ошибки и их диагностика

При возникновении проблем первым шагом следует обратиться к журналу ответов сервера: в нём содержатся коды ошибок и сообщения, указывающие на неверный формат подписи или просроченный сертификат. Если сервер возвращает ошибку аутентификации, проверьте, что токен актуален и соответствует текущему сертификату. При несоответствии форматов подписи (например, использование SHA‑256 вместо SHA‑1) запрос будет отклонён, даже если токен технически корректен. Регулярный аудит этих параметров помогает избежать простых, но критичных сбоев в работе интеграций.

Полезные сервисы и обновления

Мобильная автоматизация склада

Узнать больше

Маркировка «Честный ЗНАК»

Узнать больше

Розничная торговля и инвентаризация

Узнать больше

Часто задаваемые вопросы

Как получить временный токен доступа к API ЭДО Лайт?

1. Отправьте GET‑запрос на эндпоинт авторизации (см. спецификацию) – сервер вернёт uuid и data.
2. Подпишите полученную строку data вашей УКЭП (КриптоПро CSP, detached‑signature, Base64).
3. Отправьте POST‑запрос с полями uuid и data (подпись) – в ответ получите token (Bearer), действительный 10‑24 ч.

Нужно ли использовать статический API‑Key для доступа к ЭДО Лайт?

Нет. Доступ реализован только через динамический токен, получаемый по двухэтапной схеме с использованием вашей электронной подписи. Статические ключи не требуются и не поддерживаются.

Как ЭЦП и токен работают вместе в процессе интеграции?

ЭЦП используется только на первом этапе – для получения token. После этого все запросы к API передаются с заголовком
Authorization: Bearer <ваш_токен>; подпись не требуется, кроме случаев подписания самого документа (УПД).

Какие ошибки чаще всего возникают при получении токена и как их исправить?

Как безопасно хранить полученный токен?

• Сохраняйте токен в переменных окружения сервера или в защищённом хранилище (Vault, Azure Key Vault и т.п.).
• Не помещайте токен в репозитории кода, конфигурационные файлы без шифрования или в URL‑параметры.
• При завершении сеанса или изменении состава сотрудников отзывайте токен и генерируйте новый.