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
    Fotorider

    Юлия, спасибо за ответ.

    Что значит серия по-умолчанию для товара? Где она указывается и как получить ее ID?

    На входе у меня есть id одной из модификаций товара

  • Avatar
    Shaha

    Добавьте пожалуйста в список https://online.moysklad.ru/api/remap/1.1/entity/product параметр variants true если есть модификации и 0 если нету, и возможность получать список модификаций с их количеством на складе и ценами для конкретного товара по его айди

  • Avatar
    Shaha

    вторая часть вопроса требует добавления в https://online.moysklad.ru/api/remap/1.1/entity/variant
    простого параметра в виде строки productid на выдаче
    тогда по нему можно будет осуществлять фильтрацию

  • Avatar
    Mail

    Написал простейшего бота для Telegram, который присылает список розничных продаж за сегодня. Кому надо - пишите. Хотя в этом разделе, наверное, все итак это могут))))

  • Avatar
    Aftarburner

    Очень нужна поддержка перемещений в новом API. Пожалуйста. Обещали, но до сих пор не сделали.

  • Avatar
    Fotorider

    Присоединяюсь к Aftarburner, очень нужно получать перемещения через API. Также как и остатки для товаров(см. мои предыдущие комментарии). Почему это все так долго внедряется? МойСклад - это ведь не бесплатный сервис..

  • Avatar
    alpika

    Ищем специалиста: нам надо сделать массовую замену во всех документах(~500) одних позиций(5 позиций по 5 модификаций) другими, заменить только наименования, возможно ли как то автоматизировать этот процесс?

  • Avatar
    ZorG zerg

    А переименование позиций в справочнике не помогает?

  • Avatar
    ZorG zerg

    Мда. Тогда только внешним скриптом

  • Avatar
    alpika

    заведены две одинаковые по смыслу позиции, на каждой по 300-500 документов за пару лет скопилось, хотим одну удалить...
    кто готов сделать - 2279033@gmail.com

  • Avatar
    Максим

    Рекомендую связаться с Точкой Роста, it.abi.soft@gmail.com
    Делали мне такое, довольно быстро и недорого.

  • Avatar
    alpika

    Спасибо Максим, ТочкаРоста готовы облегчить мне жизнь:)

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

    Я правильно понимаю, что привязка платежей и атрибуты к ним в API пока не работают?
    Когда будут реализованы данные фичи?

  • Avatar
    Александр

    Не работает запрос входящих платежей https://online.moysklad.ru/api/remap/1.1/entity/paymentin

  • Avatar
    Александр

    Как получить все заказы покупателей, включая удаленные, за один запрос, когда вы удалите фильтр deleted=ALL?

  • Avatar
    Александр

    На основе отгрузки можно создать предзаполненный шаблон возврата покупателя.
    Хорошо бы по заказу покупателя была возможность создать предзаполненный шаблон для входящего платежа.

  • Avatar
    Юрий

    Александр ранее написал:

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

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

    Я думаю, что Виталий Макеев всё верно подсказал. В случае когда элементы отдаются в порядке создания необходимо делать выборку первой страницы с параметрами limit=100, offset=0, updatedFrom={закрытая-в-прошлом-дата} и updatedFrom={текущая-дата}. А для всех последующих страниц делать выборку используя точно такие же значения параметров запроса, как для первой страницы, и добавляя к ним фильтр filter=id>{id}, где id - последний идентификатор из предыдущей страницы.

    Очень важно, что offset всегда должен быть 0, именно это будет гарантией что вы ничего не пропустите, а в поледующие страницы всегда будут попадать все элементы, которые Вы ещё не проверяли. Ну а в случае если за время всех этих запросов обновятся какие-либо элементы, то эти элементы попадут в будущие выборки, где {закрытая-в-прошлом-дата} будет уже равна предыдущему {текущая-дата}, которая использовалась в прошлых выборках для updatedFrom.

    А вот для элементов, которые сортируются не по id или дате создания так уже не поступишь, там всё значительно усложняется и потребует дополнительных запросов в API.

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

    Из документации: "Ошибка в данном API представляет собой массив errors, содержащий объекты error ..."

    Но, ошибка может прийти в том числе и ввиде объекта, а не массива. К примеру ошибка "Неверно заданы параметры запроса" код 1040.

    Это не баг? Так и должно быть?

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

    Как найти отгрузки, в которых есть товар с таким-то id?

  • Avatar
    Задорожный Дмитрий

    Подскажите, как с помощью Api получить данные о Скидках и ценах каждого контрагента. Запросы вида "/entity/counterparty" или "/entity/counterparty/{id}" не выдают таких данных

  • Avatar
    Anton Danilov

    Здравствуйте.
    https://online.moysklad.ru/api/remap/1.1/entity/assortment?limit=5&filter=archived%3DAll пишет:
    "Неверное значение 'All' параметра фильтрации 'archived', допустимые значения: 'true, false'". Хотя в мануале https://online.moysklad.ru/api/remap/1.1/doc/index.html#header-%D1%84%D0%B8%D0%BB%D1%8C%D1%82%D1%80%D0%B0%D1%86%D0%B8%D1%8F-%D0%B2%D1%8B%D0%B1%D0%BE%D1%80%D0%BA%D0%B8-%D1%81-%D0%BF%D0%BE%D0%BC%D0%BE%D1%89%D1%8C%D1%8E-%D0%BF%D0%B0%D1%80%D0%B0%D0%BC%D0%B5%D1%82%D1%80%D0%B0-filter сказано, что All надо писать, чтобы выводилось всё.

    Подскажите, пожалуйста, как вывести все товары, в том числе и архивные. (Использую фильтрацию по id - т.е. мне нужно запросить конкретные товары и вывести их, даже если они в архиве.)

  • Avatar
    Задорожный Дмитрий

    Здравствуйте! Подскажите, в чем может быть проблема . Настроен пользователь для получения данных. При использовании https://online.moysklad.ru/api/remap/1.1 сервис выдает ошибку 403 Доступ запрещен. Хотя при использовании API версии 1.0 ошибок нет

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

    Задорожный Дмитрий

    > сервис выдает ошибку 403 Доступ запрещен

    Дмитрий, обратитесь в поддержку с описанием проблемы - какие именно ресурсы в API отдают такой ответ.

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

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

    > Как найти отгрузки, в которых есть товар с таким-то id?

    Такую возможность JSON API не предоставляет.

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

    Задорожный Дмитрий

    > как с помощью Api получить данные о Скидках и ценах каждого контрагента

    Описание ресурса для получения сведений о скидках -
    https://online.moysklad.ru/api/remap/1.1/doc/index.html#%D1%81%D0%BA%D0%B8%D0%B4%D0%BA%D0%B8-%D1%81%D0%BA%D0%B8%D0%B4%D0%BA%D0%B8-get

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

    Anton Danilov

    > Подскажите, пожалуйста, как вывести все товары, в том числе и архивные.

    Сожалею, но в документации ошибка - значение All не работает. Для получения всех товаров, включая архивные, необходимо указать параметр archived сразу для двух значений - для true и для false.

    https://online.moysklad.ru/api/remap/1.1/entity/assortment?limit=4&filter=archived=true;archived=false

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

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

    > Из документации: "Ошибка в данном API представляет собой массив errors, содержащий объекты error ..."

    Это баг описания, который не стали исправлять, так как в дальнейшем планируется доделать вывод ошибок к описанному виду. Изменения будут уже в следующей версии API.

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

    Добрый день, пользуемся вашей системой. Ранее делали тз для интеграции МС с другими сервисами, нужными для нашей работы. Теперь нужно было сделать еще одну интеграцию, решил зайти в документацию и обновить свои данные по api. И у меня было удивление наши интеграции сделаны на апи по версии 1.0, сейчас версия 1.1. И вот сравниваю я две версии по структуре ответов и вы их значительно переделали. С какой целью? Если бы эти переделки добавляли удобства, так нет же. К примеру:
    Старая версия:
    запрос - https://online.moysklad.ru/api/remap/1.0/entity/product?limit=1&offset=0
    имеем вот такой ответ по всем видам цен по всем товарам
    http://joxi.ru/XYmE4p9tl0z7r6

    Новая версия:
    запрос - https://online.moysklad.ru/api/remap/1.1/entity/product?limit=1&offset=0
    Ответ: http://joxi.ru/j1A5qJXC8nyqAE
    Вопрос: зачем тип валюты вы завернули в еще один запрос??? т.е. мне теперь отдельно у каждого товара и у каждого типа цены делать еще по 1му запросу?
    а если у меня 5 типов цен будет и несколько валют)) зачем это дергание api?
    Ну и зачем было закупочную цену в ответе засунуть в самый конец ответа за доп полями http://joxi.ru/BLmGYp5HOe11Al ? Это все стало удобней??

    И самый главный вопрос, как долго еще будет работать версия 1.0, т.к. мы потратили на программистов не 1 тыс дол. Теперь выходит что если вы свернете 1.0 и будет только 1.1 то нужно будет переделывать всё, и это опять затраты. Смысл делать какие либо интеграции если вы api постоянно меняете?

  • Avatar
    Roman Bolgov

    Александр Фомин, ввиду Ваших вопросов по изменению API: (можно я отвечу?) это нормальная практика когда его функциональность расширяется/изменяется/дополняется поставщиком (т.е. МоимСкладом). За данным на первый взгляд "неудобным" нововведением (1.0 vs 1.1), стоит реальная необходимость обеспечить функциональность в других, более важных случаях, где например возникает вопрос либо быстродействия, либо возможности интеграции с каким-то сторонним сервисом или же с иными особенностями продаж, с которыми Вы например еще не столкнулись), поэтому не судите только лишь по себе. Это что касается вопроса "Зачем 1.1, вместо 1.0"

    А что касается второго, самого главного Вашего вопроса - то здесь я хотел бы полностью к Вам присоединиться (была бы возможность - заплюсовал вопрос). Меня тоже, очень серьезно беспокоит факт, что та или иная версия API будет поддерживаться впредь. Очень хотелось бы публичное обещание от МоегоСклада, или адекватное упоминание в договоре-аферте.

  • Avatar
    Юрий

    > зачем тип валюты вы завернули в еще один запрос?

    Александр, возможно Вам поможет параметр "expand" для замены ссылок на сами объекты со значениями. Вот тут подробности https://online.moysklad.ru/api/remap/1.1/doc/index.html#общие-сведения-замена-ссылок-объектами-с-помощью-expand