XDTO-пакет в конфигураторе: типы, свойства, схема XSD и код обмена

Чтобы создать XDTO-пакет в 1С, откройте конфигуратор, в дереве конфигурации раскройте ветку Общие → XDTO-пакеты и добавьте новый элемент. Задайте ему имя и уникальное пространство имён (URI), затем в редакторе пакета опишите типы и их свойства. Если у партнёра уже есть готовая XSD-схема, пакет рисовать не нужно: его создают импортом схемы.

Частое заблуждение разработчиков: XDTO-пакет — это «выгрузка в XML». На деле пакет только описывает структуру данных. Он ничего не выгружает сам. Читает и пишет XML объект ФабрикаXDTO, а пакет даёт ей словарь типов. Механизм общий для платформы 8.3 и одинаково работает в любой конфигурации: БП, ЗУП, УТ или своей.

Как устроена технология XDTO и зачем нужен пакет

XDTO (XML Data Transfer Objects) — слой платформы между прикладными объектами 1С и XML. Он нужен везде, где формат данных задаёт внешняя сторона: веб-сервисы, обмен с сайтом, банком, госсистемой, загрузка файлов по XSD.

Три понятия, без которых дальше не обойтись:

• 📦 Пакет — набор типов с общим пространством имён. Одно пространство имён — один пакет.
• 🧩 Тип значения — простое значение: строка, число, дата, перечисление. Аналог simpleType в XSD.
• 🗂 Тип объекта — составная структура со свойствами. Аналог complexType.
• 🔑 Свойство — поле типа. Бывает элементом, атрибутом или текстом XML.

Фабрика XDTO знает все пакеты конфигурации плюс встроенные платформенные. По URI и имени она находит тип, создаёт по нему объект и проверяет его на соответствие схеме.

Создание XDTO-пакета в конфигураторе: пошагово

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

Шаг 1. Добавить объект

1. Откройте конфигуратор, Конфигурация → Открыть конфигурацию.
2. В дереве раскройте Общие и найдите ветку XDTO-пакеты.
3. Правой кнопкой по ветке — Добавить.
4. В палитре свойств заполните Имя, например ОбменЗаказами.
5. В поле Пространство имён укажите URI, например http://example.ru/orders/1.0.

URI не обязан открываться в браузере. Это просто уникальная строка-идентификатор. Удобно вшивать в неё версию формата: при смене структуры заводите новый URI, и старые клиенты не сломаются.

Шаг 2. Описать типы значений

В редакторе пакета правой кнопкой по корню — Добавить → Тип значения. Укажите имя (например, НомерЗаказа) и базовый тип string из пространства XMLSchema.

Для типа значения задают ограничения (фасеты):

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

Тип значения с перечислением — хороший способ передавать статусы: new, paid, shipped. Фабрика сама отклонит недопустимое значение при проверке.

Шаг 3. Описать типы объектов

Добавить → Тип объекта, имя — Заказ. У типа объекта есть флаги:

• Упорядоченный — свойства в XML идут строго в объявленном порядке (как xs:sequence);
• Открытый — допускает свойства, не описанные в схеме;
• Абстрактный — экземпляр создать нельзя, только наследника;
• Смешанный — текст может стоять между вложенными элементами.

Для обычного обмена достаточно «Упорядоченного». Остальные флаги включайте, только если они есть в исходной XSD.

Шаг 4. Добавить глобальное свойство

Чтобы XML начинался с корневого элемента <Order>, на уровне пакета (не внутри типа) добавьте свойство Order с типом Заказ. Это аналог глобального xs:element. Без него запись тоже возможна, но имя корня придётся передавать в код явно.

Свойства типов и соответствие полей

Свойства — главная работа в редакторе. Для каждого поля типа объекта правой кнопкой по типу — Добавить → Свойство.

Если максимальное количество больше 1 или равно -1, свойство становится списком (СписокXDTO). Так описывают табличные части: строки заказа, позиции накладной.

Имена свойств XDTO чувствительны к регистру. Number и number — разные свойства. В коде 1С вы привыкли к нечувствительности к регистру, здесь она не работает .

Сопоставление полей заказа 1С и пакета удобно держать перед глазами при проектировании:

Импорт и экспорт XML-схемы, WSDL веб-сервиса

Импорт готовой XSD

Если схему прислал партнёр, вручную ничего не рисуйте:

1. Правой кнопкой по ветке XDTO-пакеты — Импорт XML-схемы....
2. Выберите файл .xsd.
3. Платформа создаст пакет с типами и свойствами по схеме.

Если XSD ссылается на другие схемы через import, сначала импортируйте зависимые. Затем добавьте их в список импортируемых пакетов основного пакета. Иначе фабрика не найдёт внешние типы.

Экспорт пакета в XSD

Обратная задача — отдать формат партнёру. Правой кнопкой по самому пакету — Экспорт XML-схемы..., сохраните файл. Его можно сразу проверить любым внешним валидатором XML.

