JSON API 1.2 МойСклад: обзор и авторизация

JSON API 1.2 (remap 1.2) — основной программный интерфейс МойСклад для интеграций. Разберём базовый адрес, формат обмена, два способа авторизации и соберём первый рабочий запрос.

Что такое JSON API 1.2

JSON API 1.2 (внутреннее имя — remap 1.2) — это REST-интерфейс МойСклад, через который внешние системы читают и меняют данные: товары, заказы, отгрузки, контрагентов, отчёты. Обмен идёт в формате JSON поверх HTTPS, каждый объект адресуется собственным URL.

Ключевые принципы интерфейса:

• REST-ресурсы. Каждая сущность — это коллекция и элемент: GET /entity/product возвращает список, GET /entity/product/{id} — конкретный товар.
• Ссылочная модель. Связи между объектами выражаются объектом meta с полем href, а не «сырыми» id.
• Единый формат ошибок. Любая ошибка возвращается массивом errors с кодом и описанием.

Базовый URL и структура запроса

Все запросы идут на единый хост. Базовый адрес интерфейса:

https://api.moysklad.ru/api/remap/1.2

Полный путь складывается из базы, раздела и ресурса. Например, список заказов покупателей:

GET https://api.moysklad.ru/api/remap/1.2/entity/customerorder

Работать нужно строго по HTTPS: обращения по HTTP отклоняются.

Авторизация через Basic Auth

Самый простой способ — HTTP Basic Authentication. В заголовок Authorization кладётся строка login:password, закодированная в Base64.

Пример запроса через curl:

curl -X GET "https://api.moysklad.ru/api/remap/1.2/entity/product?limit=1" \
  -H "Authorization: Basic YWRtaW5AY29tcGFueTpwYXNzd29yZA==" \
  -H "Accept-Encoding: gzip"

Флаг -u login:password в curl формирует этот заголовок автоматически. Логин и пароль — те же, что и для входа в веб-интерфейс, но для интеграций правильнее завести отдельного сотрудника с ограниченными правами.

Токенная авторизация (Bearer)

Более безопасный вариант — получить токен доступа и дальше слать его в заголовке Authorization: Bearer. Токен запрашивается один раз методом POST с Basic-авторизацией:

curl -X POST "https://api.moysklad.ru/api/remap/1.2/security/token" \
  -u "admin@company:password"

В ответ приходит JSON с полем токена:

{ "access_token": "a5f3...c91" }

Дальше все обращения используют токен, а не пароль:

curl "https://api.moysklad.ru/api/remap/1.2/entity/counterparty" \
  -H "Authorization: Bearer a5f3...c91"

• Токен не имеет срока жизни по времени, но становится недействительным при смене пароля владельца.
• Отозвать токен можно, сменив пароль или перевыпустив доступ в настройках профиля.
• Один аккаунт может иметь несколько активных токенов — удобно выдавать по токену на каждую интеграцию.

Обязательные заголовки и сжатие

Помимо авторизации, у запросов есть служебные заголовки, о которых легко забыть.

МойСклад отдаёт объёмные ответы, поэтому Accept-Encoding: gzip заметно снижает трафик и время ответа. Для запросов, изменяющих данные, обязателен корректный Content-Type: application/json — иначе тело не будет разобрано.

Первый рабочий запрос

Проверить доступ проще всего запросом контекста текущего сотрудника — он не требует прав на конкретные сущности:

GET https://api.moysklad.ru/api/remap/1.2/context/employee

Успешный ответ содержит данные учётной записи: имя, id, ссылку meta. Если авторизация неверна, придёт HTTP 401 с телом:

{ "errors": [ { "error": "Ошибка аутентификации", "code": 1001 } ] }

Дальше можно перейти к сущностям. Запрос списка товаров с ограничением выборки:

GET /entity/product?limit=10&offset=0

Ответ придёт в виде объекта с полями meta (размер выборки) и массивом rows. Это стандартная структура коллекции, одинаковая для всех сущностей.

Безопасность и хранение доступов

API открывает доступ к коммерческим данным, поэтому доступы стоит защищать так же, как боевые ключи.

• Отдельный сотрудник для интеграции. Заводите техническую учётку с минимально необходимыми правами (например, только чтение отчётов), а не используйте аккаунт владельца.
• Токен вместо пароля. Bearer-токен изолирует интеграцию: его можно отозвать, не трогая другие системы.
• Секреты — в защищённом хранилище. Токены держат в переменных окружения или менеджере секретов, а не в репозитории.
• Логирование без секретов. При отладке маскируйте заголовок Authorization в логах.

Итог

Для старта работы с JSON API 1.2 достаточно трёх вещей: базовый URL https://api.moysklad.ru/api/remap/1.2, корректная авторизация (Basic или, что предпочтительнее, Bearer-токен) и заголовки Content-Type и Accept-Encoding. Первый запрос к /context/employee подтверждает, что доступ настроен, а дальше открываются сущности и отчёты.

Когда МойСклад нужно связать с сайтом или порталом на 1С-Битрикс, мы проектируем этот обмен как надёжный сервис: аккуратное хранение токенов, обработка ошибок и повторов, устойчивость к лимитам API. Если интеграция выходит за рамки типового обмена, поможем спроектировать и реализовать её под вашу нагрузку и данные.