Автоматизация обмена данными между 1С и Честным Знаком через API: лучшие практики

Узнайте лучшие практики API‑интеграции 1С с Честным Знаком: ускорьте обработку УПД, автоматизируйте загрузку CSV и обеспечьте надёжный мониторинг обмена данными.

Преимущества прямого API‑интегрирования

Сокращение времени обработки УПД

При традиционной загрузке УПД через пользовательский интерфейс каждый документ проходит несколько шагов: ввод данных, проверка, согласование и передача в кассовую систему. Прямой вызов API позволяет передать полностью сформированный документ из 1С в Честный Знак одним запросом. В среднем время обработки снижается с нескольких минут до 10–15 секунд. Это особенно заметно в компаниях, где ежедневно формируется сотни накладных.

Пример кода, отправляющего УПД через API:

POST https://api.chekznak.ru/v1/upd Headers: Content-Type: application/json Body: { “inn”: “7701234567”, “items”: […], “total”: 125000.00 }

После получения ответа система 1С сразу помечает документ как «Отправлен», без необходимости ручного переключения статуса.

Снижение ручных ошибок ввода

Каждое поле, заполненное оператором, потенциально может стать источником ошибки – опечатка ИНН, неверный код товара или неправильный формат даты. API‑интеграция автоматизирует передачу данных напрямую из внутренней базы 1С, где уже существуют механизмы валидации. В результате количество исправлений падает до меньше 1 % от общего числа отправленных УПД.

Для дополнительного контроля рекомендуется использовать небольшие «пакетные» проверки перед отправкой:

• Проверка уникальности номера УПД в системе Честного Знака;
• Сравнение сумм в накладной и в бухгалтерском регистре;
• Валидация форматов даты и времени согласно ТК 2025‑П.

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

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

Поддержка массовой загрузки и выгрузки

API позволяет работать как с единственными документами, так и с большими пакетами. Сценарий массовой отправки 500 УПД за один запрос экономит не только время, но и сетевые ресурсы, поскольку устанавливается один TCP‑соединение.

Для выгрузки готовых УПД из Честного Знака в 1С также используется простой GET‑запрос. Ответ в формате JSON легко импортируется в справочники и регистры 1С, что делает процесс полностью обратимым.

Настройка соединения 1С с True API

Получение токена доступа по клиент‑ID и клиент‑секрету

Для начала работы с True API необходимо запросить OAuth‑токен. В 1С создаём обработку, где указываем client_id и client_secret, полученные в личном кабинете партнёра. Запрос отправляется методом POST на эндпоинт /oauth/token с параметрами grant_type=client_credentials. Пример тела запроса в формате application/x-www-form-urlencoded:

client_id=ВАШ_ID&client_secret=ВАШ_СЕКРЕТ&grant_type=client_credentials

В ответе API возвращает JSON, содержащий поля access_token, token_type и expires_in. Эти данные сохраняются в настройках интеграции и используются для всех последующих запросов.

Конфигурация HTTP‑запросов в 1С: POST/GET

После получения токена работа с API сводится к обычным HTTP‑вызовам. В 1С рекомендуется использовать объект HTTPСоединение и задавать заголовок Authorization: Bearer <access_token>. Ниже – краткая схема типовых запросов.

• GET – получение справочников, статуса заявок, каталога товаров.
• POST – создание новых заявок, отправка документов, обновление статусов.

Внутри вызова задаём тайм‑аут 30 сек., включаем проверку сертификата и указываем формат данных (application/json).

Обработка кода ответа и ошибок сервера

Ответ API всегда сопровождается HTTP‑кодом. Правильная обработка кода позволяет быстро диагностировать проблемы и автоматизировать повторные попытки.

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

Типовые сценарии обмена через API

Заказ и эмиссия кодов (XML‑запрос)

Для автоматической выдачи кодов Честного Знаком достаточно сформировать XML‑запрос, в котором указываются все необходимые параметры заказа: идентификатор контрагента, тип продукции, количество и срок действия кода. Такой запрос отправляется на эндпоинт /api/v1/codes/issue с указанием токена доступа.

Пример структуры XML‑запроса:

Ответ сервера приходит в виде XML‑файла с перечнем сгенерированных кодов и их статусами. При возникновении ошибок в запросе API возвращает код ошибки и описание причины, что упрощает отладку в 1С.

Ввод товаров в оборот (CSV‑пакет)

При поставке новой партии продукции необходимо загрузить сведения о товарах в систему ЧЗ. Формат CSV‑пакета фиксирован и включает обязательные колонки: артикул, наименование, количество, срок годности, цена и ИНН поставщика.

Примерный вид CSV‑файла:

Артикул,Наименование,Количество,СрокГодности,Цена,ИННПоставщика 12345678,Молоко 1л,500,2026-12-31,55.00,7701234567 87654321,Кефир 0.5л,300,2026-06-15,30.00,7701234567

