Справочники и значения

Большинство полей вида *_id ссылаются на записи базы данных. Их значения могут отличаться между средами и меняться при настройке проекта. Поэтому API-клиент должен получать живой список, а не копировать ID из примера документации.

Как определить тип значения

Тип	Пример	Как использовать
Динамический справочник	`storage_unit_id`, `role_id`, `category_id`	Получить list endpoint, сохранить `id → объект`, периодически обновлять
Значение конкретного метода	webhook event `order.paid`	Использовать только значения, перечисленные в контракте этого метода
Состояние доменной сущности	статус подписки или доставки	Читать из доменной страницы; не переносить значения между разными ресурсами
UI-метка	цвет, tone, иконка	Не считать частью бизнес-контракта, если поле явно не возвращается API

Seed, запись тестовой базы и пример JSON не превращают ID в стабильную константу.

Готовый запрос: единицы измерения

Endpoint называется storage_units, но wrapper ответа называется units.

curl --request GET 
  --url https://api.gigma.ru/api/storage_units 
  --header 'Accept: application/json' 
  --header 'Authorization: Bearer <erp_access_token>'

Сокращённый успешный ответ:

{
  "units": [
    {
      "id": 7,
      "name": "Штука",
      "abbreviation": "шт"
    }
  ],
  "unitsCount": 1
}

Используйте путь GET /api/storage_units. Пути /api/units в backend нет.

Готовый запрос: способы оплаты витрины

Способы оплаты относятся к клиентскому commerce-контуру и требуют App Token:

curl --request GET 
  --url https://api.gigma.ru/api/counterparty/payment_types 
  --header 'Accept: application/json' 
  --header 'Token: <application_token>'

Сокращённый успешный ответ:

{
  "paymentTypes": [
    {
      "id": 3,
      "photo": null,
      "name": "Оплата при получении",
      "description": null
    }
  ],
  "paymentTypesCount": 1
}

Значения в примерах иллюстративные. Стабильным контрактом являются поля ответа и живые данные конкретного проекта, а не показанные ID.

ERP-справочники

Эти маршруты находятся в административном контуре и требуют ERP Bearer.

Назначение	Endpoint
Статусы заказов	`GET /api/order_statuses`
Типы контрагентов	`GET /api/counterparty_types`
Роли	`GET /api/roles`
Разрешения	`GET /api/permissions`
Экраны	`GET /api/screens`
Отделы	`GET /api/departments`
Бизнесы и филиалы	`GET /api/branches`
Менеджеры для фильтров	`GET /api/managers`
Ответственные пользователи	`GET /api/responsible_users`
Пользователи	`GET /api/users?query=<строка>`
Города	`GET /api/cities`
Страны	`GET /api/countries`
Бренды	`GET /api/brands`
Категории номенклатуры	`GET /api/categories`
Объекты	`GET /api/objects`
Типы номенклатуры	`GET /api/nomenclature_types`
Виды номенклатуры	`GET /api/nomenclature_kinds`
Единицы измерения	`GET /api/storage_units`
Ставки НДС	`GET /api/vats`
Каналы продаж	`GET /api/sales_channels`
Стратегии продаж	`GET /api/sales_strategies`
Типы файлов	`GET /api/file_types`
Типы страниц	`GET /api/page_types`
Способы доставки	`GET /api/delivery_types`

Некоторые из этих endpoint реализованы как полноценные resources, а некоторые доступны только для чтения. Наличие list endpoint не означает разрешение создавать или изменять его записи.

Справочники клиентского приложения

Эти маршруты находятся под /api/counterparty и требуют App Token.

Назначение	Endpoint
Способы оплаты	`GET /api/counterparty/payment_types`
Способы доставки	`GET /api/counterparty/delivery_types`
Подтипы доставки	`GET /api/counterparty/delivery_types/{type}/subtypes`
Категории витрины	`GET /api/counterparty/categories`
Бренды витрины	`GET /api/counterparty/brands`
Страны	`GET /api/counterparty/countries`
Сводный набор справочников	`GET /api/counterparty/dictionaries`
Типы страниц	`GET /api/counterparty/page_types`
Тарифы подписок	`GET /api/counterparty/subscription-plans`
Каталог подписок	`GET /api/counterparty/subscription-catalog`

Набор и порядок записей определяются настройками Application и Project.

Wrapper тоже является контрактом

Исторические Resource-классы используют разные стили имён:

GET /api/storage_units → units, unitsCount;
GET /api/counterparty/payment_types → paymentTypes, paymentTypesCount;
другие справочники могут использовать snake_case, camelCase или собственный wrapper.

Не вычисляйте wrapper из пути. Берите его из карточки метода или OpenAPI и покрывайте контрактным тестом.

Ошибки и реакция клиента

Код	Причина	Что делать
`401`	Не передан либо невалиден Bearer/App Token	Восстановить правильный контекст авторизации
`403`	Нет административного permission	Не повторять; запросить доступ
`404`	Неверный путь, ID либо объект скрыт границей проекта	Проверить endpoint и project/application context
`422`	Передан устаревший или недопустимый ID	Обновить справочник и повторить пользовательское действие
`429`	Слишком частое обновление списка	Использовать кэш, `Retry-After` и backoff

Что запрещено хардкодить

числовые ID ролей, разрешений, статусов, типов контрагентов и способов оплаты;
предположения о «пропущенном» ID;
значения из локального seed как production-контракт;
wrapper, выведенный из имени endpoint;
UI-tone как доменный статус.

OpenAPI добавляет к известным *_id расширение x-gigma-dictionary со ссылкой на list endpoint, но намеренно не публикует снимок ID как enum.

Следующие шаги

Общая обработка авторизации и ошибок: правила API.
Конкретные request/response поля: Swagger UI или openapi.json.
Commerce-справочники: E-Commerce / Справочники.
Административные справочники: Платформа / Справочники.