Работа с маркетплейсом Ozon требует от продавца не только умения продавать товары, но и глубокого понимания документооборота. Одним из критически важных этапов является передача первичных учетных документов, в частности Универсального передаточного документа (УПД), в электронном виде. Для интеграции с системами электронного документооборота (ЭДО) или для прямой загрузки через личный кабинет часто требуется формирование файла в формате XML. Это обеспечивает автоматическую обработку данных и исключает человеческий фактор при сверке.
Многие селлеры сталкиваются с трудностями при создании корректной структуры файла, так как Ozon предъявляет строгие требования к тегам и атрибутам. Ошибки в разметке приводят к отказу в принятии документа и могут вызвать задержки в бухгалтерском учете. В этой статье мы подробно разберем, как правильно сформировать XML-файл УПД, какие поля обязательны к заполнению и как избежать распространенных ошибок при валидации. Автоматизация этого процесса сэкономит вам десятки часов работы.
Стоит отметить, что ручное создание XML возможно, но в промышленных масштабах это нецелесообразно. Однако понимание структуры необходимо для настройки выгрузок из 1С, MySklad или других ERP-систем. Если вы планируете наладить прямой обмен данными с маркетплейсом, знание технических нюансов станет вашим конкурентным преимуществом. Давайте перейдем к деталям формирования структуры.
Требования Ozon к структуре XML УПД
Прежде чем приступать к генерации кода, необходимо изучить спецификацию, предоставляемую площадкой. Ozon, как правило, ориентируется на стандартные форматы ФНС России, но может иметь собственные расширения или требования к конкретным полям. Основная структура базируется на формате Приказа ФНС России, что гарантирует юридическую значимость документа. Ключевым элементом является корневой тег, который должен содержать все необходимые атрибуты версии и схемы.
Внутри корневой структуры располагаются блоки информации о продавце, покупателе, перечне товаров и итоговых суммах. Каждый элемент должен быть строго типизирован: числовые значения не должны содержать пробелов или валютных символов, а даты обязаны соответствовать формату ГГГГ-ММ-ДД. Нарушение этого правила приведет к мгновенному отклонению файла парсером системы. Валидация происходит автоматически при загрузке.
⚠️ Внимание: Использование кириллицы в названиях тегов или атрибутов категорически запрещено. Все имена элементов должны быть на латинице, согласно спецификации XSD-схемы.
Особое внимание следует уделить кодировке файла. Стандартным требованием является UTF-8. Если ваша система выгружает данные в другой кодировке (например, Windows-1251), при открытии или обработке файла могут возникнуть артефакты в виде "кракозябр", что сделает документ нечитаемым для роботов Ozon. Всегда проверяйте заголовок XML-декларации.
Заполнение реквизитов продавца и покупателя
Первый информационный блок в XML-файле УПД посвящен идентификации участников сделки. Для Ozon, выступающего агентом или комиссионером (в зависимости от схемы работы), или для конечного покупателя, данные должны быть указаны с максимальной точностью. Ошибки в ИНН или КПП приведут к невозможности принять документ к вычету НДС. Поле Идентификатор должно содержать только цифровые значения без лишних символов.
В разделе продавца (Seller) указываются полные реквизиты вашего юридического лица или ИП. Это включает наименование организации, адрес регистрации и контактные данные. Важно, чтобы данные в XML-файле на 100% совпадали с теми, что указаны в вашем договоре с маркетплейсом и в учетной системе. Любое расхождение, даже в одной букве названия улицы, может стать причиной спора.
Блок покупателя (Buyer) заполняется на основе данных, полученных от Ozon в отчете о реализации. Часто здесь требуется указать конкретный склад или подразделение, на которое отгружается товар. В некоторых случаях, при работе через API, эти данные подтягиваются автоматически, но при ручной выгрузке их нужно вносить внимательно.
- 📌 ИНН и КПП должны быть указаны без пробелов и тире.
- 📌 Наименование организации пишется полностью, как в уставных документах.
- 📌 Адрес должен соответствовать ФИАС/ГАР (автоматизированная система адресов).
- 📌 Контактный телефон указывается в международном формате.
Для автоматического заполнения этих полей часто используются справочники контрагентов. Убедитесь, что в вашей базе данных хранятся актуальные сведения. Регулярная сверка реквизитов с данными в личном кабинете Ozon поможет избежать технических ошибок при генерации XML.
Формирование табличной части и номенклатуры
Самая объемная часть УПД — это перечень передаваемых товаров. В XML-структуре этому соответствует повторяющийся набор тегов, описывающих каждую позицию. Для каждой строки необходимо указать наименование, количество, цену за единицу, сумму без НДС, ставку налога и итоговую сумму с учетом налога. Точность вычислений здесь критична: сумма всех строк должна сходиться с итогом документа до копейки.
Особое внимание уделите полю UnitCode (код единицы измерения). Ozon требует использования кодов из Общероссийского классификатора единиц измерения (ОКЕИ). Например, для штук используется код 796, для килограммов — 166. Использование произвольных обозначений ("шт", "кг") в числовых полях недопустимо и вызовет ошибку парсинга.
Если товар имеет маркировку (Честный Знак), в структуру XML необходимо добавить соответствующие теги с кодами DataMatrix. Отсутствие маркировки в документе при ее фактическом наличии на товаре является нарушением законодательства РФ и правил маркетплейса. Система Ozon может автоматически сверять эти данные.
| Поле XML | Описание | Пример значения | Тип данных |
|---|---|---|---|
| ProductName | Наименование товара | Смартфон X | String |
| Quantity | Количество | 10 | Decimal |
| Price | Цена за единицу | 15000.00 | Decimal |
| VatRate | Ставка НДС | 20 | Integer |
При формировании списка товаров важно соблюдать порядок следования тегов, определенный схемой. Нарушение иерархии (например, закрытие родительского тега перед дочерним) приведет к тому, что файл будет признан невалидным. Логическая структура должна быть безупречной.
☑️ Проверка табличной части
Работа с подписями и шифрованием
Просто создать текстовый XML-файл недостаточно для юридической значимости. УПД должен быть подписан электронной подписью (ЭП). В контексте XML это часто реализуется через стандарт XAdES или PAdES, когда к исходному файлу добавляется блок подписи, содержащий хэш-сумму документа и сертификат ключа проверки подписи.
Процесс подписания происходит на стороне отправителя (селлера) с использованием криптопровайдера (например, КриптоПро CSP). Файл может быть подписан отдельно (формат .sig) или подпись может быть внедрена внутрь самого XML (enveloped signature). Ozon принимает оба варианта, но предпочтительнее формат, где подпись вложена в документ, что обеспечивает целостность данных при передаче.
⚠️ Внимание: Срок действия сертификата электронной подписи должен быть актуален на момент подписания документа. Просроченный сертификат сделает УПД юридически ничтожным.
После подписания файл часто рекомендуется архивировать или кодировать в Base64, если передача идет через определенные API-методы, хотя прямой XML также поддерживается. Главное — убедиться, при проверке подписи не нарушена целостность содержимого. Любое изменение байта в файле после подписания invalidates signature.
Для проверки корректности подписи можно использовать бесплатные утилиты от производителей криптографии или онлайн-сервисы проверки ЭП. Это позволит убедиться, что документ будет принят не только системой Ozon, но и пройдет проверку в ФНС при необходимости.
Интеграция через API и автоматическая выгрузка
Для селлеров с большим оборотом ручное создание XML невозможно. В этом случае используется API Ozon. Методы API позволяют передавать данные об отгрузках и получать в ответ идентификаторы документов или готовые файлы УПД, если генерация происходит на стороне площадки. Однако, если вы генерируете УПД сами, API используется для загрузки готовых файлов.
Процесс интеграции выглядит следующим образом: ваша ERP-система формирует пакет документов, подписывает их и отправляет POST-запросом на эндпоинт Ozon. В теле запроса передается сам XML или ссылка на него. Важно соблюдать лимиты на количество запросов (Rate Limit), чтобы не получить блокировку IP-адреса.
POST /api/v1/documents/upload
Content-Type: application/xml
Authorization: Bearer YOUR_API_KEY
<UploadRequest>
<DocumentType>UPD</DocumentType>
<FileContent>BASE64_ENCODED_XML</FileContent>
</UploadRequest>
При использовании API необходимо предусмотреть механизм обработки ответов. Система вернет статус: "Принято", "Ошибка валидации" или "Ошибка подписи". На основе этих кодов ваша система должна либо считать документ проведенным, либо сформировать alert для оператора. Логирование всех обменов данными обязательно для разбора спорных ситуаций.
Что делать при ошибке 429 Too Many Requests?
Если вы получили этот код ответа, значит вы превысили лимит запросов к API. Необходимо реализовать механизм экспоненциальной отсрочки (exponential backoff) в вашем скрипте-интеграторе. Не пытайтесь отправить запрос повторно мгновенно — это усугубит ситуацию.
Частые ошибки и способы их устранения
Даже опытные разработчики сталкиваются с проблемами при работе с XML для Ozon. Самая распространенная ошибка — несоответствие форматов дат и чисел. Например, использование запятой вместо точки в дробных числах (10,5 вместо 10.5) приводит к сбою парсера. Также часто встречается ошибка в кодировке символов, особенно в наименованиях товаров с буквой "ё" или спецсимволами.
Другая группа ошибок связана с бизнес-логикой: неверный расчет НДС, отсутствие обязательных атрибутов для маркированных товаров или несоответствие суммы документа сумме в отчете о реализации. Система Ozon проводит перекрестную проверку, и такие расхождения блокируют документ.
- ❌ Отсутствие тега
Signatureили его некорректное формирование. - ❌ Использование зарезервированных символов XML (<, >, &) в тексте без экранирования.
- ❌ Превышение допустимой длины поля (например, слишком длинное наименование товара).
- ❌ Несоответствие схемы XSD текущей версии требований Ozon.
Для устранения ошибок используйте валидаторы XSD. Загрузите схему, предоставленную Ozon, в редактор кода и проверьте свой XML-файл против нее. Это отсечет 90% технических ошибок перед отправкой. Предварительная проверка экономит время на отладке интеграции.
Вопросы и ответы (FAQ)
Можно ли сформировать УПД в XML без использования платных сервисов ЭДО?
Да, технически возможно. Вы можете использовать бесплатные библиотеки для работы с XML в языках программирования (Python, PHP, C#) или настроить выгрузку в 1С, если ваша конфигурация это позволяет. Однако для юридической значимости вам все равно понадобится действующий сертификат электронной подписи и средство криптографической защиты информации (СКЗИ), которые могут быть платными.
Какой формат даты требует Ozon в XML-файле УПД?
Стандартным и наиболее безопасным форматом является ISO 8601: ГГГГ-ММ-ДД (например, 2026-05-20). В некоторых старых форматах ФНС может встречаться формат ДД.ММ.ГГГГ, но для API и современных интеграций Ozon предпочитает международный стандарт или формат, строго указанный в актуальной XSD-схеме.
Что делать, если сумма в XML отличается от суммы в отчете на 1 копейку?
Такие расхождения возникают из-за округления. В XML суммы должны рассчитываться с высокой точностью, а округление производиться только в итоговом значении, либо следовать правилам математического округления, принятым в ФНС. Если разница уже возникла, необходимо перегенерировать документ с корректными настройками округления в вашей учетной системе.
Нужно ли отправлять XML УПД для каждой поставки отдельно?
Обычно УПД формируется на каждую отгрузку (поставку), которая отражена в акте приема-передачи. Если поставка разбита на несколько коробов, но документально это одна поставка, то и УПД должен быть один. Однако, если Ozon требует разбивки по складам или типам товаров, следуйте инструкции в разделе "Документы" личного кабинета.