Загрузка данных из Ordizi в учетную систему

Техническое описание формата XML
Для специалиста, выполняющего интеграцию учетной системы с Ordizi
Версия 1.0

Область документа: Документ описывает загрузку в учетную систему визитов, оплат, заказов и возвратов, сформированных в Ordizi. Выгрузка справочников и оперативных данных из учетной системы в Ordizi описывается отдельным документом.

Содержание

• Назначение документа
• Общая схема передачи данных
• Формирование файлов выгрузки
• Общие требования к XML
• Структура файла
• Детальное описание полей
• Пример XML-файла

1. Назначение документа

Документ предназначен для специалиста, выполняющего загрузку данных из Ordizi в 1С или другую учетную систему.

Сервис обмена Ordizi формирует XML-файлы с документами, созданными торговыми агентами в мобильном приложении. В файл входят визиты, зафиксированные остатки товаров на полке, принятые оплаты, заказы, товары к отгрузке и товары к возврату.

Идентификаторы клиентов, агентов, товаров, единиц измерения, типов цен и типов оплаты передаются в том же виде, в котором они ранее были получены Ordizi из учетной системы. Это позволяет учетной системе однозначно сопоставить полученные документы со своими справочниками.

2. Общая схема передачи данных

1. Торговый агент создает визит и связанные документы в мобильном приложении Ordizi.
2. Данные передаются на сервис обмена Ordizi.
3. Сервис формирует XML-файл в каталоге обмена учетной системы.
4. Учетная система загружает визиты, оплаты, заказы и возвраты из сформированного файла.

3. Формирование файлов выгрузки

3.1. Имя файла

Каждый новый файл выгрузки получает уникальное имя вида exportN.xml, где N — последовательный номер. После успешной загрузки данных в учетную систему файл рекомендуется удалить из каталога обмена или переместить в архив.

export1.xml
export2.xml
export3.xml

Номер в имени файла является номером пакета обмена и не является номером визита или заказа.

3.2. Повторная передача документов

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

При повторной передаче визит выгружается в полном объеме: шапка визита, остатки, оплаты и все связанные заказы. Заказы также могут повторно присутствовать в новом файле.

Поле doc_number является номером документа в Ordizi. Учетная система должна сохранить этот номер и использовать его для идентификации ранее загруженного визита или заказа, чтобы повторная передача не приводила к созданию дублей.

Заказ всегда передается внутри соответствующего визита. Отдельное поле связи заказа с визитом не используется: связь определяется вложенностью узла order в узел visit.

4. Общие требования к XML

• Кодировка файла — UTF-8.
• Корневой узел — <extdata name="ordizi">.
• В одном файле может содержаться один или несколько узлов <visit>.
• Пустой список передается пустым элементом, например <returns/> или <payments/>.
• Строковые и датовые поля без значения передаются пустым элементом.
• Порядок полей внутри каждого узла фиксирован и соответствует примерам настоящего документа.

4.1. Типы данных

Тип	Описание
string	Строковое значение. Идентификаторы обрабатываются как строки и могут содержать ведущие нули.
integer	Целое число.
decimal	Число. Разделителем дробной части является точка.
datetime	Дата и время в формате ГГГГ-ММ-ДДTHH:MM:SS, например 2026-07-14T09:31:02.
integer (0/1)	Логическое значение: 0 — признак не установлен, 1 — признак установлен.

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

5. Структура файла

Узел	Назначение
extdata	Корневой узел файла. Атрибут name имеет значение ordizi.
visit	Документ «Визит». В одном файле может быть несколько узлов visit.
visit/header	Шапка визита.
visit/inventory	Остатки товаров на полке, зафиксированные во время визита.
visit/payments	Оплаты, принятые во время визита.
visit/orders	Заказы, связанные с визитом.
order/header	Шапка заказа.
order/items	Товары к отгрузке.
order/returns	Товары к возврату.

<extdata name="ordizi">
  <visit>
    <header>...</header>
    <inventory>...</inventory>
    <payments>...</payments>
    <orders>
      <order>
        <header>...</header>
        <items>...</items>
        <returns>...</returns>
      </order>
    </orders>
  </visit>
</extdata>

6. Детальное описание полей

6.1. Документ «Визит»

