JSON API

Для работы с розничными операциями: продажами, возвратами и т.д. существует специальный POS API.
Документация — https://online.moysklad.ru/api/posap/1.0/doc/index.html
В данной статье содержатся общие сведения по работе с JSON API. Подробная документация — описание структур данных, команд и кодов ошибок, расположена по адресу
https://online.moysklad.ru/api/remap/1.1/doc/index.html

Версия

Программный интерфейс JSON API расположен по адресу https://online.moysklad.ru/api/remap/1.1/. Адрес интерфейса содержит номер версии. Каждая версия API доступна по своему адресу, с указанием своего номера версии. Актуальной в настоящий момент является версия 1.1 (изменения). 

Безопасность и аутентификация

Используется BASIC–аутентификация поверх HTTPS. Для логина нужно использовать тот же логин-пароль, что и при обычной аутентификации в интерфейсе МойСклад. Например:

curl -u логин@компания:пароль \
https://online.moysklad.ru/api/remap/1.1/report/stock/all

Формат данных

JSON API предоставляет возможность обмениваться данными в формате JSON и поддерживает концепцию HATEOAS. Т.е. каждый ответ содержит мета информацию (блоки meta), содержащие ссылки, по которым можно осуществлять дальнейшую навигацию по API.

Тарифные ограничения

JSON API доступен для подписчиков на всех тарифах, кроме Бесплатного.

Ограничения по запросам

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

Листание (paging)

Большинство списков и отчетов поддерживают листание. За него отвечают два параметра:

  • offset — отступ от первого элемента (считается с нуля);
  • limit — кол-во элементов на странице (по умолчанию 25, максимум 100).

Пример

Вывести 50 товаров из списка остатки, начиная с 100-го товара.

curl -u логин@компания:пароль \
https://online.moysklad.ru/api/remap/1.1/entity/product?offset=100&limit=50

Отображение вложенных сущностей (expand)

В API есть возможность дозапрашивать дополнительные данные о вложенных сущностях в рамках одного и того же запроса. Для этого используется параметр запроса expand.

Пример

Допустим, на запрос товара по id:

curl -u логин@компания:пароль \
https://online.moysklad.ru/api/remap/1.1/entity/product/4e36721c-2660-11e5-007d-ff4e000003ce

сервер выдаёт ответ:

{
   "meta": {
       "href": "...",
       "type": "product",
       "mediaType": "application/json"
   },
   "id": "4e36721c-2660-11e5-007d-ff4e000003ce",
   "accountId": "c0c3e19c-2630-11e5-007d-ff4e00000008",
   ...
   "productFolder": {
       "meta": {
           "href": "...",
           "type": "productfolder",
           "mediaType": "application/json"
       }
   },
}

Но необходимо получить информацию о вложенном объекте productFolder (папке товара) сразу же. Для этого можно изменить запрос следующим образом:

curl -u логин@компания:пароль \
https://online.moysklad.ru/api/remap/1.1/entity/product/\
4e36721c-2660-11e5-007d-ff4e000003ce?expand=productFolder

Тогда ответ уже будет включать полную информацию о productFolder:

{
   "meta": {
       "href": "...",
       "type": "product",
       "mediaType": "application/json"
   },
   "id": "4e36721c-2660-11e5-007d-ff4e000003ce",
   "accountId": "c0c3e19c-2630-11e5-007d-ff4e00000008",
   ...
   "productFolder": {
       "meta": {
           "href": "...",
           "type": "productfolder",
           "mediaType": "application/json"
       },
       "id": "145b5258-264a-11e5-007d-ff4e0000017a",
       "accountId": "c0c3e19c-2630-11e5-007d-ff4e00000008",
       "version": 1,
       "updated": "2015-07-13 13:09:36",
       "updatedBy": "admin@acc1",
       "name": "Слишком длинное наименование папки",
       "description": "Описание",
       "code": "123123",
       "externalCode": "8EZZ6BlEjEGo-D3gZoAMm3",
       "pathName": "Папка/Другая папка",
       "article": "",
   },
}
Еще есть вопросы? Отправить запрос

