8 800 250-04-32
+7 495 228-04-32

XML API

МойСклад предоставляет API для обмена данными с внешними системами. API реализован как веб-ресурс, позволяющий вести обмен в формате XML в автоматическом режиме.

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

Однако для полноценной интеграции с внешними источниками и потребителями данных необходим инструмент, не зависящий от ручных операций. МойСклад содержит такой инструмент - это служебный сервис обмена данными.

Доступ к сервису обмена данными открыт зарегистрированным пользователям сервиса МойСклад, обладающим соответствующими правами и подписанным на один из платных тарифов. У пользователей, получивших 30-дневный пробный доступ в МойСклад после регистрации, возможность использовать служебные сервисы обмена данными заблокирована и предоставляется по запросу в отдел поддержки.

Сервис обмена данными содержит два компонента - службу экспорта данных и службу импорта данных.

Служба экспорта данных доступна по адресу:

https://online.moysklad.ru/exchange/xml/export

При обращении к службе экспорта обязательно должен быть указан параметр name, для которого могут быть указаны значения:

  • Metadata - метаданные об объектах (определения атрибутов и пользовательских справочников)
  • Templates - шаблоны печатных форм
  • CustomEntity - Элементы пользовательских справочников
  • Reason - Причины списания-оприходования
  • Country - Страны
  • Gtd - ГТД
  • Currency - Валюты
  • Uom - Единицы измерения
  • GoodFolder - Папки справочника товаров
  • Good - Товары
  • Service - Услуги
  • Goods (включает GoodFolder, Good, Service) - Справочник товаров и услуг (включает товары, услуги, папки)
  • Thing - Серийные номера
  • Consignment - Серии
  • MyCompany - Моя компания и филиалы
  • Agent - Папки справочника контрагентов
  • Company - Компании
  • Person - Частные лица
  • Agents (включает Agent, Company, Person) - Справочник контрагентов
  • Warehouse - Склады
  • Project - Проекты
  • Contract - Контракты
  • ProcessingPlan - Технологические карты
  • Dictionary (включает CustomEntity, Reason, Country, Gtd, Currency, Uom, Goods, Thing, Consignment, MyCompany, Agents, Warehouse, Project, Contract, ProcessingPlan) - словари
  • PriceList - Прайс-листы
  • Demand - Отгрузки
  • Supply - Приемки
  • PurchaseReturn - Возвраты поставщикам
  • SalesReturn - Возвраты покупателей
  • Inventory - Инвентаризации
  • Move - Перемещения
  • Processing - Технологические операции
  • ProcessingOrder - Заказ на производство
  • InvoiceOut - Счета выданные
  • InvoiceIn - Счета полученные
  • Invoices (включает InvoiceIn, InvoiceOut) - Счета
  • Loss - Списания
  • Enter - Оприходывания
  • CustomerOrder - Заказы клиентов
  • PurchaseOrder - Заказы поставщикам
  • InternalOrder - Внутренний заказ
  • Orders (включает CustomerOrder, PurchaseOrder, ProcessingOrder, InternalOrder) - Заказы
  • PaymentIn - Входящий платеж
  • PaymentOut - Исходящий платеж
  • CashIn - Приходный кассовый ордер
  • CashOut - Расходный кассовый ордер
  • Finance (включает PaymentIn, PaymentOut, CashIn, CashOut) - Платежи
  • StockOperation (включает Demand,Supply,SalesReturn,PurchaseReturn,Move,Processing,Loss,Enter) - операции движения товаров
  • Operation (включает StockOperation, Orders, Finance, Invoices, PriceList, Inventory) - все документы
  • All - все данные компании

Опционально могут быть указаны параметры:

  • type
  • operationsFrom
  • operationsTo
  • updatedFrom
  • updatedTo

Параметр type определяет тип выгружаемого файла:

  • inline - данные выгружаются без сжатия
  • zip - результат экспорта будет упакован zip
  • gzip - результат экспорта будет упакован gzip

Параметры operationsFrom и operationsTo позволяют отфильтровать выгружаемые документы по их дате.

Параметры updatedFrom и updatedTo позволяют отфильтровать выгружаемые данные по дате их модификации.

