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
    Сергей Сергеевич

    Когда вес и объем наконец то добавите, в предыдущем апи кормили обещаниями больше 2 лет, в новом так и не добавили!

  • Avatar
    Alexander Simbirtsev

    Юлия, обновление наконец-то вышло, спасибо!
    Можете теперь пояснить, как удалять позиции из заказа или сам заказ?
    В обновлённой документации про это не смог найти ничего.

  • Avatar
    ZorG zerg

    Обещали, что в этом обновлении появятся инструменты фильтрации для запросов. Не появилось, или я плохо читаю? Доступ к полю ШК в модификациях так же отсутствует?

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

    Здравствуйте! Есть необходимость при создании/изменении товара через Api загружать изображение. Делаю это, задав в массив images данные, вида

    "images"=> {
    [
    "meta"=> array(
    "href"=> "http://sitename/files/filename.jpg",
    "type"=> "file",
    "mediaType"=> "image/jpeg",

    ),
    "size"=> 28600,
    "title"=> 'file',
    "filename"=> 'filename.jpg',
    ]
    }

    Товар создается, но без изображения. Подскажите в чем может быть ошибка

  • Avatar
    Dmitry Aleksandrov

    Господа, не подскажете, как при создании нового контрагента сразу создавать и его счета (accounts) ? Как я понял, для счета поле ссылки на агента обязательно, но на момент создания ссылки не существует.

  • Avatar
    Andrejs Krotovs

    Хотим реализовать импорт/экспорт данных для сайта, но не смогли понять несколько вещей:
    1) возможно ли получение файлов печати PDF для заказов покупателя и счетов покупателя
    2) возможно ли как-то связать счет и заказов покупателя и счет покупателя

    Просто эти данные в онлайн есть, а в API я не смог их найти

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

    В документации не указан формат строки для фильтрации по updated.
    Также не указано, в каком часовом поясе должна быть указана дата.
    (Надеюсь, что в этой версии АПИ наконец-то будут даты по UTC))

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

    Andrejs Krotovs
    1) Нет, невозможно.
    2) Пока такой возможности нет. Появится скоро.

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

    Вася Садовников
    Документацию исправим. Формат - yyyy-MM-dd HH:mm:ss
    Все даты - в MSK (GMT+3)

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

    Даты навсегда останутся в GMT+3? Даже если снова появится переход на летнее время?

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

    Вася Садовников
    По крайне мере в этой версии JSON API даты в MSK.

  • Avatar
    ZorG zerg

    Юля, ответьте пожалуйста, на несколько вопросов: 1. Когда можно ожидать доступ к полям "Штрихкод" в товарах и модификациях? 2. Когда появятся (появятся ли?) другие параметры для фильтрации? 3. Когда появится (появится ли?) возможность удалять сущности? 4. Можно ли управлять сортировкой отдаваемых списков (когда это будет реализовано)?

  • Avatar
    Andrejs Krotovs

    Юлия, а получение PDF (и других файлов) заказов/счетов и т.д. или хотя бы адреса ссылки на них совсем не планируется? Может есть какой-то альтернативный вариант? Клиент хочет держать копии всех документов локально.

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

    ZorG zerg
    Примерно 10-11 июня планируется обновление. В нём будут штрихкоды, удаление и будут изменения в уже существующей структуре. От этого все изменения попадут в версию 1.1, а версия 1.0 будет поддерживаться ещё примерно 2 месяца.
    Фильтрация "по любому полю" скоро не появится. Возможно к сентябрю - не ранее. Управление сортировкой не планируется.

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

    Andrejs Krotovs
    Ссылки на печатные формы в плане. По срокам - не ранее осени.

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

    ZorG zerg
    Опубликована версия JSON API 1.1
    Появились штрихкоды и возможность удаления. Измениласть структура объектов и появилась возможность работы с метаданными объектов.

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

    Юлия, подскажите, когда добавите финансовые документы?

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

    Кто-нибудь из участников темы писал синхронизацию со своей БД через новый API?

  • Avatar
    ZorG zerg

    2 Харитонова Юлия
    Спасибо за ответ, хоть и не быстрый

    2 Виталий Макеев
    Угу, я пишу, только синхронизация не полная - выборочная, для пары костылей

  • Avatar
    ZorG zerg

    2 Харитонова Юлия
    Еще вопрос разрабам, если позволите. Хочу сменить через API статус заказу. Отправляю PUT запросом "state":{"name":"Готов к отгрузке"} - статус у заказа изменяется, все хорошо. Отправляю "state":{"id":"c39474fc-91e0-11e5-7a69-9711000560db"} - ничего не происходит.

    Ребят, НУ КАК ТАК ТО?!!!!!

    Это ж id!! Это ключ, который однозначно идентифицирует запись в базе! Почему используя его я в очередной раз натыкаюсь на какие-то сотонинские грабли? Не, ну может были какие-то причины, конечно, но вы поведайте тогда. Я пойму и прощу. Честно говоря, боюсь пробовать изменять другие атрибуты и у других сущностей. Чувствую опять постигнет меня великое разочарование.

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

    Андрей Цуваловский
    Финансовые документы будут добавлены в обмен примерно через две недели.

  • Avatar
    dima

    Подскажите, пожалуйста, как получить всю номенклатуру одним списком (товары и модификации) с помощью JSON API. Получается что можно получить отдельно товары (/entity/product) и отдельно модификации ((/entity/variant). Но для каждой модификации еще необходимо запрашивать информацию о параметрах товара, что может выполняться достаточно долго.
    Есть еще вариант использовать Товары в рознице (/pos/assortment). В документации написано: "В списке розничных товаров выводятся как сами товары, так и их модификации." Но здесь у нас возникла проблема:если товары имеют модификации, то эти товары не выводятся в списке, а выводятся только модификации товара. Судя по всему, это ошибка в работе API.

  • Avatar
    Aftarburner

    Когда в новом API появятся перемещения? Это для нас критично. Нужно успеть мигрировать со старого API. Не так много времени уже до 1 сентября-то.

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

    В недавнем обновлении для JSON API 1.1 были добавлены новые типы документов:
    Заказ поставщику, Счёт поставщика, Возврат поставщику, Приёмка, Возврат, все виды финансовых документов, кроме розничных.
    В Отгрузку и Приёмку добавлены накладные расходы.
    Добавлена возможность обнулять ссылки на объекты, передавая в качестве значения null.
    Существенно расширены метаданные по объектам и их компонентам.

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

    ZorG zerg

    Статусы теперь можно обновить по идентификатору.

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

    dima

    Для получения номенклатуры одним списком вскоре появится один источник данных - assortment (не в рознице). С его помощью можно будет получить весь каталог товаров сразу.

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

    Aftarburner

    Перемещения уже находятся на тестировании. Ориентировочно релиз с ними будет в конце следующей недели.

  • Avatar
    ZorG zerg

    хм... вы это серьезно? теперь чтобы обновить у заказа статус, я должен сделать PUT с такими параметрами: {'state':{'meta':{'href':'https://online.moysklad.ru/api/remap/1.1/entity/customerorder/metadata/states/88d4f2f1-2e04-11e6-7a69-8f5500018e82', 'type' => 'state'}}}

    Это такое изощренное издевательство, что ли, или есть способ легче, просто я его в документации найти не могу? М?

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

    {state:{id:88d4f2f1-2e04-11e6-7a69-8f5500018e82}} и все блин! ну просто ведь, дык не работает же (((

  • Avatar
    ZorG zerg

    Еще скажите пожалуйста, параметр expand, который позволяет развернуть какой-либо параметр в сущности в одном запросе. Сейчас про этот параметр в документации ни слова, несколько раз только встречается в примерах, касаемых остатков. Означет ли это, что он будет выводиться из использования? И если это планировалось, то можно ли попросить этого не делать, т.к. это очень удобная штука. Более того, сейчас expand позволяет разворачивать несколько атрибутов, например state и agent для заказа покупателя. Интересно, это баг или фича? ))