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. Если этот параметр указан при импорте, то будет использован механизм распознавания по коду. То есть если поиск существующего объекта в БД будет производиться не по идентификатору, а сначала по коду, и, если объект не найден, то по идентификатору.

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

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

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

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

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

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

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

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

Обновления

Вы можете всегда увидеть описание последних изменений в API в специальном форуме - https://moysklad.zendesk.com/forums/20732298-api При необходимости Вы можете подписаться на рассылку новых статей из этого форума и получать информацию об обновлениях по почте.