Узел <visit> содержит шапку визита и вложенные списки остатков, оплат и заказов. Связь вложенных данных с визитом определяется их расположением внутри конкретного узла <visit>.

6.1.1. Шапка визита — visit/header

Поле	Тип	Описание
doc_number	string	Номер документа «Визит», сформированный в Ordizi. Учетная система должна сохранить номер для идентификации визита при его повторной передаче.
doc_date	datetime	Дата и время создания визита.
client_id	string	Уникальный идентификатор клиента из файла client.xml.
comment	string	Комментарий к визиту.
agent_id	string	Уникальный идентификатор торгового агента из файла agent.xml.
gps_lat	string	Географическая широта, зафиксированная при оформлении визита.
gps_lon	string	Географическая долгота, зафиксированная при оформлении визита.
gps_sat	integer	Количество спутников при определении координат.
gps_time	datetime	Дата и время определения координат. Если координаты не определялись, поле может быть пустым.

6.1.2. Остатки товаров на полке — visit/inventory

Раздел содержит товары и их фактическое количество, зафиксированное агентом во время визита. Каждая строка передается в отдельном узле <row>.

Поле	Тип	Описание
product_id	string	Уникальный идентификатор товара из файла product.xml.
qty	decimal	Количество товара в базовой единице измерения.
qty_display	decimal	Количество, введенное агентом в выбранной единице измерения.
unit_id	string	Уникальный идентификатор выбранной единицы измерения из файла product_unit.xml.
unit_name	string	Наименование выбранной единицы измерения.
coefficient	decimal	Коэффициент выбранной единицы измерения относительно базовой единицы товара.
base_unit_name	string	Наименование базовой единицы измерения товара.

Количество: qty_display содержит количество в выбранной единице измерения, coefficient — коэффициент этой единицы, qty — количество в базовой единице. Расчет: qty = qty_display × coefficient.

6.1.3. Принятые оплаты — visit/payments

Раздел содержит оплаты, принятые агентом во время визита в счет документов задолженности.

Поле	Тип	Описание
doc_number	string	Номер документа задолженности из файла debt.xml, в счет которого принята оплата.
doc_date	datetime	Дата документа задолженности. Поле может быть пустым, если дата отсутствует.
doc_sum	decimal	Сумма оплаты, полученная во время визита в счет указанного документа.

6.2. Заказы — visit/orders/order

Все заказы передаются внутри соответствующего визита. Один визит может содержать несколько узлов <order>. Каждый заказ включает шапку, товары к отгрузке и товары к возврату.

6.2.1. Шапка заказа — order/header

Поле	Тип	Описание
doc_number	string	Номер заказа, сформированный в Ordizi. Учетная система должна сохранить номер и использовать его для идентификации заказа при повторной передаче.
doc_date	datetime	Дата и время создания заказа.
doc_delivery	datetime	Планируемая дата и время доставки. Поле может быть пустым, если дата доставки не указана.
client_id	string	Уникальный идентификатор клиента из файла client.xml.
price_id	string	Уникальный идентификатор типа цены из файла price_type.xml.
payment_id	string	Уникальный идентификатор типа оплаты из файла payment_type.xml.
comment	string	Комментарий к заказу.
agent_id	string	Уникальный идентификатор торгового агента из файла agent.xml.
doc_sum	decimal	Итоговая сумма заказа.
main_warehouse	integer (0/1)	Признак отгрузки заказа с основного склада. Дополнительное поле, которое может использоваться учетной системой для собственной логики обработки заказа.
call_phone	integer (0/1)	Признак заказа, созданного по телефону без посещения торговой точки: 1 — заказ создан по телефону, 0 — обычный заказ.
return_status	integer (0/1)	Признак компенсационного возврата или обмена. Дополнительное поле, которое может использоваться учетной системой для собственной логики обработки возвратов.

6.2.2. Товары к отгрузке — order/items

Каждая товарная строка передается в отдельном узле <row>.

