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.3.0.xsd.
Для работы с перечисленными сервисами требуется BASIC-авторизация. Пользователь, с именем и паролем которого будет происходить обращение к сервису, должен быть наделен правами на работу в административном разделе обмена данными. Для этого необходимо внести пользователя в стандартную группу "Возможность производить обмен данными".
Кириллическое имя пользователя и пароль при входе с BASIC-авторизацией работать не будут, так как в этом случае UTF-8 строка с именем и паролем интерпретируются как ASCII. Чтобы обойти это ограничение BASIC-авторизации, вы можете использовать вместо имени пользователя почтовый адрес, указанный при регистрации учетной записи. Если почтовый адрес указан в более чем одной учетной записи пользователя, то в качестве логина его использовать уже нельзя.
© 2007—2012 ООО «Логнекс» складская программа учета товаров