Значения параметров operationsFrom, operationsTo, updatedFrom, updatedTo должны соответствовать формату:

yyyyMMddHHmmss

  • yyyy - год
  • MM - месяц года
  • dd - день месяца
  • HH - час суток (24-часовой)
  • mm - минуты часа
  • ss - секунды минуты

Пример обращения к сервису:

https://online.moysklad.ru/exchange/xml/export?name=Operation&type=gzip&updatedFrom=20090420000000

При обработке приведенного выше вызова сервиса будут выгружены все документы, обновленные позднее 00:00 20 апреля 2009 года.

Служба импорта данных доступна по адресу:

https://online.moysklad.ru/exchange/xml/import

Для импорта данных в формате XML необходимо послать по указанному адресу POST-запрос, указав для него параметр формы encoding со значением multipart/form-data и передав загружаемый файл как часть запроса. Результат импорта будет отображен как результат вызова сервиса.

Опционально могут быть указаны параметры:

  • resolveByCode

Параметр resolveByCode. Если этот параметр указан при импорте, то будет использован механизм распознавания по коду. То есть если поиск существующего объекта в БД будет производиться не по идентификатору, а сначала по коду, и, если объект не найден, то по идентификатору.

При импорте новых и обновлении существующих данных файл с данными обрабатывается по следующим правилам:

  1. Если Вы не указываете идентификатор или указываете идентификатор, которого нет в базе, то будет создан новый объект.
  2. Если Вы указываете идентификатор существующего объекта, то объект будет обновлен.
  3. Для загрузки взаимосвязанных данных (например для загрузки папок и связанных с ними товаров) внутри файла импорта можно использовать "суррогатные" идентификаторы. То есть папка с таким идентификатором после загрузки будет содержать все те товары, для которых в атрибуте parentId будет указан идентификатор этой папки. Сам идентификатор при этом будет использован только при загрузке и будет заменен на новый по создании соответствующего объекта.
  4. Если в загружаемом узле XML есть узел version, то тогда при загрузке будет учтена версия объекта и при попытке загрузить объект с версией не совпадающей с существующей будет выдана ошибка.
  5. Если Вы работаете с несколькими филиалами, то с помощью узла company, указываемого для каждого объекта, вы можете манипулировать припиской этого объекта к соответствующему филиалу. В ином случае узел company можно опустить.

Кстати, с форматом XML для загрузки данных на сервис можно ознакомиться, выгрузив свои существующие данные. Например, создайте вручную несколько заказов от покупателей и выгрузите данные в МойСклад XML - в полученном файле вы сможете найти пример того, как в каком формате должны быть импортированы данные (заказы) к нам на сервис.

Обратите внимание на атрибуты id и version. Они должны быть указаны только при обновлении существующих данных. При импорте новых заказов эти атрибуты должны отсутствовать.

Для импорта новых заказов, связанных с существующими элементами справочников, необходимо в соответствующих атрибутах указать идентификаторы ранее загруженных на сервис данных - товаров, контрагентов и т.п. Если же элементы справочников, на которые ссылаются новые заказы на момент импорта еще не существуют, их можно импортировать вместе с самим заказом, указав, например, для товара уникальный в рамках загружаемого файла XML идентификатор (атрибут id) и указав данный идентификатор в позиции заказа (атрибут goodId).

Описание формата файла XML на языке XSD Schema можно загрузить по адресу exchange-1.3.0.xsd.

Для работы с перечисленными сервисами требуется BASIC-авторизация. Пользователь, с именем и паролем которого будет происходить обращение к сервису, должен быть наделен правами на работу в административном разделе обмена данными. Для этого необходимо внести пользователя в стандартную группу "Возможность производить обмен данными".

Кириллическое имя пользователя и пароль при входе с BASIC-авторизацией работать не будут, так как в этом случае UTF-8 строка с именем и паролем интерпретируются как ASCII. Чтобы обойти это ограничение BASIC-авторизации, вы можете использовать вместо имени пользователя почтовый адрес, указанный при регистрации учетной записи. Если почтовый адрес указан в более чем одной учетной записи пользователя, то в качестве логина его использовать уже нельзя.