Поле	Тип	Описание
product_id	string	Уникальный идентификатор товара из файла product.xml.
qty	decimal	Количество товара в базовой единице измерения.
qty_display	decimal	Количество, введенное агентом в выбранной единице измерения.
price	decimal	Цена за одну базовую единицу товара до применения скидки или наценки.
discount	integer	Процент скидки или наценки.
is_markup	integer (0/1)	Определяет назначение поля discount: 0 — скидка, 1 — наценка.
row_sum	decimal	Итоговая сумма строки после применения скидки или наценки и округления. Значение может не совпадать с результатом простого умножения price на qty.
unit_id	string	Уникальный идентификатор выбранной единицы измерения из файла product_unit.xml.
unit_name	string	Наименование выбранной единицы измерения.
coefficient	decimal	Коэффициент выбранной единицы измерения относительно базовой единицы товара.
base_unit_name	string	Наименование базовой единицы измерения товара.

Цена и сумма строки: price содержит цену за базовую единицу до изменения цены. discount содержит процент скидки или наценки, а is_markup определяет вид изменения. row_sum является итоговой суммой строки после применения изменения цены и округления; учетной системе не следует восстанавливать row_sum простым умножением price на qty.

6.2.3. Товары к возврату — order/returns

Раздел содержит товары, оформленные к возврату в рамках заказа. Каждая строка передается в отдельном узле <row>.

Поле	Тип	Описание
product_id	string	Уникальный идентификатор возвращаемого товара из файла product.xml.
qty	decimal	Количество возвращаемого товара в базовой единице измерения.
qty_display	decimal	Количество возврата, введенное агентом в выбранной единице измерения.
price	decimal	Цена за одну базовую единицу возвращаемого товара.
row_sum	decimal	Итоговая сумма строки возврата.
unit_id	string	Уникальный идентификатор выбранной единицы измерения из файла product_unit.xml.
unit_name	string	Наименование выбранной единицы измерения.
coefficient	decimal	Коэффициент выбранной единицы измерения относительно базовой единицы товара.
base_unit_name	string	Наименование базовой единицы измерения товара.

7. Пример XML-файла

Пример показывает один визит, одну строку остатков, одну оплату и один заказ. В реальном файле количество визитов, заказов и строк может быть любым.

<?xml version="1.0" encoding="utf-8"?>
<extdata name="ordizi">
  <visit>
    <header>
      <doc_number>260714093102967</doc_number>
      <doc_date>2026-07-14T09:31:02</doc_date>
      <client_id>00050003</client_id>
      <comment>Комментарий к визиту</comment>
      <agent_id>00000255</agent_id>
      <gps_lat>55.6948</gps_lat>
      <gps_lon>37.3532</gps_lon>
      <gps_sat>8</gps_sat>
      <gps_time>2026-07-14T09:30:58</gps_time>
    </header>
    <inventory>
      <row>
        <product_id>00003005</product_id>
        <qty>40.0000</qty>
        <qty_display>2.0000</qty_display>
        <unit_id>00000002</unit_id>
        <unit_name>уп (20)</unit_name>
        <coefficient>20.0000</coefficient>
        <base_unit_name>шт.</base_unit_name>
      </row>
    </inventory>
    <payments>
      <row>
        <doc_number>INV-25-0104</doc_number>
        <doc_date>2025-06-19T00:00:00</doc_date>
        <doc_sum>1500.0000</doc_sum>
      </row>
    </payments>
    <orders>
      <order>
        <header>
          <doc_number>260714093300563</doc_number>
          <doc_date>2026-07-14T09:33:00</doc_date>
          <doc_delivery>2026-07-15T08:00:00</doc_delivery>
          <client_id>00050003</client_id>
          <price_id>00000001</price_id>
          <payment_id>00000001</payment_id>
          <comment />
          <agent_id>00000255</agent_id>
          <doc_sum>990.0000</doc_sum>
          <main_warehouse>0</main_warehouse>
          <call_phone>1</call_phone>
          <return_status>0</return_status>
        </header>
        <items>
          <row>
            <product_id>00001008</product_id>
            <qty>10.0000</qty>
            <qty_display>1.0000</qty_display>
            <price>110.0000</price>
            <discount>10</discount>
            <is_markup>0</is_markup>
            <row_sum>990.0000</row_sum>
            <unit_id>00000002</unit_id>
            <unit_name>уп (10)</unit_name>
            <coefficient>10.0000</coefficient>
            <base_unit_name>шт.</base_unit_name>
          </row>
        </items>
        <returns />
      </order>
    </orders>
  </visit>
</extdata>