Создание XML‑файлов для интеграции с Честным Знаком: пошаговый гайд для IT‑отделов
Обновлено:
Подробный пошаговый гайд по созданию XML‑файлов для интеграции с сервисом Честный Знак: от выбора формата до отправки запросов через True API и отладки.
Когда и зачем использовать XML вместо CSV
Внутренние системы, такие как 1С, MyWarehouse и другие ERP‑решения, часто работают с иерархическими данными: товары, их характеристики, склады, цены, налоги. CSV‑формат ограничивается плоской таблицей, где каждое поле – простая строка. При попытке перенести такие структуры в CSV приходится «раскладывать» их по нескольким файлам или использовать сложные конкатенации, что приводит к ошибкам и потере семантики.
XML решает эти проблемы благодаря:
| Критерий | CSV | XML |
|---|---|---|
| Иерархия данных | Отсутствует | Поддерживается вложенными элементами |
| Явные типы и атрибуты | Только строки | Можно задавать типы, атрибуты, схемы |
| Валидация по схеме | Нет | XSD/Schematron позволяют проверять структуру заранее |
| Поддержка электронных подписей | Только в виде отдельного файла | Встроенные элементы для УКЭП |
Для интеграции с сервисом «Честный Знак» это особенно важно: система требует строгой структуры, проверяемой по XSD, а также возможность подписать документ цифровой подписью. XML‑файлы позволяют выполнить обе задачи без дополнительных преобразований.
Полноценная автоматизация через API
API «Честного Знака» принимает запросы в виде XML‑сообщений. Когда данные уже находятся в XML‑формате, их можно отправлять напрямую, минуя промежуточные конвертации. Это снижает нагрузку на серверы, ускоряет обработку и упрощает логирование. Автоматический генератор XML в вашей системе может формировать документ за пару секунд, после чего скрипт отправляет его через HTTPS‑запрос.
Пример типовой структуры запроса:
<Request> <Header> <SenderID>1234567890</SenderID> <Timestamp>2025-03-15T10:20:30Z</Timestamp> </Header> <Body> <ProductList> <Product> <SKU>ABC-001</SKU> <Name>Товар 1</Name> <Price>1999.99</Price> </Product> </ProductList> </Body> </Request>
Сгенерированный файл сразу готов к отправке, а при возникновении ошибки система получит полностью валидный ответ с указанием причины.
Поддержка электронных подписей (УКЭП)
Электронная подпись в XML реализуется с помощью стандарта XML Signature (XAdES). Это позволяет подписать отдельный элемент (обычно ) без изменения остального документа. При встраивании подписи система «Честный Знак» проверяет её целостность и подлинность, что упрощает аудит и соблюдение требований законодательства о работе с электронными документами.
Процесс подписи выглядит так:
- Генерируется исходный XML-файл.
- С помощью криптографии создаётся хэш нужного узла.
- Хэш подписывается закрытым ключом вашей организации.
- Подпись добавляется в элемент согласно XAdES.
После этого файл считается юридически значимым и может быть отправлен без дополнительных действий.
Совместимость с 1С, МойСклад, ERP
Большинство популярных бухгалтерских и складских систем поддерживают экспорт в XML, часто с готовыми шаблонами, соответствующими требованиям ФЗ о маркировке. При построении интеграции стоит использовать:
- Типовые XSD‑схемы, предоставляемые «Честным Знаком», чтобы гарантировать корректность структуры.
- Маппинг полей из 1С (например, объект → ) через встроенный механизм обработки данных.
- Автоматическую проверку подписей и валидности через встроенные в ERP‑модули валидаторы XML.
Таким образом, внедрение XML‑обмена упрощает процесс согласования данных, уменьшает количество ручных операций и повышает надёжность передачи информации между вашими системами и сервисом «Честный Знак».
Структура XML‑запроса для заказа кодов
Элементы <Order> и <Product>
В запросе на присвоение GTIN‑кодов основной контейнер — <Order>. Он задает метаданные всей заявки: идентификатор заказа, дату создания, контактные данные организации‑продавца. Каждый товар, для которого требуется код, описывается отдельным элементом <Product> внутри <Order>. Такая иерархия позволяет системе Честного Знаком быстро сопоставить запросы и сформировать ответы по каждому товару.
Пример минимального шаблона:
<Order id=“ORD-2025-001” date=“2025-03-15”> <Seller> <Name>ООО “Пример"1234567890 <Name>Товар A</Name> <Quantity>100</Quantity> <Price>199.99</Price> </Product> </Products> </Order>
Указание GTIN, количества, цены
Для каждого <Product> необходимо предоставить три обязательных атрибута:
- Quantity — общее количество единиц, подлежащих маркировке. Система учитывает этот параметр при распределении диапазонов GTIN.
- Price — рекомендованная розничная цена. Она используется в аналитических отчётах и при проверке корректности маркировки.
- GTIN — поле оставляется пустым в запросе; после обработки он будет заполнен присвоенным кодом.
Если у товара есть несколько вариантов (размер, цвет), каждый вариант оформляется отдельным элементом <Product> с собственным набором параметров.
Подпись заявки с помощью УКЭП
Для гарантии подлинности и целостности XML‑запроса требуется цифровая подпись, получаемая посредством Устройства Криптографической Элементной Подписи (УКЭП). Процесс выглядит так:
- Сформировать XML‑документ согласно структуре, описанной выше.
- Подписать документ с помощью программного обеспечения УКЭП, которое добавит элемент
<Signature>в корневой узел<Order>. - Проверить корректность подписи с помощью встроенного валидатора, предоставляемого сервисом Честного Знаком.
Подпись подтверждает, что запрос исходит от уполномоченного представителя организации и не был изменён после отправки.
| Элемент | Обязательность | Назначение |
|---|---|---|
| <Order> | Да | Контейнер всей заявки, содержит метаданные и подпись. |
| <Product> | Да | Описывает отдельный товар, для которого требуется GTIN. |
| <Quantity> | Да | Кол‑во единиц товара в заявке. |
| <Price> | Да | Рекомендованная розничная цена. |
| <Signature> | Да | Цифровая подпись УКЭП, подтверждающая аутентичность. |
Визуальный пример готовой структуры запроса показан на изображении ниже.
Отправка XML через True API и обработка ответа
Аутентификация OAuth2
Для работы с True API требуется получить токен доступа по протоколу OAuth2. На этапе интеграции обычно используется «Client Credentials Grant», при котором ваш клиент (приложение) передаёт client_id и client_secret в специальный endpoint авторизации.
Пример запроса (cURL):
curl -X POST https://api.chestnyznakom.ru/oauth2/token \ -d “grant_type=client_credentials” \ -d “client_id=ВАШ_CLIENT_ID” \ -d “client_secret=ВАШ_CLIENT_SECRET”
Ответ – JSON‑объект, в котором находится поле access_token. Токен действителен ограниченный период, после истечения срока его необходимо обновлять тем же запросом.
POST‑запрос к endpoint /orders
После получения токена вы можете отправлять сформированный XML‑файл в метод /orders. Тело запроса – сам XML, а в заголовках указываются:
Authorization: Bearer <access_token>Content-Type: application/xml
Пример кода на Python с использованием requests:
import requests
url = “https://api.chestnyznakom.ru/orders" headers = { “Authorization”: f"Bearer {access_token}”, “Content-Type”: “application/xml” } with open(“order.xml”, “rb”) as f: xml_data = f.read()
response = requests.post(url, headers=headers, data=xml_data) print(response.status_code) print(response.text)
Если запрос прошёл успешно, сервер вернёт XML‑ответ, в котором будет информация о статусе обработки заказа.
Разбор XML‑ответа и запись статусов в БД
Полученный от API XML содержит один или несколько элементов <order> с атрибутами order_id и status. Для дальнейшей работы их следует распарсить и записать в базу данных, чтобы система могла отслеживать состояние каждой заявки.
Ниже представлена простая таблица сопоставления кодов статуса из API с внутренними статусами вашего проекта:
| Код из API | Описание | Внутренний статус |
|---|---|---|
| ACCEPTED | Заказ принят в обработку | В обработке |
| REJECTED | Заказ отклонён (нарушение формата, отсутствие обязательных полей) | Ошибка |
| COMPLETED | Заказ успешно интегрирован в Честный Знаком | Готов |
Пример кода на PHP, использующего SimpleXML и PDO для записи статусов:
$xml = simplexml_load_string($responseBody); $db = new PDO(‘pgsql:host=localhost;dbname=integration’, ‘user’, ‘pass’);
foreach ($xml->order as $order) { $stmt = $db->prepare(” INSERT INTO orders_status (order_id, api_status, internal_status, updated_at) VALUES (:order_id, :api_status, :internal_status, NOW()) ON CONFLICT (order_id) DO UPDATE SET api_status = EXCLUDED.api_status, internal_status = EXCLUDED.internal_status, updated_at = EXCLUDED.updated_at “);
$statusMap = \[
'ACCEPTED' => 'В обработке',
'REJECTED' => 'Ошибка',
'COMPLETED' => 'Готов'
\];
$apiStatus = (string)$order\['status'\];
$internalStatus = $statusMap\[$apiStatus\] ?? 'Неизвестно';
$stmt->execute(\[
':order\_id' => (string)$order\['order\_id'\],
':api\_status' => $apiStatus,
':internal\_status'=> $internalStatus
\]);
}
После выполнения этих шагов ваш сервис будет получать статус каждого заказа в реальном времени и обновлять его в базе, что избавит бизнес‑пользователей от ручного контроля и ускорит обработку заявок.
Тестирование и отладка XML‑интеграции
Валидация схемы XSD
Первый шаг в проверке готового XML‑файла – убедиться, что он полностью соответствует XSD‑схеме, предоставленной Честным Знаком. На практике достаточно использовать любой онлайн‑валидатор или встроенный в IDE плагин. При валидации важно обратить внимание на:
- корректность пространств имён (namespace)
- соответствие типов данных (например,
xs:date—YYYY‑MM‑DD) - наличие обязательных атрибутов и элементов
Пример минимального валидного фрагмента:
<Customer xmlns=“http://www.chestnymznak.ru/schema"> <LegalName>ООО “Пример”</LegalName> <INN>7701234567</INN> <RegistrationDate>2025-01-15</RegistrationDate> </Customer>
Если валидатор возвращает ошибки, их следует исправлять сразу, иначе система Честного Знаком отклонит файл на этапе приёма.
Тестовые запросы в sandbox‑окружении
После успешной валидации файл отправляют в тестовую (sandbox) среду. Здесь проверяется не только синтаксис, но и бизнес‑логика: согласованность данных, уникальность идентификаторов и корректность расчётов.
Типичный сценарий тестовой отправки выглядит так:
- Сгенерировать XML‑файл согласно XSD.
- Отправить запрос через HTTP POST на эндпоинт
https://sandbox.cheznakaz.ru/api/xml(адрес указывается в технической документации). - Получить ответ‑сообщение в формате XML, где в элементе
<Status>указаноSUCCESSилиERROR, а в<Message>– детальное пояснение.
Пример ответа при ошибке:
<Response> <Status>ERROR</Status> <Message>Элемент <INN> не соответствует формату 10‑12 цифр</Message> </Response>
В sandbox‑режиме можно свободно экспериментировать, менять структуру и проверять реакцию системы без риска блокировки реального аккаунта.
Логирование ошибок и автоматический retry
Надёжный процесс интеграции подразумевает автоматическое сохранение всех запросов и ответов. Это помогает быстро находить причину отклонения и устранять её без повторного ручного ввода.
| Поле | Описание | Пример значения |
|---|---|---|
| Timestamp | Дата и время отправки запроса (UTC) | 2025-03-12T14:27:36Z |
| RequestID | Уникальный идентификатор запроса (UUID) | e8f1c2d9‑3a4b‑4c6d‑a9f5‑b2c1d3e4f567 |
| Status | Результат обработки | ERROR |
| ErrorCode | Код ошибки, описанный в справочнике Честного Знаком | 1003 |
| Message | Текстовое описание проблемы | Отсутствует обязательный элемент <LegalName> |
Для автоматического повторного выполнения (retry) рекомендуется внедрить простую стратегию:
- Повторить запрос не более 3 раз;
- Увеличивать интервал ожидания между попытками экспоненциально (например, 5 сек → 15 сек → 45 сек);
- Логировать каждый retry с указанием причины (тайм‑аут, 5xx‑ошибка сервера и т.п.).
Таким образом, даже если в момент отправки возникнет временная недоступность сервиса, система сама справится с восстановлением обмена без вмешательства оператора.
Вопросы и ответы
Почему XML предпочтительнее CSV для обмена данными с сервисом «Честный Знак»?
XML поддерживает вложенную иерархию, типизацию и встроенные подписи, что требуются сервисом для проверки структуры и юридической силы документа, тогда как CSV ограничивается плоской таблицей строк.
Как добавить электронную подпись (УКЭП) в XML‑запрос?
После генерации XML‑файла необходимо использовать программное обеспечение УКЭП, которое вычислит хэш выбранного узла (обычно <Body>) и вставит элемент <Signature> согласно стандарту XML Signature (XAdES).
Какие обязательные элементы должны присутствовать в запросе <Order>?
Обязательны элементы <Order>, <Seller>, <Products> с вложенными <Product>, а внутри каждого продукта – <Quantity>, <Price> и пустой <GTIN>. Также требуется элемент <Signature> для подписи.
Как получить токен доступа OAuth2 для работы с True API?
Отправьте POST‑запрос на https://api.chestnyznakom.ru/oauth2/token с параметрами grant_type=client_credentials, client_id и client_secret. В ответе будет поле access_token, которым следует авторизоваться при последующих запросах.
Что делать, если сервер возвращает статус 500 при отправке XML‑запроса?
Включите механизм автоматического повторения (retry) – до 3 попыток с экспоненциальным увеличением задержки (5 сек → 15 сек → 45 сек) и логируйте каждую попытку. При повторных ошибках обратитесь в техподдержку сервиса.
Как проверить соответствие сформированного XML XSD‑схеме?
Используйте онлайн‑валидатор или встроенный в IDE плагин, указывая путь к XSD, предоставленному «Честным Знаком». Обратите внимание на namespace, типы данных и наличие всех обязательных элементов.
Какие коды статуса возвращает API и как их интерпретировать?
API может вернуть ACCEPTED (заказ принят – внутренний статус «В обработке»), REJECTED (ошибка формата – внутренний статус «Ошибка») и COMPLETED (успешная интеграция – внутренний статус «Готов»). Эти значения сохраняются в базе для отслеживания.
Где хранить лог запросов и ответов для последующего аудита?
Создайте таблицу логов с полями Timestamp, RequestID, Status, ErrorCode, Message и сохраняйте туда полностью XML‑запросы и ответы. Это упрощает поиск причин отклонения и отвечает требованиям контроля.
