# МойСклад JSON API 1.2: Выгрузить каталог с остатками

Сценарий из mcp-everything. Актуально на 2026-10-25.

Синхронизация товаров и остатков с сайтом или маркетплейсом. Новый эндпоинт ассортимента не считает остатки — их берут из краткого отчёта и связывают по `id`.

1. Получи ассортимент: GET /api/remap/1.2/entity/assortment с заголовком `X-Lognex-Remap-Beta-Feature: assortmentWithoutStock`; листай по `limit` (до 1000) и `offset`.
2. Запроси остатки: GET /api/remap/1.2/report/stock/all/current с нужным `stockType` (`stock`, `freeStock`, `quantity`, `reserve`, `inTransit`).
3. Свяжи `id` из ассортимента с `assortmentId` из отчёта.
4. Для частых обновлений передавай `changedSince` (не дальше 24 часов назад) и раз в сутки делай полную синхронизацию.

```shell
curl --compressed -X GET \
  "https://api.moysklad.ru/api/remap/1.2/entity/assortment" \
  -H "Authorization: Basic <Credentials>" \
  -H "Accept-Encoding: gzip" \
  -H "X-Lognex-Remap-Beta-Feature: assortmentWithoutStock"
```

## Базовые URL

- Боевой: `https://api.moysklad.ru`
- Все пути начинаются с .: `/api/remap/1.2`

## Авторизация

Тип: Bearer-токен

Два способа: Basic Auth (заголовок `Authorization: Basic` с `логин:пароль` в Base64) или токен доступа (`Authorization: Bearer <AccessToken>`). Токен пользователя выдаёт POST /api/remap/1.2/security/token; для решений из маркетплейса используется токен решения. Лимит запросов зависит от способа: токены решений расходуют лимит медленнее, чем логин/пароль и токен пользователя.

## Методы сценария

### GET /api/remap/1.2/entity/assortment — Ассортимент

Все товары, услуги, комплекты, модификации и партии. Без заголовка `assortmentWithoutStock` запрос уходит в старый эндпоинт, который планируется удалить.

Документация: https://dev.moysklad.ru/doc/api/remap/1.2/#/dictionaries/assortment#2-assortiment

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `X-Lognex-Remap-Beta-Feature` | header | string | да | assortmentWithoutStock |
| `limit` | query | integer | нет | До 1000 (по умолчанию 1000) |
| `offset` | query | integer | нет | Отступ, по умолчанию 0 |
| `search` | query | string | нет | Контекстный поиск |
| `filter` | query | string | нет | Фильтр, например filter=archived=false |

### GET /api/remap/1.2/report/stock/all/current — Краткий отчёт об остатках

Только ID позиции и остаток, все данные одним ответом без листания. Для частого обновления (каждые 5–15 минут). Доступен администратору или сотруднику с правом на остатки.

Документация: https://dev.moysklad.ru/doc/api/remap/1.2/#/reports/report-stock#3-kratkij-otchet-ob-ostatkah

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `stockType` | query | string | нет | stock (по умолчанию), freeStock, quantity, reserve, inTransit |
| `changedSince` | query | string | нет | Остатки, изменившиеся с момента гггг-мм-дд чч:мм:сс (не больше 24 часов назад) |
| `include` | query | string | нет | zeroLines — включить нулевые остатки |
| `filter` | query | string | нет | assortmentId=... и/или storeId=..., несколько через запятую |

## Нюансы

- Обязательно сжатие: заголовок `Accept-Encoding: gzip`, иначе `415` без тела.
- Ссылки на объекты передаются в формате `meta` (`href`, `type`, `mediaType`).
- Списки возвращают `meta` (`size`, `limit`, `offset`, `nextHref`, `previousHref`) и `rows`; `limit` — до 1000.
- Массив `positions` в запросе на обновление полностью заменяет позиции документа: непереданные удаляются.
- Цены и суммы — в копейках.
- Функции под заголовком `X-Lognex-Remap-Beta-Feature` не подпадают под гарантию неизменности структуры.
- Остаток по заголовкам: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-Lognex-Retry-TimeInterval`, `X-Lognex-Reset`, `X-Lognex-Retry-After`.
- Вебхуки работают только на платных тарифах и в пробный период; при бесплатном тарифе их нельзя создать.
- Есть MCP-сервер документации JSON API (раздел MCP-dev) — он ищет по документации и не выполняет запросы к аккаунту.

## Другие сценарии

- [Получить токен и начать работу](https://mcp-everything.ru/integrations/moysklad/scenarios/poluchit-token-i-nachat-rabotu.md)
- [Создать покупателя и заказ](https://mcp-everything.ru/integrations/moysklad/scenarios/sozdat-pokupatelya-i-zakaz.md)
- [Отгрузить заказ](https://mcp-everything.ru/integrations/moysklad/scenarios/otgruzit-zakaz.md)
- [Получать уведомления об изменениях](https://mcp-everything.ru/integrations/moysklad/scenarios/poluchat-uvedomleniya-ob-izmeneniyah.md)
- [Выгрузить большой отчёт асинхронно](https://mcp-everything.ru/integrations/moysklad/scenarios/vygruzit-bolshoy-otchet-asinhronno.md)

---

Если этого недостаточно — официальная документация: https://dev.moysklad.ru/doc/api/remap/1.2/
Вся интеграция одним документом: https://mcp-everything.ru/integrations/moysklad.md