Файл передаётся методом POST на эндпоинт /api/v1/products/import. После обработки система формирует журнал загрузки, в котором указаны строки, прошедшие проверку, и строки с ошибками (например, неверный ИНН или дублирующий артикул).

Выгрузка отчетов о остатках (CSV‑отчёт)

Регулярный мониторинг наличия кодов и их статуса требует выгрузки отчета из ЧЗ. Запрос делается к эндпоинту /api/v1/reports/stock с указанием периода и желаемого формата (CSV).

В CSV‑отчете присутствуют следующие столбцы:

• Код продукта
• Общее количество
• Количество использованных
• Остаток
• Дата последнего изменения

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

Мониторинг и поддержка интеграции

Логи выполнения задач в 1С

Для успешного управления обменом данных между 1С и Честным Знаком необходимо вести полное журналирование всех операций. В 1С удобно использовать стандартный регистратор РегистраторРегистрации или специализированный обработчик, который записывает:

• Время начала и завершения задачи;
• Идентификатор запроса к API (например, UploadInvoice_2025_03_12_001);
• Статус выполнения (успешно, с ошибкой, частично);
• Текстовое описание ошибки и стек вызовов, если она произошла.

Пример записи в журнале:

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

Уведомления о неуспешных загрузках

Само по себе ведение логов не гарантирует своевременной реакцию на проблемы. Поэтому в системе следует настроить автоматические уведомления, которые будут приходить ответ responsible‑person. Наиболее эффективные каналы:

• Электронная почта – формируется короткое сообщение с ссылкой на запись в журнале;
• Система корпоративных чатов (например, Telegram, Microsoft Teams) – позволяет быстро обсудить проблему в реальном времени;
• SMS‑оповещения – для критических сбоев, требующих немедленного вмешательства.

Типовой шаблон сообщения:

Тема: Ошибка загрузки данных в Честный Знаком – UploadInvoice_2025_03_12_001

Текст:

• Время: 2025‑03‑12 14:05:23
• Контрагент: ООО «Ромашка»
• Ошибка: Недостаточно прав доступа к полю «ИНН»
• Решение: Проверьте заполнение реквизита «ИНН» в справочнике «Контрагенты».

Для повышения надёжности рекомендуется использовать пороговые правила: если в течение часа фиксируется более трёх ошибок одного типа – система повышает уровень уведомления (например, добавляет копию руководителю отдела).

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

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

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

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

Маркировка «Честный знак»

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

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

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

Вопросы и ответы

Как получить токен доступа к API?

Токен запрашивается методом POST на endpoint /oauth/token с параметрами client_id, client_secret и grant_type=client_credentials. В ответе возвращается access_token, который передаётся в заголовке Authorization: Bearer <token>.

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

API ограничивает количество запросов до 30 раз в минуту для каждого токена. При превышении возвращается код 429 Too Many Requests; рекомендуется использовать экспоненциальную задержку и повторить запрос через 1‑2 минуты.

Как отправить один УПД через API?

Сформируйте JSON‑объект с полями inn, items, total и отправьте его POST‑запросом на https://api.chekznak.ru/v1/upd с заголовком Content-Type: application/json и токеном в Authorization. При успешном ответе получаете код 200 OK и статус «Отправлен».

Как выполнить массовую загрузку УПД?

Создайте массив объектов УПД и отправьте один POST‑запрос на тот же эндпоинт /v1/upd. API обработает пакет за один TCP‑соединение, что сокращает время с нескольких минут до нескольких секунд даже для 500 документов.

Как обрабатывать ошибки 401 и 429?

При 401 Unauthorized запрашивайте новый токен и повторяйте запрос. При 429 Too Many Requests вводите паузу (например, 60‑120 сек) и повторяйте запрос, используя экспоненциальное увеличение задержки при повторных ошибках.

Как импортировать полученный CSV‑отчёт в 1С?

Скачайте CSV‑файл из эндпоинта /api/v1/reports/stock, затем в 1С используйте обработку «Загрузка из CSV», указав соответствие колонок (Код продукта, Общее количество, Количество использованных, Остаток, Дата последнего изменения). После загрузки данные сохраняются в регистры остатка.

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

В журнале ошибок создайте правило, которое при записи статуса «Ошибка» формирует сообщение и отправляет его по e‑mail, в Telegram или Microsoft Teams через webhook. При более трёх одинаковых ошибках за час повышайте уровень уведомления, добавляя копию руководителю.

Как проверить статус отправленного УПД?

Выполните GET‑запрос к /api/v1/upd/{id}, подставив идентификатор УПД. В ответе будет поле status («processed», «rejected» и т.д.). При необходимости запросите детали ошибки через поле errorMessage.