Из кода схема получается так:

Схема = ФабрикаXDTO.ЭкспортСхемыXML("http://example.ru/orders/1.0");

Пакет в веб-сервисе

Веб-сервис 1С работает только через XDTO:

1. Создайте объект в Общие → Web-сервисы.
2. В свойстве Пакеты XDTO выберите свой пакет.
3. У операций и параметров укажите типы из этого пакета.
4. Опубликуйте базу на веб-сервере.

WSDL генерирует платформа. После публикации он открывается по адресу вида http://сервер/ИмяПубликации/ws/ИмяСервиса?wsdl. Отдельно WSDL писать не нужно.

Для обратной ситуации — вы клиент чужого сервиса — в Общие → WS-ссылки добавьте ссылку и укажите адрес WSDL. Конфигуратор сам создаст XDTO-пакеты под типы сервиса.

Проверка пакета до запуска обмена

Перед тем как отдавать схему партнёру или публиковать сервис, прогоните короткую проверку. Она занимает несколько минут и снимает большинство вопросов на стороне получателя.

1. Экспортируйте пакет в XSD и откройте файл. Проверьте targetNamespace, имена элементов и minOccurs.
2. Сформируйте кодом тестовый объект с заполненными обязательными полями и вызовите Проверить().
3. Запишите его в XML и прочитайте обратно через ПрочитатьXML с тем же типом.
4. Отдайте получившийся XML партнёру как образец вместе со схемой.
5. Попросите у партнёра его пример файла и прочитайте его своей фабрикой.

Если пункт 5 проходит без ошибок, формат согласован с обеих сторон. Если нет — расхождение почти всегда в пространстве имён, регистре имён или обязательности полей.

Работа с XDTO-пакетом в программном коде

Создать объект и записать XML

URI = "http://example.ru/orders/1.0";

ТипЗаказ = ФабрикаXDTO.Тип(URI, "Заказ");
ТипСтрока = ТипЗаказ.Свойства.Получить("Item").Тип;

Заказ = ФабрикаXDTO.Создать(ТипЗаказ);
Заказ.Number = "А-0015";
Заказ.Date = ТекущаяДатаСеанса();

Для Каждого СтрокаТЧ Из Документ.Товары Цикл
	Позиция = ФабрикаXDTO.Создать(ТипСтрока);
	Позиция.Sku = СтрокаТЧ.Номенклатура.Артикул;
	Позиция.Qty = СтрокаТЧ.Количество;
	Позиция.Amount = СтрокаТЧ.Сумма;
	Заказ.Item.Добавить(Позиция);
КонецЦикла;

Заказ.Проверить(); // исключение, если объект не соответствует схеме

Запись = Новый ЗаписьXML;
Запись.УстановитьСтроку("UTF-8");
ФабрикаXDTO.ЗаписатьXML(Запись, Заказ, "Order", URI);
ТекстXML = Запись.Закрыть();

Тип вложенного объекта берите из свойства родителя (Свойства.Получить(...).Тип). Так не нужно отдельно объявлять тип строки в пакете под собственным именем.

Прочитать XML

Чтение = Новый ЧтениеXML;
Чтение.УстановитьСтроку(ТекстXML);

Заказ = ФабрикаXDTO.ПрочитатьXML(Чтение, ФабрикаXDTO.Тип(URI, "Заказ"));
Чтение.Закрыть();

Для Каждого Позиция Из Заказ.Item Цикл
	Сообщить(Позиция.Sku + ": " + Формат(Позиция.Qty, "ЧГ=0"));
КонецЦикла;

Для файла вместо УстановитьСтроку используйте ОткрытьФайл(ПутьКФайлу).

Фабрика без пакета в конфигурации

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

Чтение = Новый ЧтениеXML;
Чтение.ОткрытьФайл(ПутьКXSD);
ДокументDOM = Новый ПостроительDOM().Прочитать(Чтение);

Схема = Новый ПостроительСхемXML().СоздатьСхемуXML(ДокументDOM);
Набор = Новый НаборСхемXML;
Набор.Добавить(Схема);

Фабрика = Новый ФабрикаXDTO(Набор);

Дальше с Фабрика работают так же, как с глобальной ФабрикаXDTO: Тип, Создать, ПрочитатьXML.

Ошибки при работе с XDTO и как их устранить

Пара ловушек, которых нет в сообщениях об ошибках:

• 🔁 Смена URI задним числом. Поменяли пространство имён у работающего пакета — все внешние клиенты получат ошибки разбора. Новую версию формата выпускайте новым пакетом.
• 🧮 Числа как строки. Если сумма описана как string, партнёр получит 1 250,00 с пробелом и запятой. Используйте decimal, тогда XDTO запишет 1250.00.
• 🧷 Ссылки 1С в свойствах. Тип свойства из пакета не может быть ссылкой на справочник. Передавайте код, ИНН, артикул или GUID строкой (Строка(Ссылка.УникальныйИдентификатор())).

Частые вопросы