Сущности и метаданные

Сущность в МойСклад — это объект с собственным URL и обязательным блоком meta. Разберём, как устроены коллекции, как связаны объекты и как читать метаданные аккаунта.

Что такое сущность

Сущность (entity) — это адресуемый объект МойСклад: товар, заказ, контрагент, склад, организация. Каждая сущность живёт по своему URL внутри раздела /entity/.

У каждого объекта есть системные поля: id (UUID), accountId, updated, name и всегда — блок meta.

Объект meta — ядро ссылочной модели

Блок meta есть у каждой сущности и у каждой ссылки на неё. Он описывает, где лежит объект и какого он типа:

"meta": {
  "href": "https://api.moysklad.ru/api/remap/1.2/entity/product/a1b2",
  "type": "product",
  "mediaType": "application/json"
}

• href — прямой URL объекта; по нему его можно запросить или обновить.
• type — тип сущности (product, demand, counterparty).
• mediaType — формат представления, обычно application/json.

Коллекции и rows

Запрос списка любой сущности возвращает объект-коллекцию единого вида:

{
  "meta": { "size": 512, "limit": 100, "offset": 0 },
  "rows": [ { ... }, { ... } ]
}

• meta.size — общее число объектов, подходящих под запрос (а не в текущей странице).
• meta.limit — размер страницы (по умолчанию 1000, максимум 1000).
• meta.offset — смещение от начала выборки.
• rows — массив объектов текущей страницы.

По meta.size и limit вычисляют число страниц для полной выгрузки. Именно эта структура используется во всех списках — от товаров до отчётов.

expand: разворачивание связанных объектов

По умолчанию связанные объекты приходят только ссылкой meta. Чтобы получить их содержимое сразу, без второго запроса, используется параметр expand.

Пример — заказ вместе с контрагентом и его контактами:

GET /entity/customerorder/{id}?expand=agent,state

Вложенность можно указывать через точку:

GET /entity/customerorder?expand=positions.assortment

Метаданные сущности

У каждой сущности есть описание её структуры — метаданные. Они доступны по суффиксу /metadata:

GET /entity/product/metadata

Ответ содержит справочные списки, привязанные к сущности: статусы (states), доп. поля (attributes), а также ссылки на связанные справочники. Общий обзор аккаунта отдаёт корневой endpoint:

GET /entity/metadata

Он возвращает карту всех доступных сущностей с их URL — удобно для автоматического построения клиента. Метаданные стоит запрашивать при старте интеграции и кэшировать, так как они меняются редко.

Дополнительные поля (атрибуты)

Пользовательские поля в МойСклад называются атрибутами (attributes). Их описание — тип, id, имя — лежит в метаданных сущности, а значения передаются в массиве attributes объекта.

Пример добавления значения доп. поля в заказ:

"attributes": [{
  "meta": { "href": ".../attributes/f0a1", "type": "attributemetadata" },
  "value": "Приоритетный"
}]

• Каждый атрибут идентифицируется через свой meta.href, а не по имени.
• Тип значения зависит от типа поля: строка, число, булево, дата или ссылка на справочник.
• Список доступных атрибутов всегда сверяйте с /metadata/attributes.

Итог

Модель данных МойСклад строится на трёх идеях: сущность с уникальным URL, ссылочная связка через meta и единый формат коллекции с meta и rows. Параметр expand экономит запросы, метаданные описывают структуру, а атрибуты хранят пользовательские поля. Освоив эти механизмы, вы сможете работать с любой сущностью по одному шаблону.

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