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

    Средства для обновления объектов практически уже готовы. Следите за обновлениями и документацией.

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

    Country и Currency запланированы и появятся в течение месяца примерно.

  • Avatar
    Павел Махнёв

    Возвращаются цены без точки, либо с точкой, но всегда в 100 раз больше, чем надо. Это явный и очень не приятный баг.

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

    Павел, напишите, пожалуйста в поддержку - какое именно поле содержит цену без точки в 100 раз больше, чем надо.

  • Avatar
    Павел Махнёв

    Если выгрузить остатки, и в них есть настроенные цены ("цены продажи", в каждом из товаров), то вместо 7 538,00 возвращается 753800.

    Пример про 1500.00 руб:

    "salePrices": [
    {
    "value": 150000,
    "currency": "руб",
    "priceType": "Цена продажи"
    },
    {
    "value": 0,
    "priceType": "Предзаказа"
    },
    {
    "value": 0,
    "priceType": "Розница"
    }

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

    Так это всегда так - цена в копейках.

  • Avatar
    Павел Махнёв

    Я не против, мне главное знать, что это внезапно не поменяется и все товары на сайте внезапно не станут стоить в 100 раз меньше чем мне надо. )

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

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

  • Avatar
    Павел Махнёв

    Хорошо, спасибо, я просто был не уверен. Извините за то что потратил ваше время )

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

    Подскажите, пожалуйста, а импорт (создание) заказов работает? У меня система упорно требует id...

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

    Андрей, импорт заказов работает. Напишите заявку в поддержку с описанием отсылаемого на сервер JSON.

  • Avatar
    Alexander Simbirtsev

    Может, быть я что-то проглядел, но есть ли в JSON API возможность увеличить остатки на складе?

  • Avatar
    Alexander Simbirtsev

    И второй вопрос: как мне через API создать возврат покупателя?
    Как я понял, сначала нужно для заказа создать отгрузку (при этом непонятно, как через API сделать так, чтобы отгрузка была связана с заказом, но отгрузки хотя бы упомянуты в описании API), а как далее создать возврат?

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

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

  • Avatar
    Alexander Simbirtsev

    Не могу понять, как удалять позиции из пользовательского заказа:
    изначально сохраняю в заказе позиции "А", "Б", "В", после редактирования заказа на сайте сохраняю позиции "А", "Б", "Г", в итоге в моём складе в заказе наблюдаю "А", "Б", "В", "Г".

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

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

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

    Александр, удаление позиций и управление ими пока не реализовано в окончательном виде. В течение пары недель будет релиз с большими изменениями как раз в этой части.

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

    Александр, работа с позициями документа в новом API должна появиться в течение недели. Это имеет смысл подождать. Но удаление заказов мало будет отличаться от старого API. Изменится лишь базовая часть адреса, а суть останется прежней - запросом GET можно будет удалить объекта, указав идентификатор этого объекта как часть URL.

  • Avatar
    ZorG zerg

    Добрый день. Хочу исправить значение одной характеристики в модификации. Пытаюсь это сделать со страницы документации JSON API.

    В поле entityId указываю id нужной мне модификации, в поле body вот такой JSON
    {
    "meta": {
    "href": "https://online.moysklad.ru/api/remap/1.0/entity/variant/0b12e0cc-a24d-11e5-7a69-9711001d174c",
    "type": "variant",
    "mediaType": "application/json"
    },
    "id": "0b12e0cc-a24d-11e5-7a69-9711001d174c",
    "accountId": "846be844-5af5-11e5-90a2-8ecb00002ae3",
    "version": 38,
    "updated": "2015-12-16 01:25:11",
    "name": "Основа VP21 (1 л, 03мг, Velvet Cloud (80/20))",
    "code": "00219",
    "externalCode": "p6-4aZS4gCBfhubaC1BaE2",
    "characteristics": {
    "Объём": "1 л",
    "Тип смеси": "Velvet Cloud (80/20)",
    "Никотин": "03 мг"
    },
    "buyPrice": {
    "value": 0
    },
    "salePrices": [
    {
    "value": 99900,
    "priceType": "Цена продажи"
    },
    {
    "value": 0,
    "priceType": "Старая цена"
    },
    {
    "value": 0,
    "priceType": "РРЦ"
    }
    ],
    "product": {
    "meta": {
    "href": "https://online.moysklad.ru/api/remap/1.0/entity/product/2a57c30b-5b31-11e5-7a07-673d0121e78e",
    "type": "product",
    "mediaType": "application/json"
    }
    }
    }

    В ответ приходит такое:
    Тело ответа
    {
    "errors": [
    {
    "error": null,
    "code": 400
    }
    ]
    }
    HTTP код ответа
    400

    Что я делаю не так?

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

    В новом API другая схема идентификации в справочнике товаров. Можете попытаться запросить список модификаций и из него вытащить нужный идентификатор. Или можете получить его из старого API - это идентификатор серии по-умолчанию для нужной модификации.

  • Avatar
    Aftarburner

    Как вывести UUID нового типа, идентифицирующий товар, в шаблон Excel?

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

    К примеру ${position.consignment.id}

  • Avatar
    Aftarburner

    Виталий, откуда у вас берется position? Если это строка вывода отчета, то так не работает. И многими другими способами тоже.

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

    position - это объявленная в теге цикла переменная строки. В виде, приведённом Виталием, будет работать в отчётах по спискам документов (реестрах документов).

  • Avatar
    Aftarburner

    Юлия, "отчёт по списку документов" -- это просто список документов. Это не отчет. Суть отчета в какой-либо агрегации, например, вычисление итоговых сумм. Меня интересует, как выводить uuid-идентификаторы, признаваемые вашим новым API, в шаблоне ОТЧЕТА. Например, остатков товара по складам.

  • Avatar
    Алексей Валериевич

    Вопрос напрямую относится к вашему выпуску бета версии АПИ. Дайте на него пожалуйста ответ. Нам хотелось бы решить этот вопрос сейчас. Измените ли вы дату прекращения поддержки или уберете вовсе? Либо нам в срочном порядке разрешать этот вопрос сменой системы?

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

    Для отчёта по складам формула вывода идентификатора серии (id товара в новом API) будет такой:
    ${row.consignmentID}

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

    Алексей Валериевич, с 1 января 2017 года REST API останется доступным, но не будет поддерживаться. Время окончания его обслуживания пока не определено.

  • Avatar
    Aftarburner

    Да, ${row.consignmentID} работает. Спасибо за ответ. Теперь, пожалуйста, поясните, как мне обновить товар. А именно изменить любую цену по этому новому uuid. Какая структура параметра body требуется?

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

    Aftarburner, нужно послать запрос по адресу /entity/product/{entityID} - методом POST (скоро для обновления нужно будет использовать метод PUT). В тело запроса нужно сложить JSON:

    {
    "id": "{entityID}",
    "salePrices": [
    {
    "value": 300,
    "currency": "руб",
    "priceType": "Цена для конкурентов"
    },
    ],
    }