Комментарии

  • Avatar
    Alexander Kalnoy (lazychaser)

    Сыровато, однако. Почему в остатках нельзя получить id товара напрямую (только парсить href)? Почему для цен прилагается только название валюты, но не ее id? Почему для валюты нельзя получить ее текущий курс? Также, ограничения по запросам очень серьезные: я сейчас использую REST-api для автоматического импорта закупочных цен на сайт, и таким образом 10 тыс товаров с помощью JSON api я буду обновлять миллион лет.

  • Avatar
    Максим

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

  • Avatar
    Roman Bolgov

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

    Если "да", то
    - какова дальнейшая судьба в сервисе МС этих файлов по ссылке?

    - что произойдет Если ссылка поломается со временем?
    - если же файл выкачивается МоимСкладом, какой минимально-возможный размер в пикселях Вы бы порекомендовали указывать?

  • Avatar
    Харитонова Юлия

    Изображения загружать через API нельзя. Появится ли такая возможность в дальнейшем - неизвестно.
    Размер в пикселях особой роли не играет, кроме того, как этот файл отображается в интерфейсе МойСклад.

  • Avatar
    Timur

    Здравствуйте! Обнаружил странную вещь.
    Например, выполняю поиск продукта по его коду: https://online.moysklad.ru/exchange/rest/ms/xml/Good/list?filter=code%3Dss140357. Возвращается xml-дерево. У продукта uuid равен 045a5afc-82bf-11e5-7a40-e897003fda30. Пытаюсь получить данные по этому uuid через JSON Api: https://online.moysklad.ru/api/remap/1.0/entity/product/045a5afc-82bf-11e5-7a40-e897003fda30, получаю ошибку «Объект с типом 'product' с идентификатором '045a5afc-82bf-11e5-7a40-e897003fda30' не найден"». Экспериментальным путём выясняется, что в JSON Api этот же продукт имеет id 045a62a7-82bf-11e5-7a40-e897003fda36. Как так?
    Ну и второе, как теперь выполнять фильтрацию данных? (как было тут: https://support.moysklad.ru/hc/ru/articles/203075846-%D0%A4%D0%B8%D0%BB%D1%8C%D1%82%D1%80%D0%B0%D1%86%D0%B8%D1%8F-%D0%B4%D0%B0%D0%BD%D0%BD%D1%8B%D1%85-%D0%B2-REST-%D1%81%D0%B5%D1%80%D0%B2%D0%B8%D1%81%D0%B5).

    Спасибо.

  • Avatar
    dima

    Здравствуйте! Вопрос по поводу прибыльности.
    Ни в REST. ни в JSON API мы не нашли возможностей для извлечения прибыльности (аналогичный вопрос по REST уже задавали). Прибыльность(например. по отгрузкам/возвратам) можно извлечь, только генерируя отчет на сайте. Подскажите. может. мы что-то упустили. и прибыльность можно получить по API?

  • Avatar
    Fotorider

    Здравствуйте!
    В REST-api можно получить документ "Розничные продажи", тип документа - RetailDemand (/exchange/rest/ms/xml/RetailDemand/list)

    Здесь(https://online.moysklad.ru/api/remap/1.0/doc/#/) про розничные продажи ничего нет.

    Реализована ли на данный момент возможность через JSON API получать документ "Розничная продажа" ?

  • Avatar
    Павел Сутырин
    Коллеги, большое спасибо за новый API и, в особенности за HATEOAS и Swagger. Пока что мелочь: в примерах приведено "Слишком длинное наименование папки" - оно действительно слишком длинное? Это кусок другого примера на ошибку? Если так, то как он фигурирует в примере работы с API? Вобщем, или используйте другое имя (не указывающее на ошибку), или раскройте суть ошибки. :) Спасибо!
  • Avatar
    Павел Сутырин
    Немного смущает формат ссылок, например, с product на productfolder - указан сразу href. Допустим, мне нужно отфильтровать продукты по группе - нужно, стало быть, парсить этот урл на предмет uuid папки, и т.д. Потом вы поменяете формат url доступа к productfolder и это сломается. Предложение: добавить попросту в ключ "productfolder" продукта поле id или uuid. Спасибо!
  • Avatar
    Харитонова Юлия
    В старом API справочник номенклатуры имел довольно сложный вид и состоял из товаров, модификаций и серий. Причём непосредственно в документах использовался идентификатор серии для товара. В новом JSON API это постарались упростить и спрятали внутренние связи под идентификаторы серий. Идентификатор для product в итоге соответствует идентификатору серии по-умолчанию из старого API.
  • Avatar
    Харитонова Юлия
    В настоящий момент JSON API средств для получения сведений о прибыльности не содержит. Будет ли это добавлено в дальнейшем - пока неизвестно.
  • Avatar
    Харитонова Юлия
    Формат url для доступа к объектам в рамках одной версии API меняться не будет.
  • Avatar
    Александр
    Здравствуйте! Как через JSON API выполнять фильтрацию данных?
  • Avatar
    Виталий Макеев
    Поддержу вопрос по фильтрации. Интересно насколько далеки планы по добавлению этой возможности в новый API?
  • Avatar
    Вася Садовников
    Документация крайне скудная и небрежная, с кучей пробелов. Нет даже фильтрации по дате -- ни документы за нужный период не получить, ни список изменившихся товаров не вытащить. Как этим вообще пользоваться?
  • Avatar
    Юрий

    В «1.0/entity/counterparty» есть поле «rows.{rowIndex}.mobile». Что это поле означает и можно ли его увидеть в UI?

    Можно ли получить дополнительные кастомные поля стандартных справочников?

  • Avatar
    Юрий

    Как получить листаемый список архивных сущностей?

    Как получить сущности таких типов, как Country и Currency?

  • Avatar
    Андрей Цуваловский

    Добрый день!

    Планируется ли добавление функционала для входящих/исходящих платежей и приходных/расходных ордеров? Если да, то когда?

  • Avatar
    Егор Овчаренко

    Вопросы:
    1. Без фильтрации - как получить список изменений за последние неск. минут (для синхронизации)?
    2. Как поставить/снять резерв на позиции заказа?

  • Avatar
    Виталий Макеев

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

  • Avatar
    Егор Овчаренко

    Виталий, а вы разве не в МоемСкладе работаете? Просто почти все схемы данных,документы и модули, в т.ч. по node.js - от вашего имени выложены, вот я и подумал :)

  • Avatar
    Виталий Макеев

    Нет. Я просто уже очень давно пользуюсь МС и его API )

  • Avatar
    Егор Овчаренко

    Оффтопик: коллеги, а кто-нибудь может подсказать немного по логике работы? Пример: есть 3 шт товара, приходит 5 заказов. Мы ставим все заказы в резерв. После этого в каждом заказе этот товар получается недоступен. Вопрос - как понять, какие заказы отгружать первыми, ведь троим мы же пообещали отгрузку сразу? Я так понимаю можно ставить в резерв по-товарно, но тогда как делать закупку на отсутстующие товары? Они же тогда в закупку не попадут, а если попадут, то после приемки не попадут в резерв и смогут уйти в другой заказ, верно? Спасибо заранее за комментарии!

  • Avatar
    Александр Фомин

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

  • Avatar
    Вася Садовников

    И нам тоже нужна. Выгружать самим десятки тысяч документов для отчётов тяжко.
    На весь АПИ всего два сервиса! - остатки и взаиморасчёты, и всё. Очень не хватает сервисов для того, в чём МС как раз и хорош -- быстрого суммирования позиций по заданным выборкам документов. Странно подобное самим вручную делать.

  • Avatar
    Харитонова Юлия

    Фильтрация появится в ближайшем будущем. Будет ли она покрывать все поля объектов или будет ограничена лишь частью полей - неизвестно. Было бы крайне полезно услышать от вас пожелания по фильтрации - какие объекты и по каким полям вы хотите фильтровать.

  • Avatar
    Харитонова Юлия

    Документацию готовим к обновлению - в ближайшем будущем должна появиться в новом и немного более удобном виде.

  • Avatar
    Харитонова Юлия

    Поле «rows.{rowIndex}.mobile» - это атавизм. Из API и документации будет удалено.

  • Avatar
    Харитонова Юлия

    Листаемый список архивных сущностей скоро можно будет получить - для этого появится специальный параметр.

  • Avatar
    Харитонова Юлия

    Для финансовых документов расширение API планируется в ближайшие месяцы.