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
    Харитонова Юлия

    ZorG zerg

    > Почему бы просто не передавать в запросе ID статуса, без всякой мишуры?

    Потому что ссылка на объект передаётся в виде href внутри meta. Эта ссылка и является идентификатором объекта.

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

    ZorG zerg

    Expand - это фича. Пользуйтесь, оно специально было сделано для удобства получения объекта вместе с вложенными. С тем, что применение этого параметра не особо описано в документации, будем бороться.

  • Avatar
    ZorG zerg

    Юля, спасибо за ответы, на этот раз очень быстрые )
    Еще непонятный момент: через API забрал сейчас все товары и модификации, что примечательно: модификации с признаком archived=1 есть, а вот товаров таких "не приехало". Я правильно понимаю, что архивированные товары я не смогу получить через API?

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

    ZorG zerg

    archived забыли добавить в описание. Скоро появится.
    Допустимые значения параметра: All и Archived

    Но с ним скорее всего в версии 1.2 будут изменения - все ранее добавленные параметры фильтрации уедут в механизмы универсальной фильтрации.

  • Avatar
    ZorG zerg

    И все же, могу я читать архивированные товары через АПИ, или нет?

  • Avatar
    ZorG zerg

    И сам отвечу на свой вопрос: архивный товар я могу выгрузить через АПИ, в том случае, если я обращаюсь к нему по ID напрямую. В этом случае, его свойство archived = 1. Но! Если я хочу выгрузить список товаров, не важно, с фильтрацией или нет, то архивные в этот список не попадают. В связи с этим запрос: исправьте пожалуйста ситуацию, как можно скорее. На мой взгляд это очевидный баг. К слову, у модификаций с этим все хорошо, что какбэ тоже намекает

  • Avatar
    ZorG zerg

    И еще раз отвечу на этот вопрос :) можно запрашивать и архивные товары, но только All и Archived, как вы писали - это неверные значения для параметра archived, а вот archived=true работает. Иными словами, можно запрашивать отдельно архивные и отдельно НЕ архивные, например запросом https://online.moysklad.ru/api/remap/1.1/entity/product?updatedFrom=2016-07-15%2010:00:00&filter=archived%3Dtrue это, честно говоря, очень неудобно, но хотя б так. Изо всех сил жду фикс, а пока рисую костыль (

  • Avatar
    ZorG zerg

    Еще одно наблюдение: если товар отправляется в архив, у него атрибут archive становится true, а вот все его модификации, не смотря на то, что в интерфейсе получают буковку А в начале, по факту в архив не уходят и их атрибут archive остается пустым. Это, видимо баг. Передайте разрабам, пожалуйста

  • Avatar
    Ilia Maltsev

    JSON Schema есть?

  • Avatar
    Александр

    Как удалённые заказы покупателей получить после заданной даты?

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

    ZorG zerg

    archived - это параметр командной строки, а не часть набора фильтров, указываемых в параметре filter.

    Примеры:

    https://online.moysklad.ru/api/remap/1.1/entity/product?archived=NotArchived
    https://online.moysklad.ru/api/remap/1.1/entity/product?archived=Archived
    https://online.moysklad.ru/api/remap/1.1/entity/product?archived=All

    Частично универсальная фильтрация через набор фильтров в параметре filter тоже уже работает (в том числе archived со значениями типа boolean). И заменит в версии 1.2 все ранее добавленные параметры фильтрации.

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

    ZorG zerg

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

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

    Ilia Maltsev

    JSON схема сейчас разбросана по документации. Одним большим файлом не опубликована.

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

    Александр

    Возможность указать даты для фильтрации по дате удаления сейчас отсутствует. С очередным обновлением API будет значительно расширена возможность фильтрации по набору фильтров в параметре filter. И такая возможность появится.

  • Avatar
    Александр

    Сейчас попробовал и работает, но не документирован (deleted=Deleted) запрос https://online.moysklad.ru/api/remap/1.1/entity/customerOrder?deleted=Deleted&updatedFrom=2016-07-15+20%3A50%3A02 он нас устраивает, то что нужно. Можно его использовать или при обновлении сломается?

  • Avatar
    Александр
  • Avatar
  • Avatar
    Андрей

    Добрый день, как определить тип лица (физическое, юридическое или ИП) в списке контрагентов?
    В старом api это был атрибут "companyType", в json api, видимо, ещё не добавили такую возможность?

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

    Андрей

    Поле для определения типа контрагента будет добавлено в одном из ближайших обновлений. Примерно в течение 5-10 дней.

  • Avatar
    Fotorider

    Когда в новом API появится возможность получать остатки по товару, как это было в старом API(https://online.moysklad.ru/exchange/rest/stock/xml)? Можно было получить сумму остатков всех модификаций определенного товара. До сентября появится такая возможность? Очень нужно..

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

    Fotorider

    В новом API есть возможность запросить остатки:

    https://online.moysklad.ru/api/remap/1.1/doc/index.html#%D0%BE%D1%82%D1%87%D1%91%D1%82-%D0%BE%D1%81%D1%82%D0%B0%D1%82%D0%BA%D0%B8

    По составу параметров этот ресурс должен совпадать со старым API. Если это не так, то могли бы указать - в чём необходимо скорректировать работу нового API в части получения отчёта Остатки?

  • Avatar
    Anton

    Есть ли у кого готовый класс на php по работе с api?
    Интересует получения заказа по его номеру, для обновления в CMS при получении изменений через СommerceML

  • Avatar
    Fotorider

    Например, есть товар "Куртка Adidas". У этого товара есть 3 модификации с такими остатками: "Куртка Adidas(черный, 46)" - остаток 2, "Куртка Adidas(черный, 48)" - остаток 3, "Куртка Adidas(черный, 46)" - остаток 5.

    В старом API, по запросу($good_id - id товара "Куртка Adidas"):
    "/exchange/rest/stock/xml?goodUuid=".$good_id;
    получал остаток 10.

    Сейчас, используя запрос "https://online.moysklad.ru/api/remap/1.1/report/stock/bystore?product.id=".$id (где $id - также id товара "Куртка Adidas")
    остаток всегда - 0.

    p.s. для товаров, у которых нет модификаций, остаток выдает правильный.

  • Avatar
    Александр

    Ответьте, пожалуйста, на мои предыдущие вопросы

  • Avatar
    Александр

    Отлично, что появился параметр запроса updatedFrom.
    Вот только как его использовать если нет сортировки по updated (хотя скорее всего у себя в базе вы его проиндексировали). Пока грузишь вторую страницу, может поменяться в первой и документ затеряется

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

    Fotorider

    В старом API используется ID товара. В новом API вместо него необходимо использовать ID серии по-умолчанию для этого товара.

  • Avatar
    Александр

    Про deleted есть в документации https://online.moysklad.ru/api/remap/1.1/doc/index.html#header-параметры-фильтрации-выборки (возможно пропустил в прошлый раз)
    Спасибо

  • Avatar
    Александр

    Про сортировки ответьте, пожалуйста.

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

    > Пока грузишь вторую страницу, может поменяться в первой и документ затеряется

    Александр, я поступаю в таких случаях следующим образом, учитывая что сортировка идет по идентификатору (по умолчанию):
    1. задаю интервал фильтрации по времени (закрытый интервал в прошлом)
    2. получаю список сущностей
    3. если записей в интервале больше чем размер страницы, то получаю следующую страницу с тем-же интервалом по времени, но с фильтром по идентификатору filter=id>{id}, где id - последний идентификатор из полученного списка.
    4. продолжаю листать пока не будет получены все записи
    5. сдвигаю интервал, снова на п.1

    Напиши что думаешь. Получится таким образом?

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

  • Avatar
    Александр

    Думаю, что во время запроса любой последующей страницы(2) может поменяться любой документ из предыдущий страницы(1), а потом и из следующей (3). Если мы смотрим максимальную дату обновления по полученным документам, то окажется max_updated по (3), а (1) будет пропущен и сейчас и при следующих итераций.
    По ID запрашивать здесь никак не поможет, так как документы и так отдаются в порядке создания.

    В поддержке ответили:

    Здравствуйте.
    Увы, в настоящий момент какого-то решения описанной проблемы нет.

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