Техническое описание формата XML
Для специалиста, выполняющего интеграцию учетной системы с Ordizi
Версия 1.0
Область документа: Документ описывает выгрузку справочников и оперативных данных из учетной системы в Ordizi. Обратная загрузка заказов и других документов из Ordizi в учетную систему в данном документе не рассматривается.
Содержание
- Назначение документа
- Общая схема выгрузки
- Порядок формирования пакета обмена
- Общие требования к XML
- Типы данных и пустые значения
- Перечень файлов выгрузки
- Детальное описание файлов
1. Назначение документа
Документ предназначен для специалиста, выполняющего выгрузку данных из 1С или другой учетной системы в Ordizi.
Задача интеграции — сформировать в папке обмена набор XML-файлов установленной структуры. Сервис обмена Ordizi принимает эти файлы, обрабатывает данные и передает их в мобильные приложения торговых агентов.
Сервис обмена обеспечивает синхронизацию между учетной системой и мобильными устройствами. Мобильное приложение Ordizi предназначено для работы торговых представителей и использования выгруженных справочников и оперативных данных.
2. Общая схема выгрузки
- Учетная система формирует XML-файлы со справочниками и оперативными данными.
- После полного завершения записи всех XML-файлов учетная система создает или перезаписывает
update.txt. - Сервис обмена Ordizi получает сигнал о завершении пакета, считывает подготовленные файлы и обновляет данные мобильных пользователей.
3. Порядок формирования пакета обмена
3.1. Первичная выгрузка
При первой выгрузке необходимо сформировать полный пакет обязательных XML-файлов со всеми актуальными данными. Опциональные файлы передаются, если в интеграции используются соответствующие функции.
Каждый передаваемый XML-файл должен содержать полный актуальный набор записей своего типа.
3.2. Последующие выгрузки
В последующих сеансах разрешено передавать только те файлы, данные которых изменились. При этом каждый передаваемый файл по-прежнему должен содержать полный актуальный набор записей, а не только добавленные или измененные строки.
Если объект ранее присутствовал в файле, но отсутствует в его новой версии, объект будет исключен из актуального набора данных Ordizi. Если файл не передан, ранее загруженные данные этого типа остаются без изменений.
3.3. Контроль завершения выгрузки: update.txt
Файл update.txt используется как маркер завершения выгрузки. Он не позволяет сервису обмена начать чтение XML-файлов, пока учетная система еще продолжает их формировать. Без такого маркера сервис мог бы получить частично записанный файл и обработать неполные данные.
Порядок работы следующий: учетная система формирует и полностью записывает все XML-файлы текущего пакета, закрывает их и только после этого создает или перезаписывает update.txt. Для сервиса Ordizi это означает, что пакет подготовлен полностью и его можно обрабатывать.
Содержимое update.txt должно изменяться при каждой выгрузке. Если значение осталось прежним, новый пакет не будет обработан. Рекомендуется записывать текущую дату и время с точностью до секунды.
- Имя файла:
update.txt. - Файл создается или перезаписывается последним, после завершения записи всех XML-файлов.
- Значение должно отличаться от значения предыдущей выгрузки.
2026-07-13 12:15:01
4. Общие требования к XML
Имена файлов и их содержимое должны соответствовать настоящей документации. Файлы с неизвестными именами или некорректной структурой будут проигнорированы сервисом обмена.
- Кодировка XML-файлов — UTF-8.
- Корневой узел —
<extdata>. Имя узла является обязательным и фиксированным. Если корневой узел называется иначе, файл не будет обработан. - Атрибут
nameрекомендуется указывать равным имени файла без расширения, например<extdata name="product">. Он служит для обозначения типа данных.
4.1. Внутренняя структура
Внутри корневого узла располагаются два функциональных блока:
<s>(Schema) — описание схемы данных. В этом блоке определяются имена полей и их типы в том порядке, в котором значения будут следовать в блоке данных.<d>(Data) — контейнер данных.<r>(Row) — отдельная строка данных внутри блока<d>.<f>(Field) — значение конкретного поля.
Важно: порядок тегов <f> внутри каждой строки <r> должен строго соответствовать порядку полей, указанному в блоке схемы <s>.
4.2. Общий пример структуры
<?xml version="1.0" encoding="UTF-8"?>
<extdata name="price_type">
<s>
<f name="id" type="string"/>
<f name="name" type="string"/>
</s>
<d>
<r>
<f>00000001</f>
<f>Розница</f>
</r>
<r>
<f>00000002</f>
<f>Опт</f>
</r>
</d>
</extdata>
5. Типы данных и пустые значения
| Тип | Описание |
|---|---|
string | Текстовое значение. |
integer | Целое число. |
decimal | Число. Разделителем дробной части является точка. |
datetime | Дата и время в формате ГГГГ-ММ-ДДTHH:MM:SS, например 2026-01-08T00:00:00. |
Пустое значение поля передается как <f/> или <f></f>. Узел <f> при этом должен оставаться в строке, чтобы порядок значений соответствовал схеме.
6. Перечень файлов выгрузки
Обязательные файлы формируют базовый набор данных и передаются при первичной выгрузке. Опциональные файлы передаются, если используются соответствующие возможности Ordizi.
| Файл | Статус | Назначение |
|---|---|---|
agent.xml | Обязательный | Список торговых агентов (пользователей) и параметры их авторизации. |
client_agent.xml | Обязательный | Закрепление клиентов за конкретными торговыми представителями. |
product.xml | Обязательный | Список товаров. |
product_unit.xml | Обязательный | Единицы измерения товаров и коэффициенты пересчета. |
price_type.xml | Обязательный | Типы цен товаров. |
product_price.xml | Обязательный | Цены на товары. |
product_category.xml | Опциональный | Древовидная или плоская структура групп товаров. |
stock.xml | Опциональный | Текущие остатки товаров на складах. |
client.xml | Обязательный | Список клиентов и торговых точек. |
client_category.xml | Опциональный | Дополнительная классификация (сегментация) клиентской базы. |
payment_type.xml | Обязательный | Перечень доступных способов оплаты, выбираемых при оформлении заказа. |
route.xml | Опциональный | План-график посещений торговых точек. |
debt.xml | Опциональный | Задолженность с детализацией по каждому неоплаченному документу. |
7. Детальное описание файлов
7.1. agent.xml — Торговые агенты
Статус: Обязательный
Файл содержит данные для авторизации торгового представителя и параметры работы мобильного приложения.
Поля
| Поле | Тип | Описание |
|---|---|---|
id | string | Уникальный идентификатор агента в учетной системе. |
user_login | string | Логин агента для синхронизации с сервером обмена. |
user_pass | string | Пароль агента. |
Пример
<?xml version="1.0" encoding="UTF-8"?>
<extdata name="agent">
<s>
<f name="id" type="string"/>
<f name="user_login" type="string"/>
<f name="user_pass" type="string"/>
</s>
<d>
<r>
<f>00000255</f>
<f>ivanov</f>
<f>1234</f>
</r>
</d>
</extdata>
7.2. client_agent.xml — Привязка агентов к клиентам
Статус: Обязательный
Файл определяет закрепление клиентов за конкретными торговыми представителями (агентами). На основании этих данных формируется клиентская база в мобильном приложении каждого агента.
Поля
| Поле | Тип | Описание |
|---|---|---|
client_id | string | Уникальный идентификатор клиента из файла client.xml. |
agent_id | string | Уникальный идентификатор агента из файла agent.xml. |
Пример
<?xml version="1.0" encoding="UTF-8"?>
<extdata name="client_agent">
<s>
<f name="client_id" type="string"/>
<f name="agent_id" type="string"/>
</s>
<d>
<r>
<f>00050000</f>
<f>00000255</f>
</r>
</d>
</extdata>
7.3. product.xml — Справочник товаров
Статус: Обязательный
Файл содержит перечень товаров для формирования каталога в мобильном приложении.
Поля
| Поле | Тип | Описание |
|---|---|---|
id | string | Уникальный идентификатор товара в учетной системе. |
name | string | Наименование товара. |
category_id | string | Уникальный идентификатор категории товара из файла product_category.xml. |
base_unit_id | string | Уникальный идентификатор базовой единицы товара из файла product_unit.xml. |
main_unit_id | string | Уникальный идентификатор основной единицы товара. Используется как единица по умолчанию при работе с товаром в документах. |
sort | integer | Приоритетная сортировка товара в списках. Значение этого поля имеет больший приоритет, чем алфавитная сортировка по наименованию. |
sku | string | SKU, внутренний код или артикул товара для быстрого поиска или идентификации товара в списках. |
Пример
<?xml version="1.0" encoding="UTF-8"?>
<extdata name="product">
<s>
<f name="id" type="string"/>
<f name="name" type="string"/>
<f name="category_id" type="string"/>
<f name="base_unit_id" type="string"/>
<f name="main_unit_id" type="string"/>
<f name="sort" type="integer"/>
<f name="sku" type="string"/>
</s>
<d>
<r>
<f>00001001</f>
<f>Хлеб Бородинский 400г</f>
<f>00000110</f>
<f>00000001</f>
<f>00000002</f>
<f>0</f>
<f>BR-1001</f>
</r>
</d>
</extdata>
7.4. product_unit.xml — Единицы измерения товара
Статус: Обязательный
Файл содержит список всех единиц измерения для каждого товара и коэффициенты пересчета относительно базовой единицы.
Поля
| Поле | Тип | Описание |
|---|---|---|
unit_id | string | Уникальный идентификатор единицы измерения в учетной системе. |
product_id | string | Уникальный идентификатор товара из файла product.xml. |
name | string | Наименование единицы измерения (например: шт., уп., пал.). |
coefficient | decimal | Коэффициент пересчета единицы относительно базовой единицы товара. |
Пример
<?xml version="1.0" encoding="UTF-8"?>
<extdata name="product_unit">
<s>
<f name="unit_id" type="string"/>
<f name="product_id" type="string"/>
<f name="name" type="string"/>
<f name="coefficient" type="decimal"/>
</s>
<d>
<r>
<f>00000001</f>
<f>00001001</f>
<f>шт.</f>
<f>1</f>
</r>
</d>
</extdata>
7.5. price_type.xml — Типы цен товара
Статус: Обязательный
Перечень доступных типов цен на товары. При создании заказа приложение по умолчанию использует тип цены из карточки клиента, с возможностью изменить его вручную в шапке документа.
Поля
| Поле | Тип | Описание |
|---|---|---|
id | string | Уникальный идентификатор типа цены в учетной системе. |
name | string | Наименование типа цены. |
Пример
<?xml version="1.0" encoding="UTF-8"?>
<extdata name="price_type">
<s>
<f name="id" type="string"/>
<f name="name" type="string"/>
</s>
<d>
<r>
<f>00000001</f>
<f>Розница</f>
</r>
</d>
</extdata>
7.6. product_price.xml — Цены на товары
Статус: Обязательный
Файл содержит данные о ценах товаров в разрезе типов цен. Стоимость указывается за базовую единицу товара.
Поля
| Поле | Тип | Описание |
|---|---|---|
price_id | string | Уникальный идентификатор типа цены из файла price_type.xml. |
product_id | string | Уникальный идентификатор товара из файла product.xml. |
price | decimal | Цена товара по данному типу цен за одну базовую единицу. |
Пример
<?xml version="1.0" encoding="UTF-8"?>
<extdata name="product_price">
<s>
<f name="price_id" type="string"/>
<f name="product_id" type="string"/>
<f name="price" type="decimal"/>
</s>
<d>
<r>
<f>00000001</f>
<f>00001001</f>
<f>50.0000</f>
</r>
</d>
</extdata>
7.7. product_category.xml — Категории товаров
Статус: Опциональный
Файл содержит древовидную или плоскую структуру категорий товара. Данные используются для построения группировки товаров при фильтрации по категории. Для плоской структуры значения parent_id во всех строках оставляются пустыми.
Поля
| Поле | Тип | Описание |
|---|---|---|
id | string | Уникальный идентификатор категории товара в учетной системе. |
name | string | Наименование группы товаров. |
parent_id | string | Уникальный идентификатор родительской категории из этого же файла. Если поле пустое, категория является корневой. |
Пример
<?xml version="1.0" encoding="UTF-8"?>
<extdata name="product_category">
<s>
<f name="id" type="string"/>
<f name="name" type="string"/>
<f name="parent_id" type="string"/>
</s>
<d>
<r>
<f>00000100</f>
<f>Бакалея</f>
<f></f>
</r>
<r>
<f>00000110</f>
<f>Хлеб и мука</f>
<f>00000100</f>
</r>
</d>
</extdata>
7.8. stock.xml — Складские остатки
Статус: Опциональный
Файл содержит сведения о текущем количестве товаров на складах. Данные используются для отображения остатков в каталоге. Количество товара всегда указывается в базовых единицах измерения, заданных полем base_unit_id файла product.xml.
Поля
| Поле | Тип | Описание |
|---|---|---|
product_id | string | Уникальный идентификатор товара из файла product.xml. |
stock_qty | decimal | Фактическое количество товара на складе в базовых единицах. |
Пример
<?xml version="1.0" encoding="UTF-8"?>
<extdata name="stock">
<s>
<f name="product_id" type="string"/>
<f name="stock_qty" type="decimal"/>
</s>
<d>
<r>
<f>00001001</f>
<f>25.00</f>
</r>
</d>
</extdata>
7.9. client.xml — Список клиентов
Статус: Обязательный
Файл содержит список клиентов и торговых точек со всеми параметрами, необходимыми для их обслуживания торговым агентом.
Поля
| Поле | Тип | Описание |
|---|---|---|
id | string | Уникальный идентификатор клиента в учетной системе. |
name | string | Наименование торговой точки. |
address | string | Физический адрес клиента. |
category_id | string | Уникальный идентификатор категории клиента из файла client_category.xml. |
price_id | string | Уникальный идентификатор типа цены из файла price_type.xml. Параметр определяет, какие цены из файла product_price.xml будут отображаться для клиента по умолчанию. |
payment_id | string | Уникальный идентификатор типа оплаты из файла payment_type.xml. Параметр определяет, какой тип оплаты будет отображаться для клиента по умолчанию. |
comment | string | Дополнительные инструкции, примечания или комментарии для торгового агента. Максимальная длина — 200 символов. |
contact | string | Имя или ФИО контактного лица в торговой точке. |
phone | string | Номер телефона для связи с контактным лицом торговой точки. |
gps_lat | string | Координата широты для отображения местоположения торговой точки на карте и контроля GPS-координат при посещении. |
gps_lon | string | Координата долготы для отображения местоположения торговой точки на карте и контроля GPS-координат при посещении. |
Пример
<?xml version="1.0" encoding="UTF-8"?>
<extdata name="client">
<s>
<f name="id" type="string"/>
<f name="name" type="string"/>
<f name="address" type="string"/>
<f name="category_id" type="string"/>
<f name="price_id" type="string"/>
<f name="payment_id" type="string"/>
<f name="comment" type="string"/>
<f name="contact" type="string"/>
<f name="phone" type="string"/>
<f name="gps_lat" type="string"/>
<f name="gps_lon" type="string"/>
</s>
<d>
<r>
<f>00050000</f>
<f>Магазин Петров</f>
<f>пр. Мира, д. 37</f>
<f>00000003</f>
<f>00000002</f>
<f>00000002</f>
<f>Нужен пропуск</f>
<f>Дмитрий</f>
<f>8-924-174-82-73</f>
<f>55,6948</f>
<f>37,3532</f>
</r>
</d>
</extdata>
7.10. client_category.xml — Категории клиентов
Статус: Опциональный
Файл предназначен для фильтрации списка клиентов в мобильном приложении. Он позволяет агенту отобразить только тех контрагентов, которые относятся к выбранной категории, например к определенному району.
Примечание: Идентификатор из этого файла указывается в поле category_id файла client.xml.
Поля
| Поле | Тип | Описание |
|---|---|---|
id | string | Уникальный идентификатор категории клиента в учетной системе. |
name | string | Наименование категории. |
Пример
<?xml version="1.0" encoding="UTF-8"?>
<extdata name="client_category">
<s>
<f name="id" type="string"/>
<f name="name" type="string"/>
</s>
<d>
<r>
<f>00000001</f>
<f>Арбат</f>
</r>
</d>
</extdata>
7.11. payment_type.xml — Типы оплаты
Статус: Обязательный
Справочник содержит перечень доступных способов оплаты, например наличный или безналичный расчет. Эти данные используются при создании заказа в мобильном приложении для указания условий платежа.
Поля
| Поле | Тип | Описание |
|---|---|---|
id | string | Уникальный идентификатор типа оплаты в учетной системе. |
name | string | Наименование способа оплаты, которое отображается в интерфейсе приложения. |
Пример
<?xml version="1.0" encoding="UTF-8"?>
<extdata name="payment_type">
<s>
<f name="id" type="string"/>
<f name="name" type="string"/>
</s>
<d>
<r>
<f>00000001</f>
<f>Безналичный расчет</f>
</r>
</d>
</extdata>
7.12. route.xml — План визитов
Статус: Опциональный
Файл содержит данные о планируемых посещениях торговых точек. В мобильном приложении они используются для фильтрации списка клиентов по маршруту на выбранный день.
Поля
| Поле | Тип | Описание |
|---|---|---|
agent_id | string | Уникальный идентификатор торгового агента из файла agent.xml. |
client_id | string | Уникальный идентификатор торговой точки из файла client.xml. |
visit_date | datetime | Дата визита в формате ГГГГ-ММ-ДДTHH:MM:SS. |
sort | integer | Определяет последовательность отображения клиентов в списке при включенном фильтре по маршруту. |
Пример
<?xml version="1.0" encoding="UTF-8"?>
<extdata name="route">
<s>
<f name="agent_id" type="string"/>
<f name="client_id" type="string"/>
<f name="visit_date" type="datetime"/>
<f name="sort" type="integer"/>
</s>
<d>
<r>
<f>00000255</f>
<f>00050000</f>
<f>2026-01-08T00:00:00</f>
<f>999</f>
</r>
</d>
</extdata>
7.13. debt.xml — Задолженность
Статус: Опциональный
Файл содержит сведения о неоплаченных документах. Помимо детализации по накладным, данные используются для информационного отображения общей суммы долга в карточке клиента, а также при оформлении визита и создании заказа. В мобильном приложении предусмотрен прием наличной оплаты в счет погашения конкретного документа из этого списка.
Поля
| Поле | Тип | Описание |
|---|---|---|
client_id | string | Уникальный идентификатор клиента из файла client.xml. |
doc_number | string | Номер первичного документа (накладной, инвойса). |
doc_date | datetime | Дата и время оформления документа в формате ГГГГ-ММ-ДДTHH:MM:SS. |
doc_name | string | Полное наименование документа для отображения в списке, например «Реализация товаров…». |
doc_sum | decimal | Изначальная сумма, на которую был выписан документ. |
debt_sum | decimal | Текущий остаток задолженности по данному документу. |
paid_sum | decimal | Сумма, уже оплаченная по этому документу ранее. Пустое значение допускается и обрабатывается как 0. |
Пример
<?xml version="1.0" encoding="UTF-8"?>
<extdata name="debt">
<s>
<f name="client_id" type="string"/>
<f name="doc_number" type="string"/>
<f name="doc_date" type="datetime"/>
<f name="doc_name" type="string"/>
<f name="doc_sum" type="decimal"/>
<f name="debt_sum" type="decimal"/>
<f name="paid_sum" type="decimal"/>
</s>
<d>
<r>
<f>00050000</f>
<f>INV-25-0100</f>
<f>2025-07-27T16:23:00</f>
<f>Реализация товаров INV-25-0100 от 27.07.2025 16:23:00</f>
<f>16376.87</f>
<f>11348.29</f>
<f>5028.58</f>
</r>
</d>
</extdata>