# Gigma

> Документация Gigma: общие правила API, сайты и приложения, управление бизнесом, каталоги, заказы, подписки и интеграции.

Полная документация API одним файлом. Источник на сайте: https://docs.gigma.ru/. Индекс: https://docs.gigma.ru/llms.txt

Общие соглашения (auth-flow, headers, форматы данных, пагинация, фильтры, коды ошибок): https://docs.gigma.ru/conventions/

Базовый URL API: `https://api.gigma.ru/api`

## Содержание

Всего endpoint'ов: 325 в 35 разделах. В оглавлении URL приведены без базового хоста.

### Общее
- [Как устроена Gigma](https://docs.gigma.ru/product-logic/)
- [Правила API](https://docs.gigma.ru/conventions/)
- [Справочники и значения](https://docs.gigma.ru/enums/)
- [Swagger UI](https://docs.gigma.ru/api-docs/)

### Сайты и приложения
- [Обзор API](https://docs.gigma.ru/E-Commerce/)
- [Подготовка приложения](https://docs.gigma.ru/E-Commerce/%D0%A1%D0%B0%D0%B9%D1%82%D1%8B%20%D0%B8%20%D0%BF%D1%80%D0%B8%D0%BB%D0%BE%D0%B6%D0%B5%D0%BD%D0%B8%D1%8F/)
- [Интеграция с backend](https://docs.gigma.ru/E-Commerce/%D0%98%D0%BD%D1%82%D0%B5%D0%B3%D1%80%D0%B0%D1%86%D0%B8%D1%8F%20%D1%87%D0%B5%D1%80%D0%B5%D0%B7%20backend/)
- [Heartbeat клиентской сессии](https://docs.gigma.ru/E-Commerce/%D0%98%D0%BD%D1%82%D0%B5%D0%B3%D1%80%D0%B0%D1%86%D0%B8%D1%8F%20%D1%87%D0%B5%D1%80%D0%B5%D0%B7%20backend/heartbeat/)
    - `POST   /api/counterparty/session/heartbeat` — Обновление активности клиентской сессии
- [Проверка Bearer-токена](https://docs.gigma.ru/E-Commerce/%D0%98%D0%BD%D1%82%D0%B5%D0%B3%D1%80%D0%B0%D1%86%D0%B8%D1%8F%20%D1%87%D0%B5%D1%80%D0%B5%D0%B7%20backend/introspect/)
    - `POST   /api/counterparty/auth/introspect` — Проверка Counterparty Bearer
- [Вход клиента](https://docs.gigma.ru/E-Commerce/%D0%90%D0%B2%D1%82%D0%BE%D1%80%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D1%8F/)
    - `POST   /api/counterparty/send_password` — Запрос одноразового кода
    - `POST   /api/counterparty/login` — Вход по одноразовому коду
    - `POST   /api/counterparty/miniapps/{provider}/contact_auth` — Авторизация miniapp по подписанному контакту
    - `POST   /api/counterparty/callback_auth/init` — Инициализация callback-авторизации
    - `POST   /api/counterparty/callback_auth/status` — Проверка статуса callback-авторизации
    - `POST   /api/counterparty/callback_auth/exchange` — Получение Bearer token после callback-звонка
    - `POST   /api/counterparty/logout` — Выход контрагента из системы
- [Профиль клиента](https://docs.gigma.ru/E-Commerce/%D0%9A%D0%BE%D0%BD%D1%82%D1%80%D0%B0%D0%B3%D0%B5%D0%BD%D1%82%20(%D0%BA%D0%BB%D0%B8%D0%B5%D0%BD%D1%82)/)
    - `GET    /api/counterparty` — Получение текущего клиента
    - `PUT    /api/counterparty` — Обновление профиля
    - `POST   /api/counterparty/phone/request_change` — Запрос кода на новый номер
    - `POST   /api/counterparty/phone/verify_change` — Подтверждение нового номера
    - `POST   /api/counterparty/verifications/sbp-payment` — Создание или получение СБП-проверки
    - `DELETE /api/counterparty` — Удаление аккаунта клиента
- [Каталог, тарифы и цены](https://docs.gigma.ru/E-Commerce/%D0%A2%D0%BE%D0%B2%D0%B0%D1%80%D1%8B/)
    - `GET    /api/counterparty/subscription-catalog` — Получение подписочного каталога
    - `GET    /api/counterparty/subscription-catalog/grouped` — Получение всегда сгруппированного каталога
    - `GET    /api/counterparty/subscription-plans` — Получение плоских планов подписки
    - `GET    /api/counterparty/products` — Получение списка товаров
    - `GET    /api/counterparty/products/{id}` — Получение карточки товара
    - `GET    /api/counterparty/prices` — Получение диапазона цен
    - `GET    /api/counterparty/products/favourites` — Получение избранных товаров
    - `GET    /api/counterparty/products/favourites/{product_id}` — Получение карточки товара через маршрут избранного
    - `POST   /api/counterparty/products/favourites` — Добавление товара в избранное
    - `DELETE /api/counterparty/products/favourites/{product_id}` — Удаление товара из избранного
- [Заказы и подписки](https://docs.gigma.ru/E-Commerce/%D0%97%D0%B0%D0%BA%D0%B0%D0%B7%D1%8B/)
    - `POST   /api/counterparty/orders/precalculate` — Предварительный расчёт корзины
    - `POST   /api/counterparty/orders` — Создание заказа
    - `GET    /api/counterparty/orders` — Получение заказов клиента
    - `GET    /api/counterparty/orders/{id}` — Получение одного заказа
    - `POST   /api/counterparty/contact_form` — Создание заказа из контактной формы
    - `POST   /api/counterparty/subscriptions/checkout` — Создание checkout подписки
    - `GET    /api/counterparty/subscriptions` — Получение подписок клиента
    - `POST   /api/counterparty/subscriptions` — Создание подписки с немедленным списанием
    - `PATCH  /api/counterparty/subscriptions/{id}` — Изменение тарифа или сохранённого способа оплаты
    - `POST   /api/counterparty/subscriptions/{id}/cancel` — Отмена подписки
    - `POST   /api/counterparty/subscriptions/{id}/resume` — Возобновление отменённой подписки
    - `GET    /api/counterparty/subscriptions/{id}/payments` — Получение истории платежей
    - `POST   /api/counterparty/subscriptions/{id}/payments/{payment_id}/retry` — Повтор последней неуспешной оплаты
    - `GET    /api/counterparty/payment-methods` — Получение способов оплаты клиента
    - `DELETE /api/counterparty/payment-methods/{id}` — Отвязка сохранённого способа оплаты
    - `POST   /api/counterparty/subscriptions/{id}/payment-method-change` — Начало безопасной смены карты подписки
    - `POST   /api/counterparty/subscriptions/{id}/payment-method-changes/{change_id}/sync` — Синхронизация смены карты
- [Контентные блоки](https://docs.gigma.ru/E-Commerce/%D0%94%D0%B8%D0%BD%D0%B0%D0%BC%D0%B8%D1%87%D0%B5%D1%81%D0%BA%D0%B8%D0%B9%20%D0%BA%D0%BE%D0%BD%D1%82%D0%B5%D0%BD%D1%82/)
    - `GET    /api/counterparty/blocks/{code}` — Получение блока по code
    - `GET    /api/counterparty/blocks/id/{identifier}` — Получение блока по identifier
- [Страницы и публикации](https://docs.gigma.ru/E-Commerce/%D0%A1%D1%82%D1%80%D0%B0%D0%BD%D0%B8%D1%86%D1%8B/)
    - `GET    /api/counterparty/page_types` — Получение типов страниц
    - `GET    /api/counterparty/pages` — Получение списка страниц
    - `GET    /api/counterparty/pages/{slug}` — Получение страницы по slug
- [Меню и навигация](https://docs.gigma.ru/E-Commerce/%D0%9D%D0%B0%D0%B2%D0%B8%D0%B3%D0%B0%D1%86%D0%B8%D0%BE%D0%BD%D0%BD%D0%B0%D1%8F%20%D0%BF%D0%B0%D0%BD%D0%B5%D0%BB%D1%8C/)
    - `GET    /api/counterparty/menus/{slug?}` — Получение меню по slug
    - `GET    /api/counterparty/menus/{name}/items` — Получение пунктов проектного меню
- [Настройки и поиск](https://docs.gigma.ru/E-Commerce/%D0%92%D1%81%D0%BF%D0%BE%D0%BC%D0%BE%D0%B3%D0%B0%D1%82%D0%B5%D0%BB%D1%8C%D0%BD%D1%8B%D0%B5%20%D0%B7%D0%B0%D0%BF%D1%80%D0%BE%D1%81%D1%8B/)
    - `GET    /api/counterparty/settings` — Получение настроек витрины
    - `GET    /api/counterparty/tags` — Получение тегов товаров
    - `GET    /api/counterparty/search/history` — Получение истории поиска клиента
    - `GET    /api/counterparty/search/popular` — Текущее поведение маршрута популярных запросов
- [Уведомления клиента](https://docs.gigma.ru/E-Commerce/%D0%A3%D0%B2%D0%B5%D0%B4%D0%BE%D0%BC%D0%BB%D0%B5%D0%BD%D0%B8%D1%8F/)
    - `GET    /api/counterparty/notifications` — Получение списка уведомлений
- [Справочники витрины](https://docs.gigma.ru/E-Commerce/%D0%A1%D0%BF%D1%80%D0%B0%D0%B2%D0%BE%D1%87%D0%BD%D0%B8%D0%BA%D0%B8/)
    - `GET    /api/counterparty/categories` — Получение категорий
    - `GET    /api/counterparty/brands` — Получение брендов
    - `GET    /api/counterparty/countries` — Получение стран
    - `GET    /api/counterparty/delivery_types` — Получение способов доставки
    - `GET    /api/counterparty/delivery_types/{type_id}` — Получение одного способа доставки
    - `GET    /api/counterparty/delivery_types/{type_id}/subtypes` — Получение подтипов доставки
    - `GET    /api/counterparty/delivery_types/{type_id}/subtypes/{subtype_id}` — Получение одного подтипа доставки
    - `GET    /api/counterparty/delivery_types/{type_id}/subtypes/{subtype_id}/params` — Получение параметров подтипа
    - `GET    /api/counterparty/payment_types` — Получение способов оплаты
    - `GET    /api/counterparty/shops` — Получение магазинов и пунктов самовывоза
    - `GET    /api/counterparty/shops/{id}` — Текущее поведение маршрута карточки магазина
    - `POST   /api/counterparty/search_address` — Поиск адреса
    - `GET    /api/counterparty/slides` — Получение рекламных слайдов
    - `GET    /api/counterparty/dictionaries` — Получение нескольких справочников одним запросом

### Платформа
- [Обзор платформы](https://docs.gigma.ru/ERP/)
- [Доступ сотрудников](https://docs.gigma.ru/ERP/%D0%90%D0%B2%D1%82%D0%BE%D1%80%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D1%8F/)
    - `POST   /api/send_password` — Отправка пароля на электронную почту
    - `POST   /api/login` — Авторизация
    - `GET    /api/user` — Получение текущего пользователя
    - `POST   /api/user/logout` — Выход пользователя из системы
- [MCP: рабочие методы](https://docs.gigma.ru/ERP/%D0%9C%D0%A1%D0%9F/)
    - `GET    /api/user` — Проверка рабочего Agent Token
- [MCP: получение доступа](https://docs.gigma.ru/ERP/%D0%9C%D0%A1%D0%9F/%D0%9F%D0%BE%D0%BB%D1%83%D1%87%D0%B5%D0%BD%D0%B8%D0%B5%20%D0%B4%D0%BE%D1%81%D1%82%D1%83%D0%BF%D0%B0/)
    - `POST   /api/agent-access-requests` — Создание запроса доступа
    - `GET    /api/agent-access-requests/{publicId}/review` — Страница подтверждения для владельца
    - `POST   /api/agent-access-requests/{publicId}/review` — Получение данных для review
    - `POST   /api/agent-access-requests/{publicId}/approve` — Одобрение доступа
    - `POST   /api/agent-access-requests/{publicId}/decline` — Отклонение доступа
    - `POST   /api/agent-access-requests/{publicId}/status` — Статус запроса доступа
    - `POST   /api/agent-access-requests/{publicId}/consume` — Создание агента и получение первого токена
- [Управление агентами](https://docs.gigma.ru/ERP/%D0%9C%D0%A1%D0%9F/%D0%A3%D0%BF%D1%80%D0%B0%D0%B2%D0%BB%D0%B5%D0%BD%D0%B8%D0%B5%20%D0%B0%D0%B3%D0%B5%D0%BD%D1%82%D0%B0%D0%BC%D0%B8/)
    - `GET    /api/agents` — Список агентов проекта
    - `GET    /api/tables/agents` — Табличный список агентов
    - `GET    /api/agents/{agent}` — Получение агента
    - `POST   /api/agents` — Создание агента
    - `PATCH  /api/agents/{agent}` — Изменение агента
    - `DELETE /api/agents/{agent}` — Отключение агента
    - `GET    /api/agents/{agent}/tokens` — Список токенов агента
    - `POST   /api/agents/{agent}/tokens` — Выпуск Agent Token
    - `DELETE /api/agents/{agent}/tokens/{token}` — Отзыв Agent Token
- [Сотрудники и менеджеры](https://docs.gigma.ru/ERP/%D0%9F%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D0%B8/)
    - `GET    /api/users` — Поиск пользователей
    - `GET    /api/managers` — Список менеджеров (упрощённый)
    - `GET    /api/responsible_users` — Список ответственных пользователей
- [Бизнесы и реквизиты](https://docs.gigma.ru/ERP/%D0%91%D0%B8%D0%B7%D0%BD%D0%B5%D1%81%D1%8B/)
    - `GET    /api/branches` — Список бизнесов
    - `GET    /api/tables/branches` — Таблица бизнесов (для UI с колонками и пагинацией)
    - `GET    /api/branches/{id}` — Получение бизнеса по ID
    - `POST   /api/branches` — Создание бизнеса
    - `PUT    /api/branches/{id}` — Изменение бизнеса
    - `DELETE /api/branches/{id}` — Удаление бизнеса
    - `GET    /api/branches/{id}/bank_requisites` — Список реквизитов бизнеса
    - `POST   /api/branches/{id}/bank_requisites` — Добавление реквизита бизнеса
    - `PUT    /api/branches/{id}/bank_requisites/{requisiteId}` — Изменение реквизита бизнеса
    - `GET    /api/branches/{id}/history` — История изменений бизнеса
    - `GET    /api/branches/{branchId}/bank_requisites/{bankId}/integrations` — Список интеграций реквизита
    - `PUT    /api/branches/{branchId}/bank_requisites/{bankId}/integrations/{integrationsId}` — Изменение интеграции реквизита
    - `GET    /api/integrations/{integrationId}` — Описание интеграции по ID
    - `GET    /api/branches/{branchId}/bank_requisites/{bankId}/integrations/{integrationId}/parameters` — Параметры (значения) интеграции реквизита
    - `POST   /api/branches/{branchId}/bank_requisites/{bankId}/integrations/{integrationsId}/parameters` — Добавление значения параметра интеграции
    - `DELETE /api/branches/{branchId}/bank_requisites/{bankId}/integrations/{integrationId}/parameters/{parameterId}` — Удаление значения параметра интеграции
    - `GET    /api/responsible_users` — Список ответственных пользователей (для фильтра)
    - `GET    /api/users` — Поиск пользователя по строке
- [Приложения и webhooks](https://docs.gigma.ru/ERP/%D0%9F%D1%80%D0%B8%D0%BB%D0%BE%D0%B6%D0%B5%D0%BD%D0%B8%D1%8F/)
    - `GET    /api/applications` — Получение списка приложений
    - `POST   /api/applications` — Создание приложения
    - `GET    /api/applications/{id}` — Получение выбранного приложения
    - `GET    /api/applications/{application}/subscription-nomenclatures/catalog` — Каталог тарифов для настройки приложения
    - `POST   /api/applications/{application}/subscription-nomenclatures` — Назначить подписочный тариф приложению
    - `PATCH  /api/applications/{application}/subscription-nomenclatures/{assignment}` — Изменить привязку подписочного тарифа
    - `DELETE /api/applications/{application}/subscription-nomenclatures/{assignment}` — Удалить привязку подписочного тарифа
    - `GET    /api/applications/{application}/webhooks` — Получение списка вебхуков
    - `POST   /api/applications/{application}/webhooks` — Создание вебхука
    - `GET    /api/applications/{application}/webhooks/{webhook}` — Получение выбранного вебхука
    - `PATCH  /api/applications/{application}/webhooks/{webhook}` — Обновление вебхука
    - `DELETE /api/applications/{application}/webhooks/{webhook}` — Удаление вебхука
    - `GET    /api/applications/{application}/webhooks/{webhook}/deliveries` — Получение доставок вебхука
    - `POST   /api/applications/{application}/webhooks/{webhook}/deliveries/{delivery}/resend` — Повторная доставка вебхука
    - `POST   /api/applications/{application}/webhooks/{webhook}/rotate-secret` — Ротация секрета вебхука
    - `GET    /api/tables/applications/{id}/categories` — Получение списка категорий приложения (табличное)
    - `GET    /api/applications/{id}/categories` — Получение списка категорий приложения
    - `POST   /api/applications/{id}/categories` — Добавление категории в приложение
    - `GET    /api/applications/{id}/categories/{category_id}` — Получение категории приложения
    - `DELETE /api/applications/{id}/categories/{category_id}` — Удаление категории из приложения
    - `POST   /api/applications/{id}/categories/{category_id}/up` — Повышение приоритета категории
    - `POST   /api/applications/{id}/categories/{category_id}/down` — Понижение приоритета категории
    - `GET    /api/tables/applications/{id}/brands` — Получение списка брендов приложения (табличное)
    - `GET    /api/applications/{id}/brands` — Получение списка брендов приложения
    - `POST   /api/applications/{id}/brands` — Добавление бренда в приложение
    - `GET    /api/applications/{id}/brands/{brand_id}` — Получение бренда приложения
    - `DELETE /api/applications/{id}/brands/{brand_id}` — Удаление бренда из приложения
    - `POST   /api/applications/{id}/brands/{brand_id}/up` — Повышение приоритета бренда
    - `POST   /api/applications/{id}/brands/{brand_id}/down` — Понижение приоритета бренда
    - `GET    /api/tables/applications/{id}/menu_items` — Получение списка пунктов меню (табличное)
    - `POST   /api/applications/{id}/menu_items` — Создание пункта меню
    - `PUT    /api/applications/{id}/menu_items/{menu_item_id}` — Обновление пункта меню
    - `DELETE /api/applications/{id}/menu_items/{menu_item_id}` — Удаление пункта меню
    - `POST   /api/applications/{id}/menu_items/{menu_item_id}/up` — Повышение приоритета пункта меню
    - `POST   /api/applications/{id}/menu_items/{menu_item_id}/down` — Понижение приоритета пункта меню
- [Каталог товаров и услуг](https://docs.gigma.ru/ERP/%D0%9D%D0%BE%D0%BC%D0%B5%D0%BD%D0%BA%D0%BB%D0%B0%D1%82%D1%83%D1%80%D0%B0/)
    - `GET    /api/tables/categories` — Получение списка категорий
    - `GET    /api/tables/categories/{id}` — Получение выбранной категории
    - `PUT    /api/categories/{id}` — Обновление выбранной категории
    - `POST   /api/categories` — Добавление категории
    - `GET    /api/categories/{id}/history` — Получение истории изменений категории
    - `GET    /api/tags` — Получение списка тегов
    - `GET    /api/nomenclature_types` — Получение списка типов номенклатуры
    - `GET    /api/nomenclature_kinds` — Получение списка видов номенклатуры
    - `GET    /api/tables/nomenclatures` — Получение списка номенклатуры (табличное представление)
    - `GET    /api/nomenclatures` — Получение списка номенклатуры
    - `POST   /api/nomenclatures` — Добавление позиции номенклатуры
    - `PUT    /api/nomenclatures/{id}` — Обновление позиции номенклатуры
    - `GET    /api/nomenclatures/{id}` — Получение выбранной позиции номенклатуры
    - `GET    /api/nomenclatures/{id}/history` — Получение истории изменений позиции номенклатуры
    - `POST   /api/nomenclatures/export` — Экспорт файла номенклатуры
    - `POST   /api/nomenclatures/import` — Импорт файла номенклатуры
- [Склады](https://docs.gigma.ru/ERP/%D0%A1%D0%BA%D0%BB%D0%B0%D0%B4%D1%8B/)
    - `GET    /api/tables/warehouses` — Получение списка складов
    - `GET    /api/warehouses/{id}` — Получение выбранного склада
    - `POST   /api/warehouses` — Добавление склада
    - `PUT    /api/warehouses/{id}` — Редактирование склада
    - `DELETE /api/warehouses/{id}` — Удаление склада
    - `GET    /api/warehouses/{id}/integrations` — Получение списка интеграций
    - `PUT    /api/warehouses/{id}/integrations/{id}` — Обновление статуса выбранной интеграции
    - `GET    /api/warehouses/{id}/integrations/{id}/parameters` — Получение списка параметров интеграции
    - `POST   /api/warehouses/{id}/integrations/{id}/parameters` — Добавление параметров для выбранной интеграции
    - `POST   /api/warehouses/{id}/integrations/{id}/parameters/{id}` — Удаление параметров из выбранной интеграции
    - `GET    /api/warehouses/{id}/history` — Получение истории изменений
- [Остатки и импорт](https://docs.gigma.ru/ERP/%D0%9E%D1%81%D1%82%D0%B0%D1%82%D0%BA%D0%B8/)
    - `GET    /api/tables/inventories` — Получение списка остатков (табличное представление)
    - `GET    /api/inventories` — Получение списка остатков (JSON)
    - `POST   /api/inventories` — Создание записи остатка
    - `PUT    /api/inventories/{id}` — Обновление записи остатка
    - `GET    /api/inventories/{id}` — Получение выбранного остатка
    - `GET    /api/inventories/{id}/history` — Получение истории изменений остатка
    - `POST   /api/inventories/upload` — Импорт остатков
- [Резервы товаров](https://docs.gigma.ru/ERP/%D0%A0%D0%B5%D0%B7%D0%B5%D1%80%D0%B2%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5/)
    - `GET    /api/tables/reservations` — Таблица резервов
    - `DELETE /api/reservations/{id}` — Удаление резерва ⚠ endpoint не существует на бэке
- [Стратегии продаж](https://docs.gigma.ru/ERP/%D0%A1%D1%82%D1%80%D0%B0%D1%82%D0%B5%D0%B3%D0%B8%D0%B8%20%D0%BF%D1%80%D0%BE%D0%B4%D0%B0%D0%B6/)
    - `GET    /api/sales_strategies` — Список стратегий продаж
    - `GET    /api/sales_strategies/{id}` — Стратегия продаж по ID
- [Акции и скидки](https://docs.gigma.ru/ERP/%D0%9F%D1%80%D0%BE%D0%BC%D0%BE%D0%B0%D0%BA%D1%86%D0%B8%D0%B8/)
    - `GET    /api/promotions` — Получение списка промоакций
    - `GET    /api/discounts` — Получение списка скидок
    - `POST   /api/discounts` — Создание скидки
    - `GET    /api/discounts/{id}` — Получение выбранной скидки
    - `PUT    /api/discounts/{id}` — Обновление скидки
    - `DELETE /api/discounts/{id}` — Удаление скидки
    - `GET    /api/discounts/stats` — Статистика скидок
    - `POST   /api/discounts/{id}/pause` — Поставить скидку на паузу
    - `POST   /api/discounts/{id}/activate` — Активировать скидку
    - `POST   /api/discounts/{id}/archive` — Архивировать скидку
    - `GET    /api/discounts/{id}/usages` — Использования скидки
- [Магазины и пункты выдачи](https://docs.gigma.ru/ERP/%D0%9C%D0%B0%D0%B3%D0%B0%D0%B7%D0%B8%D0%BD%D1%8B/)
    - `GET    /api/tables/shops` — Получение списка магазинов (табличное представление)
    - `GET    /api/shops` — Получение списка магазинов
    - `POST   /api/shops` — Добавление магазина
    - `PUT    /api/shops/{id}` — Обновление выбранного магазина
    - `GET    /api/shops/{id}` — Получение выбранного магазина
    - `DELETE /api/shops/{id}` — Удаление выбранного магазина
    - `GET    /api/shops/{id}/history` — Получение истории изменений по выбранному магазину
    - `GET    /api/shops/{id}/hours` — Получение списка дней и часов работы выбранного магазина
    - `POST   /api/shops/{id}/hours` — Добавление дней и часов работы выбранного магазина
    - `PUT    /api/shops/{id}/hours/{id}` — Обновление дней и часов работы выбранного магазина
    - `DELETE /api/shops/{id}/hours/{id}` — Удаление выбранных дней и часов работы магазина
    - `GET    /api/shops/{id}/holidays` — Получение графика работы в праздничные дни выбранного магазина
    - `POST   /api/shops/{id}/holidays` — Обновление графика работы в праздничные дни выбранного магазина
    - `GET    /api/shops/{id}/exceptions` — Получение списка дней-исключений в работе выбранного магазина
    - `POST   /api/shops/{id}/exceptions` — Добавление промежутка дней-исключений для выбранного магазина
    - `PUT    /api/shops/{id}/exceptions/{id}` — Обновление промежутка дней-исключений для выбранного магазина
    - `DELETE /api/shops/{id}/exceptions/{id}` — Удаление промежутка дней-исключения для выбранного магазина
- [Клиенты и контрагенты](https://docs.gigma.ru/ERP/%D0%9A%D0%BE%D0%BD%D1%82%D1%80%D0%B0%D0%B3%D0%B5%D0%BD%D1%82%D1%8B/)
    - `GET    /api/counterparties` — Список контрагентов
    - `GET    /api/tables/counterparties` — Таблица контрагентов (для UI с колонками и пагинацией)
    - `GET    /api/counterparties/{id}` — Получение контрагента по ID
    - `POST   /api/counterparties` — Создание контрагента
    - `PUT    /api/counterparties/{id}` — Изменение контрагента
    - `DELETE /api/counterparties/{id}` — Удаление контрагента
    - `GET    /api/counterparties/{id}/bank_requisites` — Список банковских реквизитов контрагента
    - `POST   /api/counterparties/{id}/bank_requisites` — Добавление банковского реквизита
    - `PUT    /api/counterparties/{id}/bank_requisites/{requisiteId}` — Изменение банковского реквизита
    - `GET    /api/counterparties/{id}/contacts` — Список контактов контрагента
    - `POST   /api/counterparties/{id}/contacts` — Добавление контакта
    - `PUT    /api/counterparties/{id}/contacts/{contactId}` — Изменение контакта
    - `GET    /api/counterparties/{id}/history` — История изменений контрагента
- [Заказы и исполнение](https://docs.gigma.ru/ERP/%D0%97%D0%B0%D0%BA%D0%B0%D0%B7%D1%8B/)
    - `GET    /api/orders` — Получение списка заказов
    - `GET    /api/tables/orders` — Получение списка заказов (табличное представление)
    - `GET    /api/orders/{id}` — Получение выбранного заказа
    - `POST   /api/orders` — Добавление заказа
    - `PUT    /api/orders/{id}` — Редактирование заказа
    - `DELETE /api/orders/{id}` — Удаление заказа ⚠ backend bug
    - `GET    /api/tables/orders/{id}/nomenclatures` — Получение содержимого заказа (табличное представление)
    - `POST   /api/orders/{id}/nomenclatures` — Добавление товаров в заказ (= создание Reservation) ⚠ backend bug
    - `PUT    /api/orders/{id}/nomenclatures/{nomenclatureId}` — Обновление товаров в заказе
    - `DELETE /api/orders/{id}/nomenclatures/{nomenclatureId}` — Удаление товаров из заказа
    - `GET    /api/tables/orders/{id}/files` — Получение списка файлов (табличное представление)
    - `POST   /api/orders/{id}/files` — Добавление файла
    - `GET    /api/orders/{id}/history` — Получение истории изменений по заказу
    - `POST   /api/orders/{id}/request-refund` — Запрос возврата по заказу
- [Задачи команды](https://docs.gigma.ru/ERP/%D0%97%D0%B0%D0%B4%D0%B0%D1%87%D0%B8/)
    - `GET    /api/tables/tasks` — Получение списка задач (табличное представление)
    - `GET    /api/tasks` — Получение списка задач (JSON)
    - `GET    /api/tasks/{id}` — Получение выбранной задачи
    - `POST   /api/tasks` — Создание задачи
    - `PUT    /api/tasks/{id}` — Редактирование задачи
- [Контентные блоки](https://docs.gigma.ru/ERP/%D0%91%D0%BB%D0%BE%D0%BA%D0%B8/)
    - `GET    /api/tables/applications/{id}/blocks` — Получение списка блоков (табличное представление)
    - `GET    /api/applications/{id}/blocks` — Получение списка блоков
    - `GET    /api/applications/{id}/blocks/{id}` — Получение выбранного блока
    - `POST   /api/applications/{id}/blocks` — Добавление блока
    - `PUT    /api/applications/{id}/blocks/{id}` — Редактирование блока
    - `DELETE /api/applications/{id}/blocks/{id}` — Удаление блока
    - `GET    /api/applications/{id}/blocks/{id}/history` — Получение истории изменений по блоку
- [Страницы и публикации](https://docs.gigma.ru/ERP/%D0%A1%D1%82%D1%80%D0%B0%D0%BD%D0%B8%D1%86%D1%8B/)
    - `GET    /api/tables/pages` — Получение списка страниц (табличное представление)
    - `GET    /api/pages/{id}` — Получение выбранной страницы (контента)
    - `POST   /api/pages` — Добавление страницы
    - `PUT    /api/pages/{id}` — Редактирование страницы (контента)
    - `DELETE /api/pages/{id}` — Удаление страницы (контента)
    - `GET    /api/pages/{page}/history` — Получение истории изменений страницы
    - `GET    /api/page_tags` — Получение списка тегов
- [Меню сотрудников](https://docs.gigma.ru/ERP/%D0%9C%D0%B5%D0%BD%D1%8E/)
    - `GET    /api/menus` — Меню текущего пользователя
    - `GET    /api/menus/default/items` — Пункты меню по умолчанию
    - `POST   /api/users/{id}/attach_menu` — Скопировать меню текущего пользователя указанному
    - `POST   /api/attach_menu_to_project` — Скопировать меню текущего пользователя всем пользователям проекта
    - `POST   /api/users/{id}/create_menu_from_user_items` — Сохранить меню пользователя как шаблон
- [Файлы и медиа](https://docs.gigma.ru/ERP/%D0%A4%D0%B0%D0%B9%D0%BB%D1%8B/)
    - `POST   /api/files` — Загрузка файла
    - `GET    /api/files/{id}` — Получение файла по ID
    - `DELETE /api/files/{id}` — Удаление файла
    - `GET    /api/file_types` — Список типов файлов
    - `GET    /api/file_types/{id}` — Тип файла по ID
- [Справочники и права](https://docs.gigma.ru/ERP/%D0%A1%D0%BF%D1%80%D0%B0%D0%B2%D0%BE%D1%87%D0%BD%D0%B8%D0%BA%D0%B8/)
    - `GET    /api/screens` — Получение списка экранов, к которым применяется проверка права на доступ
    - `GET    /api/screens/{id}` — Получение выбранного экрана со списком прав доступа
    - `GET    /api/counterparty_types` — Получение списка с типами контрагентов
    - `GET    /api/counterparty_types/{id}` — Получение выбранного типа контрагента
    - `GET    /api/departments` — Получение списка отделов
    - `GET    /api/departments/{id}` — Получение выбранного отдела
    - `POST   /api/departments` — Добавление отдела
    - `PUT    /api/departments/{id}` — Редактирование отдела
    - `DELETE /api/departments/{id}` — Удаление выбранного отдела
    - `GET    /api/roles` — Получение списка ролей пользователей
    - `GET    /api/roles/{id}` — Получение выбранной роли пользователя
    - `POST   /api/roles` — Добавление роли пользователя
    - `PUT    /api/roles/{id}` — Редактирование роли пользователя
    - `DELETE /api/roles/{id}` — Удаление выбранной роли пользователя
    - `GET    /api/file_types` — Получение списка типов файлов
    - `GET    /api/file_types/{id}` — Получение выбранного типа файла
    - `GET    /api/permissions` — Получение списка прав доступа
    - `GET    /api/permissions/{id}` — Получение выбранного права доступа
    - `POST   /api/permissions` — Добавление права доступа
    - `PUT    /api/permissions/{id}` — Редактирование права доступа
    - `DELETE /api/permissions/{id}` — Удаление выбранного права доступа
    - `GET    /api/call_statuses` — Получение списка статусов звонков
    - `GET    /api/call_statuses/{id}` — Получение выбранного статуса звонка
    - `GET    /api/order_statuses` — Получение списка статусов заказов
    - `GET    /api/order_statuses/{id}` — Получение выбранного статуса заказа
    - `GET    /api/task_statuses` — Получение списка статусов задач
    - `GET    /api/task_statuses/{id}` — Получение выбранного статуса задачи
    - `GET    /api/cities` — Получение списка городов
    - `GET    /api/cities/{id}` — Получение выбранного города
    - `GET    /api/countries` — Получение списка стран
    - `GET    /storage_units` — Получение списка единиц измерения
    - `GET    /storage_units/{id}` — Получение выбранной единицы измерения
    - `GET    /api/brands` — Получение списка брендов
    - `GET    /api/brands/{id}` — Получение выбранного бренда
    - `POST   /api/brands` — Добавление бренда
    - `PUT    /api/brands/{id}` — Обновление бренда
    - `GET    /api/objects` — Получение списка объектов
    - `GET    /api/sales_channels` — Получение списка каналов продаж
    - `GET    /api/vats` — Получение списка НДС
    - `GET    /api/vats/{id}` — Получение выбранного значения НДС
    - `GET    /api/page_types` — Получение списка типов страниц
    - `GET    /api/page_types/{id}` — Получение выбранного типа страницы
    - `GET    /api/integration_types` — Получение списка типов интеграций
    - `GET    /api/integration_types/{id}` — Получение выбранного типа интеграции
    - `GET    /api/integrations` — Получение списка интеграций
    - `GET    /api/integrations/{id}` — Получение выбранной интеграции
    - `GET    /api/settings` — Получение настроек
    - `GET    /api/settings/{id}` — Получение выбранной настройки
    - `GET    /api/delivery_types` — Получение списка типов доставки
    - `GET    /api/block_types` — Получение списка типов блоков
    - `GET    /api/block_types/{id}` — Получение выбранного типа блока
- [Калькулятор и подсказки](https://docs.gigma.ru/ERP/%D0%92%D1%81%D0%BF%D0%BE%D0%BC%D0%BE%D0%B3%D0%B0%D1%82%D0%B5%D0%BB%D1%8C%D0%BD%D1%8B%D0%B5%20%D0%B7%D0%B0%D0%BF%D1%80%D0%BE%D1%81%D1%8B/)
    - `POST   /api/orders/calculator` — Расчёт стоимости товара
    - `POST   /api/search_address` — Поиск адреса
    - `POST   /api/search_bank` — Поиск банка
    - `POST   /api/search_company` — Поиск компании
    - `GET    /api/cities` — Список городов
    - `GET    /api/cities/{id}` — Город по ID
    - `POST   /api/search_nomenclature` — Поиск номенклатуры


# Общее

---

## Как устроена Gigma

Source: https://docs.gigma.ru/product-logic/

# Как устроена Gigma

Gigma объединяет клиентские сценарии и внутреннее управление бизнесом в одной проектной модели. Разработчику важно сначала выбрать API-контур и только потом способ авторизации и конкретные endpoint.

## Два API-контура

| Контур | Кто обращается | Что делает | Основная авторизация |
| --- | --- | --- | --- |
| [Сайты и приложения](/E-Commerce/) | сайт, мобильное приложение, BFF продукта | вход клиента, профиль, каталог, заказы, оплаты и подписки | App Token; Counterparty Bearer — после входа для персональных методов |
| [Платформа](/ERP/) | сотрудник, внутренний backend или агент | бизнесы, приложения, каталог, склады, клиенты, заказы, задачи и контент | Bearer пользователя проекта |

Контуры работают с общими сущностями, но не заменяют друг друга. App Token не даёт прав сотрудника, Bearer сотрудника нельзя использовать как клиентскую авторизацию, а Counterparty Bearer не открывает административные методы.

## Общая модель

### Project

`Project` — верхняя граница данных и доступа одного владельца. Пользователи, бизнесы, приложения, клиенты, заказы и другие объекты должны обрабатываться внутри своего проекта.

### Branch

`Branch` — бизнес, юридическое лицо, филиал или операционное направление внутри проекта. К нему могут относиться реквизиты, сотрудники, приложения, склады и магазины.

### Application

`Application` — конкретный сайт, приложение или сервис. Оно выбирает настройки клиентского продукта: каталог, склады, способы оплаты, контент, меню и подписочные тарифы.

App Token передаётся в заголовке:

```http
Token: <application_token>
```

App Token выбирает `Application`, но не идентифицирует клиента и не даёт административных прав. В прямой frontend-интеграции пользователь может увидеть его в сетевых запросах, поэтому App Token нельзя считать конфиденциальным доказательством личности, покупки или права доступа.

### User

`User` — сотрудник, оператор, менеджер или агент. Он работает с платформенным API по Bearer и ограничен проектом, ролью и permissions.

```http
Authorization: Bearer <user_access_token>
```

### Counterparty

`Counterparty` — внешний клиент или компания, которые взаимодействуют с продуктом. В клиентском контуре Counterparty получает отдельный Bearer для профиля, избранного, заказов и подписок.

```http
Authorization: Bearer <counterparty_access_token>
```

`User` и `Counterparty` — разные субъекты и разные guards. Их токены нельзя взаимозаменять.

## Выберите сценарий

### Создать клиентский продукт без собственного backend

Подходит, когда сайту или приложению достаточно готовых API Gigma.

```text
Frontend
  │ App Token
  │ Counterparty Bearer после входа
  ▼
Gigma API
```

1. Подготовьте `Application`.
2. Получите публичный каталог или контент по App Token.
3. Подключите вход клиента.
4. Для персональных операций добавляйте Counterparty Bearer по правилам конкретного endpoint.
5. Не используйте frontend как единственное доказательство оплаты или права доступа.

Начните с [обзора API для сайтов и приложений](/E-Commerce/).

### Подключить продукт через собственный backend

Используйте BFF или backend, если продукт хранит закрытые данные, собственные роли или платный функционал.

```text
Frontend
  │ локальная HttpOnly-сессия
  ▼
Backend / BFF продукта
  │ App Token
  │ Counterparty Bearer для персональных методов
  ▼
Gigma API
```

Backend хранит Counterparty Bearer, связывает клиента с локальным пользователем и перед защищённым действием повторно проверяет актуальный заказ или подписку. Frontend показывает состояние, но не принимает окончательное решение о доступе.

Подробная схема находится в [интеграции с backend](</E-Commerce/Интеграция%20через%20backend/>).

### Автоматизировать внутреннюю работу бизнеса

Этот сценарий использует платформенный API.

```text
Сотрудник / внутренний сервис / агент
  │ Bearer пользователя проекта
  ▼
API управления бизнесом
```

1. Создайте отдельного пользователя интеграции или агента с минимальной ролью.
2. Выполните вход и получите Bearer.
3. Проверьте пользователя и permissions через `GET /api/user`.
4. Получайте ID только из ресурсов текущего проекта.
5. Для опасных операций используйте подтверждение, журналирование и сверку результата.

Начните с [обзора платформы](/ERP/).

## Как связаны клиентский и внутренний контуры

Типичный запуск продукта выглядит так:

```text
Платформа
  ├─ бизнес и реквизиты
  ├─ Application
  ├─ каталог, склады и остатки
  ├─ оплата, скидки и контент
  ▼
Сайт или приложение
  ├─ вход клиента
  ├─ каталог
  ├─ заказ или подписка
  ▼
Backend продукта
  └─ проверка платного доступа и собственная бизнес-логика
```

Платформенный API настраивает и обслуживает бизнес. Клиентский API использует эти настройки в конкретном `Application`. Собственный backend добавляет закрытые данные и правила, которых нет в Gigma.

## Граница ответственности

| Отвечает Gigma | Отвечает интегратор |
| --- | --- |
| проектная область и проверка поддерживаемых токенов | безопасное хранение токенов и локальных сессий |
| каталог, приложения, заказы, оплаты и подписки в пределах их контрактов | собственные роли, закрытые данные и дополнительные бизнес-правила |
| права пользователя платформы и контекст клиента | подтверждение человека для рискованных автоматизаций |
| webhooks поддерживаемых событий | подпись, дедупликация, очередь и повторная сверка состояния |
| актуальное состояние ресурсов Gigma | обработка сетевой неопределённости и идемпотентность локальных операций |

## Как выбрать следующий раздел

- Создаёте интерфейс для конечного клиента — [Сайты и приложения](/E-Commerce/).
- Настраиваете бизнес, каталог, склады, сотрудников или операционные процессы — [Платформа](/ERP/).
- Нужны общие правила ошибок, повторов и токенов — [Правила API](/conventions/).
- Нужны допустимые ID и источники справочников — [Справочники и значения](/enums/).
- Нужен машиночитаемый контракт — [OpenAPI](/openapi.json) и [Swagger UI](/api-docs/).

---

## Правила API

Source: https://docs.gigma.ru/conventions/

# Правила работы с Gigma API

Эта страница описывает общие правила интеграции. Точный набор полей, заголовков, кодов ответа и ограничений всегда берите из карточки конкретного метода или из [OpenAPI](/openapi.json): backend не использует один универсальный контракт для всех endpoint.

## Базовый адрес

```text
https://api.gigma.ru/api
```

Например, путь `POST /api/login` вызывается по адресу:

```text
https://api.gigma.ru/api/login
```

## Заголовки и формат тела

Для JSON-ответа передавайте:

```http
Accept: application/json
```

Для запроса с JSON-телом добавляйте:

```http
Content-Type: application/json
```

Другие форматы указываются в карточке метода:

- загрузка файлов — `multipart/form-data`;
- introspection клиентского токена — `application/x-www-form-urlencoded`;
- запрос без тела не требует `Content-Type`.

Не устанавливайте `multipart/form-data` вручную вместе с boundary: это должен сделать HTTP-клиент при формировании формы.

<h2 id="auth">Авторизация</h2>

API использует несколько независимых способов доступа.

| Контекст | Заголовок | Где используется |
|---|---|---|
| Сотрудник | `Authorization: Bearer <erp_access_token>` | Административный API |
| Приложение | `Token: <application_token>` | Публичные и клиентские методы конкретного Application |
| Клиент | `Authorization: Bearer <counterparty_access_token>` | Профиль и персональные commerce-операции |
| Приложение + клиент | Оба заголовка одновременно | Заказы, подписки и другие application-scoped методы |
| Backend-интеграция | `Authorization: Basic <base64(client_id:client_secret)>` | `POST /api/counterparty/auth/introspect` |

Точный набор авторизации указан у каждого метода. ERP Bearer и Counterparty Bearer выглядят одинаково на уровне HTTP, но относятся к разным guards и не взаимозаменяются.

### Bearer и серверные credentials — непрозрачные секреты

Sanctum Bearer может содержать служебные разделители, однако клиент не должен разбирать его на части. Используйте значение `access_token.value` целиком. `client_secret` introspection-интеграции храните только на backend.

App Token определяет Application, но в прямой браузерной интеграции не может считаться конфиденциальным: пользователь видит сетевые запросы. Не используйте App Token как замену клиентскому Bearer или проверке прав.

Нельзя:

- помещать токен в URL или query-параметр;
- записывать его в аналитику, error tracking и access-логи;
- определять пользователя по части токена;
- хранить backend-секреты в браузере.

При наличии собственного backend предпочтительна локальная httpOnly-сессия: Bearer проверяется сервером, а браузер не получает долгоживущий секрет Gigma после обмена.

## Готовый запрос

Запрос профиля сотрудника:

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

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

```json
{
  "user": {
    "id": 17,
    "login": "manager@example.test",
    "first_name": "Ирина",
    "is_banned": false,
    "permissions": []
  }
}
```

Wrapper и состав объекта зависят от Resource-класса конкретного endpoint. Не выводите имя корневого поля из URL по аналогии.

## Успешные ответы

Успех определяется диапазоном `2xx`, но конкретный код и тело являются частью контракта метода.

В текущем backend встречаются разные варианты:

- создание может вернуть `200` с Resource либо явно заданный `201`;
- обновление обычно возвращает `200` с объектом;
- удаление нередко возвращает `200` с `{ "message": "..." }`, а не `204`;
- асинхронная операция может использовать собственный статус.

Поэтому:

1. принимайте весь документированный диапазон `2xx`;
2. не пытайтесь парсить тело у ответа, для которого указан `204`;
3. не считайте любой `POST` автоматически ответом `201`;
4. не считайте любой `DELETE` автоматически ответом `204`.

## Форматы значений

Единого формата для всех исторических endpoint нет. Используйте схему конкретного поля.

| Значение | Правило клиента |
|---|---|
| Дата | Обычно `YYYY-MM-DD`; проверяйте `format: date` |
| Дата и время | Парсите как ISO 8601 и сохраняйте timezone |
| Деньги | Не преобразовывайте decimal-string в float без необходимости |
| Boolean | Новые поля используют `true`/`false`; legacy-ответы могут содержать `0`/`1` |
| ID | Считайте ссылкой на ресурс или живой справочник, а не бизнес-константой |
| Nullable | Различайте отсутствующее поле и явно переданный `null` |

## Пагинация, фильтры и сортировка

Пагинация не унифицирована глобально. В API есть:

- Laravel paginator с `data`, `current_page`, `last_page`, `links` и URL страниц;
- UI-таблицы с `columns`, ресурсным массивом и `pagination`;
- непагинированные коллекции со своим wrapper и полем count.

Параметры `page`, `per_page`, `query`, `date_from` и `date_to` встречаются часто, но поддерживаются не каждым методом. Отправляйте только параметры, перечисленные в его карточке. Не переносите фильтры одного ресурса на другой автоматически.

<h2 id="errors">Ошибки</h2>

### Нет или невалиден Bearer

```json
{
  "message": "Unauthenticated."
}
```

### Нет App Token

```json
{
  "message": "Application token is missing"
}
```

### Ошибка валидации

Обычный Form Request возвращает `errors`, а `message` может присутствовать или отсутствовать:

```json
{
  "message": "The given data was invalid.",
  "errors": {
    "phone": ["Поле phone является обязательным."],
    "products.0.id": ["Выбранное значение некорректно."]
  }
}
```

Ключи вложенных полей записываются через точку. Не привязывайте обработку к языку текста: используйте HTTP-код и имя поля.

## Как клиенту реагировать

| Код | Что означает | Действие клиента |
|---|---|---|
| `400` | Запрос понятен, но текущий flow или состояние не подходит | Исправить последовательность действий; не повторять без изменения |
| `401` | Нет, истёк или не подходит токен | Удалить локальную сессию или повторить вход; тот же токен не отправлять циклически |
| `403` | Идентичность подтверждена, но нет permission, scope или token ability | Остановить запрос и проверить настройки доступа |
| `404` | Ресурс отсутствует либо скрыт проектной/application-границей | Не перебирать ID; проверить контекст проекта и приложения |
| `409` | Конфликт состояния или повтор операции | Получить актуальное состояние и решить конфликт |
| `415` | Неверный `Content-Type` | Пересобрать запрос в формате из карточки метода |
| `422` | Не прошла валидация или бизнес-проверка | Показать ошибки полей либо исправить данные |
| `429` | Превышен лимит | Учесть `Retry-After`, применить backoff с jitter и не создавать параллельный retry-шторм |
| `5xx` или timeout | Результат неизвестен либо backend временно недоступен | Для чтения — ограниченный retry; для записи — сначала сверить состояние через GET |

## Rate limits

Лимиты задаются на уровне конкретных маршрутов. Универсального публичного значения «60 запросов в минуту для всего API» нет.

Примеры из текущей конфигурации backend:

| Операция | Ограничение |
|---|---|
| `POST /api/login` | 5 запросов в минуту |
| `POST /api/counterparty/login` | 5 в минуту на project + contact и 30 в минуту на IP |
| `POST /api/counterparty/send_password` | 3 в час на project + contact и 20 в час на IP |
| `POST /api/counterparty/auth/introspect` | 60 в минуту на IP и 300 в минуту на backend-клиент |
| `POST /api/counterparty/session/heartbeat` | 6 в минуту на клиентскую сессию |

Эти значения описывают текущую реализацию, а не бессрочную квоту продукта. Клиент всё равно должен корректно обрабатывать `429` и заголовки ответа.

## Повторы и идемпотентность

Общего публичного контракта `Idempotency-Key` для Gigma API нет.

| Запрос | Рекомендация |
|---|---|
| `GET` | Можно повторить с ограниченным exponential backoff |
| `POST` создания или оплаты | Не повторять вслепую после timeout/`5xx`; сначала найти результат по бизнес-идентификатору |
| `PUT`/`PATCH` | Повтор допустим только если карточка метода и операция действительно идемпотентны |
| `DELETE` | Не считать глобально идемпотентным: повтор может вернуть другой код или тело |

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

## Webhook

В текущем публичном контракте Application поддерживает событие `order.paid`.

При доставке Gigma передаёт:

```http
X-Webhook-Event: order.paid
X-Webhook-Event-Id: <event_id>
X-Webhook-Delivery-Id: <delivery_id>
X-Webhook-Timestamp: <unix_timestamp>
X-Signature: sha256=<hex_digest>
Content-Type: application/json
```

Подпись вычисляется по исходным байтам тела:

```text
HMAC_SHA256(secret, timestamp + "." + raw_body)
```

Получатель должен:

1. проверить допустимый возраст `X-Webhook-Timestamp`;
2. вычислить HMAC по необработанному body и сравнить подпись constant-time способом;
3. дедуплицировать событие по `X-Webhook-Event-Id` или доставку по `X-Webhook-Delivery-Id`;
4. сохранить событие транзакционно;
5. быстро вернуть любой `2xx`.

Redirect не используется, timeout доставки — 10 секунд. После неуспеха повторы планируются через 1, 5, 30, 120 и 720 минут. После исчерпания попыток доставка переходит в `failed` и может быть повторно отправлена администратором.

Подробная настройка находится в [«Платформа / Приложения»](/ERP/Приложения/#application-webhooks-list).

## Версионирование и совместимость

Публичные пути сейчас находятся под `/api` без `/v1`. Отсутствие версии в URL не означает, что клиент может полагаться на недокументированные поля или внутренние классы.

Для устойчивой интеграции:

- отправляйте только документированные поля;
- допускайте появление новых необязательных полей в JSON;
- не полагайтесь на порядок ключей;
- фиксируйте контрактные тесты на критические сценарии;
- проверяйте изменения OpenAPI перед релизом клиента.

## Машиночитаемый слой

- [openapi.json](/openapi.json) — методы, security schemes и схемы, извлечённые из карточек endpoint;
- [Swagger UI](/api-docs/) — просмотр и ручная проверка запросов;
- [llms.txt](/llms.txt) — индекс документации для агента;
- [llms-full.txt](/llms-full.txt) — полный текст страниц;
- [erp-rules.txt](/erp-rules.txt) — короткие правила безопасной интеграции.

OpenAPI не подменяет runtime-код: генератор намеренно не угадывает ID справочников и не выводит `201`/`204` только из HTTP-метода.

Спецификация собирается из карточек методов, поэтому отсутствие данных означает «не зафиксировано», а не «запрещено». Код `2XX` значит, что точный статус не подтверждён карточкой; отсутствие `requestBody` не доказывает, что тело не нужно; `example` иллюстрирует формат, а не допустимый диапазон значений. Полный список правил чтения для агента — в [erp-rules.txt §13](/erp-rules.txt).

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

- Разберите модель платформы на странице [«Как устроена Gigma»](/product-logic/).
- Получайте ID через [живые справочники](/enums/).
- Выберите нужный доменный раздел: [E-Commerce](/E-Commerce/Сайты%20и%20приложения/) или [Платформа](/ERP/Авторизация/).
- Для собственного backend начните с [introspection](</E-Commerce/Интеграция%20через%20backend/introspect/>).

---

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

Source: https://docs.gigma.ru/enums/

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

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

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

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

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

## Рекомендуемый flow

1. При запуске интеграции запросите нужные справочники.
2. Сохраните весь объект, а не только название: `id`, `name` и дополнительные поля могут понадобиться позже.
3. Передавайте в write-запрос фактический `id`.
4. Обновляйте кэш по TTL либо после `404`/`422`, указывающих на устаревшую ссылку.
5. Не подбирайте соседний ID и не делайте вывод по пропуску в последовательности.

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

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

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

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

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

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

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

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

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

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

```json
{
  "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](/conventions/).
- Конкретные request/response поля: [Swagger UI](/api-docs/) или [openapi.json](/openapi.json).
- Commerce-справочники: [E-Commerce / Справочники](/E-Commerce/Справочники/).
- Административные справочники: [Платформа / Справочники](/ERP/Справочники/).

## Swagger UI

_Источник недоступен: /app/src/routes/api-docs/+page.svx_


# Сайты и приложения

---

## Обзор API

Source: https://docs.gigma.ru/E-Commerce/

# API для сайтов, приложений и сервисов

Этот раздел описывает API Gigma для сайтов, приложений и цифровых сервисов. Gigma хранит настройки приложения, клиентские профили, каталог, заказы, платежи, подписки и управляемый контент. Вы создаёте интерфейс продукта и определяете, какие возможности получает клиент.

## Что можно собрать

- витрину товаров или услуг;
- оформление обычного заказа и онлайн-оплату;
- подписочный сервис с периодической оплатой;
- личный кабинет клиента;
- сайт или приложение с управляемыми страницами, меню и контентными блоками;
- закрытый сервис, где доступ открывается после подтверждённой покупки или активной подписки.

## Как устроена модель

| Сущность | Простое объяснение |
| --- | --- |
| `Project` | граница данных и доступа вашего бизнеса |
| `Application` | конкретный сайт, приложение или сервис внутри проекта |
| App Token | выбирает `Application` и разрешает обращаться к API текущего сайта, приложения или сервиса |
| Client / `Counterparty` | клиент, который входит, оформляет заказы и оплачивает подписки |
| Counterparty Bearer | подтверждает, от имени какого клиента выполняется запрос |

`Application` не создаёт интерфейс и не заводит отдельную базу клиентов. Оно связывает запросы с настройками нужного продукта: каталогом, складами, контентом, способами оплаты и подписочными тарифами.

Подробные правила заголовков и назначения токенов собраны в [соглашениях об авторизации](/conventions/#auth).

## Выберите схему интеграции

### Прямые запросы из сайта или приложения

Подходят для публичного каталога, страниц, меню, входа клиента и стандартного оформления заказа. Клиентское приложение передаёт App Token, а после входа — также Counterparty Bearer.

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

### Через собственный backend или BFF

Используйте эту схему, когда покупка или подписка в Gigma должна открыть функции вашего сервиса. Ваш backend хранит Counterparty Bearer, создаёт локальную сессию и перед выдачей закрытых данных проверяет актуальное состояние заказа или подписки в Gigma.

Перейдите к [интеграции с backend](</E-Commerce/Интеграция%20через%20backend/>).

## Три основных сценария

### Каталог или контентный сайт

1. [Подготовьте `Application`](</E-Commerce/Сайты%20и%20приложения/>).
2. Получите [каталог, тарифы и цены](/E-Commerce/Товары/).
3. Подключите [страницы и публикации](/E-Commerce/Страницы/), [контентные блоки](</E-Commerce/Динамический%20контент/>) и [меню](</E-Commerce/Навигационная%20панель/>).
4. Добавьте вход только для функций, которым нужен клиент: избранное, история, заказ или подписка.

### Обычная покупка

1. Покажите товары и доступные варианты доставки и оплаты.
2. Рассчитайте корзину через `POST /api/counterparty/orders/precalculate`.
3. [Авторизуйте клиента](/E-Commerce/Авторизация/).
4. Создайте заказ через `POST /api/counterparty/orders`.
5. Считайте оплату подтверждённой только по состоянию, которое вернул backend Gigma, а не по возврату пользователя с платёжной страницы.

Подробный поток находится в разделе [«Заказы, оплаты и подписки»](/E-Commerce/Заказы/).

### Подписка и платный доступ

1. Получите тарифы из `subscription-catalog`.
2. Авторизуйте клиента.
3. Создайте checkout подписки и перенаправьте клиента по `payment_link`.
4. После оплаты повторно получите подписки клиента.
5. Открывайте доступ только при `status = "active"` и неистёкшем `current_period_end`.
6. Повторяйте эту проверку на своём backend перед защищённым действием.

## Минимальный путь до первого рабочего запроса

1. Получите ERP-доступ к нужному `Project`.
2. Создайте или выберите `Application` и сохраните его App Token.
3. Настройте каталог, склады, оплату и контент в платформенном контуре.
4. Проверьте App Token запросом `GET /api/counterparty/settings`.
5. Получите каталог или подписочные тарифы.
6. Подключите один способ входа клиента.
7. Реализуйте один сквозной сценарий: каталог → вход → заказ либо тариф → вход → checkout → проверка подписки.

## Карта документации

| Задача | Раздел |
| --- | --- |
| Создать и настроить контекст продукта | [Подготовка приложения](</E-Commerce/Сайты%20и%20приложения/>) |
| Спрятать токены и проверять платный доступ на сервере | [Интеграция с backend](</E-Commerce/Интеграция%20через%20backend/>) |
| Войти по коду или callback-звонку | [Вход клиента](/E-Commerce/Авторизация/) |
| Получить и изменить профиль | [Профиль клиента](</E-Commerce/Контрагент%20(клиент)/>) |
| Показать товары, цены и подписочные тарифы | [Каталог, тарифы и цены](/E-Commerce/Товары/) |
| Рассчитать корзину, создать заказ или подписку | [Заказы, оплаты и подписки](/E-Commerce/Заказы/) |
| Получить управляемый контент | [Контентные блоки](</E-Commerce/Динамический%20контент/>), [страницы и публикации](/E-Commerce/Страницы/), [меню и навигация](</E-Commerce/Навигационная%20панель/>) |
| Получить настройки и данные поиска | [Настройки и поиск](</E-Commerce/Вспомогательные%20запросы/>) |
| Показать клиенту системные события | [Уведомления клиента](/E-Commerce/Уведомления/) |
| Получить доставку, оплату, магазины и фильтры | [Доставка, оплата и справочники](/E-Commerce/Справочники/) |

## Правила, которые нельзя переносить на frontend

- факт оплаты и право доступа подтверждает backend;
- App Token и Counterparty Bearer решают разные задачи и не заменяют друг друга;
- идентификаторы справочников получайте из API, а не фиксируйте по примеру;
- неизвестный результат создания платежа не означает неуспех: сначала проверьте текущее состояние;
- Counterparty Bearer, callback-сессии и платёжные данные нельзя писать в URL, аналитику или клиентские логи.

---

## Подготовка приложения

Source: https://docs.gigma.ru/E-Commerce/%D0%A1%D0%B0%D0%B9%D1%82%D1%8B%20%D0%B8%20%D0%BF%D1%80%D0%B8%D0%BB%D0%BE%D0%B6%D0%B5%D0%BD%D0%B8%D1%8F/

# Подготовка приложения

Перед подключением API создайте в Gigma `Application` — контекст конкретного сайта, приложения или сервиса. Это может быть интернет-магазин, мобильное приложение, личный кабинет, подписочный продукт или другой клиентский интерфейс.

`Application` определяет, какие настройки увидит клиентский интерфейс: каталог, склады, способы оплаты, контент, меню и подписочные тарифы. Сам интерфейс и его маршруты создаёт ваша команда.

## Что нужно получить

Для запуска нужны:

- ERP-доступ к нужному `Project`;
- существующее или новое `Application`;
- App Token этого приложения;
- настроенные источники каталога и оплаты;
- хотя бы один готовый пользовательский сценарий: каталог, заказ или подписка.

Для создания или изменения приложения у ERP-пользователя должно быть соответствующее право, например `create-applications` или `edit-applications`.

## Что настроить в Gigma

| Настройка | Для чего нужна |
| --- | --- |
| Категории, бренды и склады | определяют ассортимент и цены каталога |
| Способы доставки и оплаты | используются при создании обычного заказа |
| Подписочные тарифы | формируют каталог подписок конкретного приложения |
| Страницы, блоки и меню | позволяют менять контент без выпуска новой версии frontend |
| Уведомления и webhooks | сообщают клиенту и вашему backend о событиях |

Каталог создаётся в [Платформа / Номенклатура](/ERP/Номенклатура/), контент — в [Платформа / Страницы](/ERP/Страницы/), настройки приложения — в [Платформа / Приложения](/ERP/Приложения/).

## Как App Token участвует в запросе

Передавайте App Token в заголовке `Token`:

```http
GET /api/counterparty/settings HTTP/1.1
Host: api.gigma.ru
Token: <application_token>
Accept: application/json
```

Успешный ответ подтверждает, что token распознан и контекст `Application` выбран:

```json
{
    "wholesale": false
}
```

App Token выбирает приложение, но не идентифицирует клиента. Профиль работает по Counterparty Bearer; избранное, заказы и подписки требуют Counterparty Bearer вместе с App Token.

## Порядок подключения

1. Создайте или выберите `Application` через [ERP API приложений](/ERP/Приложения/).
2. Сохраните App Token и не смешивайте его с ERP Bearer или Counterparty Bearer.
3. Настройте каталог, склады, оплату и доставку.
4. Для подписочного продукта назначьте активные тарифы текущему `Application`.
5. Добавьте страницы, блоки и меню, если контент должен управляться из Gigma.
6. Проверьте `GET /api/counterparty/settings`.
7. Получите [каталог, тарифы и цены](/E-Commerce/Товары/).
8. Подключите [вход клиента](/E-Commerce/Авторизация/).
9. Реализуйте [заказ, оплату или подписку](/E-Commerce/Заказы/).

## Как выбрать следующую страницу

- Только публичная витрина: начните с [каталога, тарифов и цен](/E-Commerce/Товары/).
- Нужен личный кабинет: подключите [вход клиента](/E-Commerce/Авторизация/) и [профиль](</E-Commerce/Контрагент%20(клиент)/>).
- Покупка товара: используйте [заказы, оплаты и подписки](/E-Commerce/Заказы/) и [доставку, оплату и справочники](/E-Commerce/Справочники/).
- Платный доступ к вашему сервису: сначала изучите [интеграцию с backend](</E-Commerce/Интеграция%20через%20backend/>).

## Граница ответственности

Gigma хранит клиентские профили, каталог, заказы, оплаты и подписки. Ваш продукт отвечает за интерфейс, локальную сессию и собственные закрытые данные. Не считайте наличие кнопки «Оплачено» на frontend доказательством покупки: право доступа должно подтверждаться актуальным состоянием на backend.

---

## Интеграция с backend

Source: https://docs.gigma.ru/E-Commerce/%D0%98%D0%BD%D1%82%D0%B5%D0%B3%D1%80%D0%B0%D1%86%D0%B8%D1%8F%20%D1%87%D0%B5%D1%80%D0%B5%D0%B7%20backend/

# Интеграция с backend

Используйте собственный backend или BFF, когда покупка в Gigma должна открыть закрытые данные или функции вашего продукта. Frontend показывает интерфейс, Gigma хранит состояние профиля, заказа, оплаты и подписки, а ваш backend принимает окончательное решение о доступе.

## Разделение ответственности

| Компонент | Ответственность |
| --- | --- |
| Gigma | вход клиента, профиль, каталог, заказ, платёж и подписка |
| Ваш backend | локальная сессия, связь с собственным пользователем, проверка доступа, выдача закрытых данных |
| Frontend | ввод пользователя и отображение состояния; не является источником истины об оплате |

```text
Браузер
  │ HttpOnly cookie вашей сессии
  ▼
Backend / BFF продукта
  │ App Token + Counterparty Bearer
  ▼
Gigma API
```

## Рекомендуемый поток входа

1. Backend инициирует выбранный способ [входа клиента](/E-Commerce/Авторизация/).
2. После успешного входа он получает Counterparty Bearer и связывает его с локальным пользователем.
3. Bearer хранится на сервере; браузер получает только cookie локальной сессии.
4. Перед обращением к Gigma backend добавляет нужный App Token и Bearer клиента.
5. При выходе backend отзывает токен в Gigma и удаляет локальную сессию.

Для cookie используйте `HttpOnly`, `Secure` и подходящий вашему доменному сценарию `SameSite`. Counterparty Bearer не должен попадать в URL, browser storage, аналитику или обычные application-логи.

## Как открывать доступ после покупки

### Доступ по обычному заказу

1. Получите заказ через `GET /api/counterparty/orders/{id}`.
2. Убедитесь, что заказ принадлежит текущему клиенту и текущему `Application` — backend Gigma дополнительно проверяет это сам.
3. Разрешайте действие только для вашего явно заданного оплаченного статуса.
4. Не доверяйте `payment_link`, query-параметрам возврата или данным, присланным frontend.

### Доступ по подписке

Получите `GET /api/counterparty/subscriptions` и найдите нужный тариф. Минимальное правило действующего доступа:

```text
subscription.status == "active"
AND subscription.current_period_end > now
```

`charging`, `past_due` и `canceled` не дают закрытый доступ. Проверяйте состояние перед защищённым действием, а не только при входе пользователя.

## Webhook и повторная проверка

Webhook `order.paid` помогает быстро обновить локальное состояние, но не должен быть единственным доказательством доступа. Обработчик должен:

1. проверить подпись и идентификатор `Application`;
2. обработать событие идемпотентно;
3. повторно получить заказ или подписку из Gigma;
4. только после этого обновить локальное право доступа.

Настройка webhooks описана в [Платформа / Приложения](/ERP/Приложения/#application-webhooks-list).

## Когда нужен introspect

Обычный BFF уже получает Bearer от Gigma и может использовать его напрямую. [Introspect](</E-Commerce/Интеграция%20через%20backend/introspect/>) нужен, когда Bearer передаётся вашему backend другой доверенной системой и требуется серверная проверка токена отдельными client credentials.

## Heartbeat не является проверкой доступа

[Heartbeat](</E-Commerce/Интеграция%20через%20backend/heartbeat/>) учитывает активное время клиентской сессии. Он не подтверждает оплату, подписку или право на функцию.

## Ошибки и повторы

- `401` — очистите локальную сессию или повторите вход; не зацикливайте refresh.
- `403` — клиент опознан, но действие запрещено вашим правилом доступа.
- `409` — операция конфликтует с уже выполняемой; сначала получите текущее состояние.
- `422` — исправьте данные или бизнес-условия, автоматический повтор не поможет.
- `429` — соблюдайте `Retry-After`.
- `5xx` и сетевой сбой — результат операции может быть неизвестен; сначала выполните безопасное чтение состояния.

Общие форматы ответов и правила повторов находятся в [соглашениях API](/conventions/).

## Карта интеграции

| Задача | Раздел |
| --- | --- |
| Подготовить `Application` и App Token | [Подготовка приложения](</E-Commerce/Сайты%20и%20приложения/>) |
| Получить Counterparty Bearer | [Вход клиента](/E-Commerce/Авторизация/) |
| Получить профиль и app-scoped проверку | [Профиль клиента](</E-Commerce/Контрагент%20(клиент)/>) |
| Получить товары или тарифы | [Каталог, тарифы и цены](/E-Commerce/Товары/) |
| Создать покупку и проверить доступ | [Заказы, оплаты и подписки](/E-Commerce/Заказы/) |
| Учесть активное время | [Heartbeat](</E-Commerce/Интеграция%20через%20backend/heartbeat/>) |
| Проверить Bearer из другой системы | [Introspect](</E-Commerce/Интеграция%20через%20backend/introspect/>) |

---

## Heartbeat клиентской сессии

Source: https://docs.gigma.ru/E-Commerce/%D0%98%D0%BD%D1%82%D0%B5%D0%B3%D1%80%D0%B0%D1%86%D0%B8%D1%8F%20%D1%87%D0%B5%D1%80%D0%B5%D0%B7%20backend/heartbeat/

# Heartbeat клиентской сессии

Heartbeat обновляет время последней активности и длительность клиентской сессии. Запись сессии создаётся при входе, отдельный запрос для её начала не нужен.

[Вернуться к схеме интеграции](</E-Commerce/Интеграция%20через%20backend/>).

### Обновление активности клиентской сессии

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/counterparty/session/heartbeat`  
**Авторизация:** App Token + Bearer token  
**Headers:** `Token: {application_token}; Authorization: Bearer {counterparty_token}`  

#### Запрос

Тело запроса не требуется.

```http
POST /api/counterparty/session/heartbeat HTTP/1.1
Host: api.gigma.ru
Token: <application_token>
Authorization: Bearer <counterparty_token>
Accept: application/json
```

#### Ответ

```json
{
    "session": {
        "id": 154,
        "status": "active",
        "started_at": "2026-07-30T03:00:00+00:00",
        "last_seen_at": "2026-07-30T03:02:00+00:00",
        "duration_seconds": 120
    },
    "server_time": "2026-07-30T03:02:00+00:00",
    "next_heartbeat_in_seconds": 60
}
```

##### Поля ответа

- `session.id` — идентификатор сессии.
- `session.status` — состояние сессии; успешный heartbeat возвращает `active`.
- `session.started_at` — время начала сессии в ISO 8601.
- `session.last_seen_at` — время последней активности в ISO 8601.
- `session.duration_seconds` — активное время в секундах.
- `server_time` — время сервера в ISO 8601.
- `next_heartbeat_in_seconds` — рекомендуемая задержка до следующего запроса.

Отправляйте heartbeat через интервал из `next_heartbeat_in_seconds`, но не чаще шести раз в минуту для одного Bearer.

За один интервал учитывается не больше 180 секунд. После перерыва в 300 секунд Gigma закрывает прежнюю сессию и начинает новую.

#### Ошибки

- `401` — проверьте App Token и Bearer.
- `404` — проверьте проект и `Application`.
- `429 Too Many Attempts.` — дождитесь окончания `Retry-After`.
- `503 counterparty_session_unavailable` — повторите запрос позже без бесконечного цикла повторов.


## Что почитать ещё

- [Интеграция с backend](</E-Commerce/Интеграция%20через%20backend/>).
- [Вход клиента](/E-Commerce/Авторизация/).
- [Соглашения API](/conventions/).

---

## Проверка Bearer-токена

Source: https://docs.gigma.ru/E-Commerce/%D0%98%D0%BD%D1%82%D0%B5%D0%B3%D1%80%D0%B0%D1%86%D0%B8%D1%8F%20%D1%87%D0%B5%D1%80%D0%B5%D0%B7%20backend/introspect/

# Проверка Bearer через introspect

Используйте `introspect`, если Counterparty Bearer пришёл на backend из другой системы. Для обычного входа этот запрос не нужен: backend уже получает Bearer от Gigma.

[Вернуться к схеме интеграции](</E-Commerce/Интеграция%20через%20backend/>).

## Получите credentials

Запросите у администратора Gigma отдельные `client_id`, `client_secret` и `audience` для нужного `Application`. Получить эти credentials через публичные методы API нельзя.

Сохраните `client_secret` сразу после выдачи: повторно он не показывается. Если secret потерян или скомпрометирован, запросите его ротацию.

### Проверка Counterparty Bearer

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/counterparty/auth/introspect`  
**Авторизация:** Basic client credentials  
**Headers:** `Authorization: Basic {base64(client_id:client_secret)}; Content-Type: application/x-www-form-urlencoded`  

#### Параметры запроса

- `token` *(string, обязательно)* — Bearer целиком, включая разделитель `|`.
- `audience` *(string, обязательно, до 64 символов)* — значение, выданное вместе с credentials.

Передавайте параметры в теле form-запроса. Query-параметры не поддерживаются.

#### Пример запроса

```http
POST /api/counterparty/auth/introspect HTTP/1.1
Host: api.gigma.ru
Authorization: Basic <base64(client_id:client_secret)>
Accept: application/json
Content-Type: application/x-www-form-urlencoded

token=12%7CplainSanctumToken&audience=project-backend
```

#### Ответ для действующего Bearer

```json
{
    "active": true,
    "principal_handle": "0f1c1f8e-7a64-4c7a-9c10-1dd25edc54d0",
    "project": { "id": 12 },
    "application": {
        "id": 34,
        "name": "Личный кабинет"
    },
    "scopes": ["chat:access"],
    "expires_at": "2026-07-31T03:00:00+00:00"
}
```

##### Описание полей ответа

- `active` — результат проверки Bearer.
- `principal_handle` — стабильный UUID клиента для связи с пользователем вашей системы.
- `project.id` — идентификатор проекта Gigma.
- `application.id` — идентификатор приложения, выпустившего Bearer.
- `application.name` — название приложения.
- `scopes` — разрешения backend-клиента.
- `expires_at` — время окончания Bearer или `null`.

Неизвестный, отозванный, просроченный или выпущенный другим приложением Bearer возвращается как неактивный:

```json
{
    "active": false
}
```

`active: false` — результат проверки, а не ошибка авторизации backend-клиента.

#### Ошибки

- `401` — проверьте `client_id`, `client_secret` и состояние backend-клиента.
- `403 Forbidden.` — проверьте `audience`.
- `415 Unsupported Media Type.` — отправьте `application/x-www-form-urlencoded`, а не JSON.
- `422` — передайте `token` и `audience` в теле запроса.
- `429 Too Many Attempts.` — дождитесь окончания `Retry-After`.


## Что почитать ещё

- [Интеграция с backend](</E-Commerce/Интеграция%20через%20backend/>).
- [Вход клиента](/E-Commerce/Авторизация/).
- [Соглашения API](/conventions/).

---

## Вход клиента

Source: https://docs.gigma.ru/E-Commerce/%D0%90%D0%B2%D1%82%D0%BE%D1%80%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D1%8F/

# Вход клиента

Здесь описаны контракты входа и выхода клиента. Общий порядок подключения находится на странице [«Подготовка приложения»](</E-Commerce/Сайты%20и%20приложения/>), а серверное хранение Bearer и локальная сессия — в разделе [«Интеграция с backend»](</E-Commerce/Интеграция%20через%20backend/>).

Назначение токенов и общие заголовки вынесены в [соглашения об авторизации](/conventions/#auth). После входа сохраняйте Bearer целиком, включая разделитель `|`.

## Вход по коду

### Запрос одноразового кода

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/counterparty/send_password`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}`  

Создаёт или находит клиента внутри проекта текущей витрины и отправляет одноразовый код: звонком на телефон или письмом на email.

#### Параметры запроса

- `phone` *(string, обязательно)* — телефон или email клиента. Для телефона используйте нормализованный формат `7XXXXXXXXXX`.

#### Пример запроса

```json
{
    "phone": "79999999990"
}
```

Несмотря на историческое имя поля `phone`, в нём также можно передать email.

#### Ответ

При успешном действии возвращается HTTP `200`.

```json
{
    "message": "Password successfully send"
}
```

Код действует 5 минут и погашается после успешного входа.

#### Возможные ошибки

- `401 Application token is missing` — не передан заголовок `Token`.
- `401 Application token is invalid` — App Token неизвестен или выключен.
- `422` — поле `phone` отсутствует или имеет неверный формат.
- `429` — превышен лимит: до 3 запросов в час на контакт внутри проекта и до 20 запросов в час с одного IP.
- `500 Internal server error` — код не удалось отправить.


### Вход по одноразовому коду

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/counterparty/login`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}`  

#### Параметры запроса

- `phone` *(string, обязательно)* — телефон в цифровом формате или email, на который запрашивался код.
- `password` *(обязательно)* — одноразовый код из звонка или письма.
- `device` *(string, необязательно, 3–50 символов)* — имя устройства для токена, например `storefront-web`.

#### Пример запроса

```json
{
    "phone": "79999999990",
    "password": "1111",
    "device": "storefront-web"
}
```

#### Ответ

При успешном действии возвращается HTTP `200` с объектом клиента и Bearer token.

```json
{
    "counterparty": {
        "id": 1,
        "type": {
            "id": 2,
            "name": "Розница",
            "created_at": "2024-03-23T10:27:06.000000Z"
        },
        "manager": {
            "id": 1,
            "first_name": "Артём",
            "last_name": "Полищук",
            "middle_name": "Николаевич",
            "name": "Полищук Артём"
        },
        "avatar": null,
        "first_name": "Алексей",
        "last_name": "Петров",
        "middle_name": "Викторович",
        "birthday": "1980-04-02",
        "address": "630073, Новосибирская область, город Новосибирск, Новогодняя ул., д. 20/1, кв. 26",
        "phone_1": "79999999990",
        "phone_2": "78888888888",
        "email": "support@itecho.ru",
        "created_at": "2024-03-22T14:01:37.000000Z",
        "updated_at": "2024-03-23T10:48:33.000000Z",
        "favourite_products": [],
        "access_token": {
            "value": "2|k8InFzsVIDB3sumslYax1hWJcZDglKptEgIWzxWo21bdb3d6"
        }
    }
}
```

`access_token.value` — Bearer token клиента. Полный состав объекта описан на странице [Профиль клиента](/E-Commerce/Контрагент%20(клиент)/).

#### Возможные ошибки

- `400 Send password before login. Password TTL is 5 minutes.` — код не запрашивался, уже использован или истёк.
- `401 Application token is missing` / `Application token is invalid` — проблема с App Token.
- `401 Указан неправильный пароль` — неверный одноразовый код.
- `422` — параметры не прошли валидацию, например в системе нет указанного телефона или email.
- `429` — превышен лимит: до 5 попыток в минуту на контакт внутри проекта и до 30 попыток в минуту с одного IP.


## Вход из miniapp

### Авторизация miniapp по подписанному контакту

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/counterparty/miniapps/{provider}/contact_auth`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}`  

Используется, когда miniapp получил у провайдера подписанное подтверждение контакта клиента. В ответе выдаётся обычный `counterparty.access_token.value` для дальнейшей работы с API Gigma.

Канонический маршрут находится в counterparty-контуре. Не используйте alias URL вида `/api/miniapps/.../auth/...`.

#### Параметры пути

- `provider` — маршрут принимает `max` или `telegram`. Подписанный вход по контакту сейчас поддерживает `max`; для Telegram без подтверждения владения телефоном backend возвращает `422`.

#### Параметры запроса

- `phone` *(string, обязательно, до 32 символов)* — телефон из подписанного contact payload. Backend нормализует его к `7XXXXXXXXXX`.
- `auth_date` *(integer, обязательно)* — время подписи Unix в секундах, миллисекундах или микросекундах; значение не должно быть из будущего или старше настроенного TTL.
- `hash` *(string, обязательно)* — подпись contact payload, 64 hex-символа.
- `init_data` *(string, обязательно, до 8192 символов)* — подписанные init data miniapp.
- `device` *(string, необязательно, до 255 символов)* — имя устройства для токена, например `max-miniapp`.

#### Пример запроса

```json
{
    "phone": "+79139277802",
    "auth_date": 1780000000,
    "hash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "init_data": "auth_date=1780000000&user=%7B%22id%22%3A123456%7D&hash=...",
    "device": "max-miniapp"
}
```

#### Ответ

При успешном действии возвращается HTTP `200` с полным объектом клиента и `access_token` — так же, как при входе по коду. Ниже ответ сокращён:

```json
{
    "counterparty": {
        "id": 1,
        "phone_1": "79139277802",
        "access_token": {
            "value": "2|k8InFzsVIDB3sumslYax1hWJcZDglKptEgIWzxWo21bdb3d6"
        }
    }
}
```

#### Возможные ошибки

- `401 Application token is missing` / `Application token is invalid` — проблема с App Token.
- `401 miniapp_contact_auth_invalid` — подпись, `init_data` или срок действия не прошли проверку.
- `422` — параметры запроса не прошли валидацию.
- `422 miniapp_contact_auth_not_supported` — провайдер не поддерживает безопасный signed contact login, например Telegram без proof владения телефоном.
- `429` — превышен лимит 5 запросов в минуту.
- `503 miniapp_contact_auth_not_configured` — на backend не настроен токен провайдера.


## Вход по callback-звонку

Callback-flow состоит из трёх шагов: начать сессию, дождаться подтверждения звонка и обменять подтверждённую сессию на Bearer token.

Перед началом работы сгенерируйте `client_nonce` — криптографически случайную строку из 32–128 символов base64url (`A–Z`, `a–z`, `0–9`, `-`, `_`). Используйте новый `client_nonce` для каждой попытки входа и передавайте одно и то же значение во всех трёх запросах.

Если у приложения есть backend или BFF, генерируйте и храните `client_nonce` и `session_token` на сервере. В прямой frontend-интеграции держите их только в памяти текущей вкладки. Не сохраняйте эти значения в URL, `localStorage`, `sessionStorage`, аналитике или клиентских логах.

### Инициализация callback-авторизации

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/counterparty/callback_auth/init`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}; Content-Type: application/json`  

Создаёт callback-сессию и возвращает номер, на который клиент должен позвонить со своего телефона.

#### Параметры запроса

- `phone` *(string, обязательно)* — телефон клиента. Backend нормализует значение к `7XXXXXXXXXX`.
- `client_nonce` *(string, обязательно)* — секрет текущей попытки входа, 32–128 символов base64url.

#### Пример запроса

```json
{
    "phone": "+7 (900) 123-45-67",
    "client_nonce": "R2xvYmFsTm9uY2VFeGFtcGxlMTIzNDU2Nzg5MA"
}
```

#### Ответ

При успешном действии возвращается HTTP `200`.

```json
{
    "session_token": "opaque-session-token",
    "callback_number": "79001000011",
    "expires_at": "2026-07-03T01:23:45+00:00"
}
```

- `session_token` — временный токен callback-сессии, а не Bearer token клиента.
- `callback_number` — номер, на который клиент должен позвонить с указанного телефона.
- `expires_at` — время окончания сессии. TTL составляет 5 минут.

IP не участвует в авторизации сессии: переход между Wi-Fi и мобильной сетью не прерывает вход.

#### Возможные ошибки

- `401 Application token is missing` / `Application token is invalid` — проблема с App Token.
- `409 callback_auth_session_already_started` — этот `client_nonce` уже использован. Начните новую попытку с новым значением.
- `409 callback_auth_challenge_already_active` — для телефона уже создаётся звонок. Дождитесь окончания cooldown и повторите запрос с новым `client_nonce`.
- `422` — проверьте телефон и формат `client_nonce`.
- `429 callback_auth_rate_limited` — повторите запрос через число секунд из заголовка `Retry-After`.
- `503 UCaller service unavailable.` — сервис callback-звонков временно недоступен. Повторите запрос позже.


### Проверка статуса callback-авторизации

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/counterparty/callback_auth/status`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}; Content-Type: application/json`  

Возвращает текущее состояние callback-сессии. Этот метод никогда не возвращает Bearer token.

#### Параметры запроса

- `session_token` *(string, обязательно, до 128 символов)* — значение из ответа `callback_auth/init`.
- `client_nonce` *(string, обязательно)* — значение, переданное в `callback_auth/init`.

#### Пример запроса

```json
{
    "session_token": "opaque-session-token",
    "client_nonce": "R2xvYmFsTm9uY2VFeGFtcGxlMTIzNDU2Nzg5MA"
}
```

#### Ответ

При успешном запросе API вернёт HTTP `200 OK`.

```json
{
    "status": "pending",
    "expires_at": "2026-07-03T01:23:45+00:00",
    "server_time": "2026-07-03T01:20:10+00:00",
    "remaining_seconds": 215
}
```

| `status` | Что делать |
| --- | --- |
| `pending` | Повторите запрос через 3–5 секунд. Для таймера используйте `server_time` и `remaining_seconds`. |
| `verified` | Вызовите `POST /api/counterparty/callback_auth/exchange` до времени из `expires_at`. После подтверждения звонка окно обмена составляет не менее 120 секунд. |
| `expired` | Очистите данные сессии и начните новую попытку с новым `client_nonce`. |

#### Возможные ошибки

- `401 Application token is missing` / `Application token is invalid` — проблема с App Token.
- `404 Session not found` — проверьте `session_token`, `client_nonce` и App Token. Если восстановить значения нельзя, начните вход заново.
- `422` — проверьте обязательные поля и их длину.
- `429` — уменьшите частоту polling и повторите запрос после паузы.

`session_token` привязан к проекту и `Application`, но не к IP. Он не заменяет Bearer token.


### Получение Bearer token после callback-звонка

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/counterparty/callback_auth/exchange`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}; Content-Type: application/json`  

Обменивает подтверждённую callback-сессию на Bearer token клиента.

#### Параметры запроса

- `session_token` *(string, обязательно, до 128 символов)* — значение из ответа `callback_auth/init`.
- `client_nonce` *(string, обязательно)* — значение, переданное в `callback_auth/init`.
- `device` *(string, опционально, до 255 символов)* — название устройства или приложения для журнала сессий.

#### Пример запроса

```json
{
    "session_token": "opaque-session-token",
    "client_nonce": "R2xvYmFsTm9uY2VFeGFtcGxlMTIzNDU2Nzg5MA",
    "device": "web"
}
```

#### Ответ

При успешном запросе API вернёт HTTP `200 OK`.

```json
{
    "access_token": "12|plainSanctumToken"
}
```

Сохраните `access_token` целиком, включая разделитель `|`. Следующий запрос выберите по карте интеграции: [профиль клиента](</E-Commerce/Контрагент%20(клиент)/>) или [заказы, оплаты и подписки](/E-Commerce/Заказы/).

#### Возможные ошибки

- `401 Application token is missing` / `Application token is invalid` — проблема с App Token.
- `404 Session not found` — `session_token`, `client_nonce` или App Token не относятся к одной сессии.
- `409 callback_auth_not_verified` — звонок ещё не подтверждён. Вернитесь к проверке статуса.
- `410 callback_auth_expired` — сессия истекла. Начните вход заново.
- `410 callback_auth_exchange_window_closed` — окно повторной выдачи закрыто. Начните вход заново.
- `422` — проверьте обязательные поля и их длину.
- `429` — повторите запрос после паузы. Не используйте повторный `exchange` как способ создать второй активный токен.

Повторный `exchange` предназначен только для восстановления после потерянного ответа. В течение 60 секунд API отзывает предыдущий Bearer и выдаёт новый; после этого возвращает `410`.


## Выход

### Выход контрагента из системы

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/counterparty/logout`  
**Авторизация:** Bearer token клиента  
**Headers:** `Authorization: Bearer {access_token}`  

#### Параметры запроса

- `from_all_devices` *(boolean, обязательно)* — `true`, чтобы удалить все токены клиента; `false`, чтобы удалить только текущий токен.

#### Пример запроса

```json
{
    "from_all_devices": true
}
```

#### Ответ

Для выхода со всех устройств:

```json
{
    "message": "User successfully logout from all devices"
}
```

Для выхода только с текущего устройства:

```json
{
    "message": "User successfully logout"
}
```

#### Возможные ошибки

- `401 Unauthenticated` — Bearer token отсутствует или недействителен.
- `422` — `from_all_devices` отсутствует или не является boolean.

---

## Профиль клиента

Source: https://docs.gigma.ru/E-Commerce/%D0%9A%D0%BE%D0%BD%D1%82%D1%80%D0%B0%D0%B3%D0%B5%D0%BD%D1%82%20(%D0%BA%D0%BB%D0%B8%D0%B5%D0%BD%D1%82)/

# Профиль клиента

В API клиент называется `Counterparty`. Это человек или компания, которые входят в продукт, оформляют заказы и управляют подписками.

Профильные методы работают по Counterparty Bearer. App Token дополнительно нужен только там, где результат относится к конкретному `Application`, например при проверке клиента через платёж.

## Что возвращает профиль

Для физического лица ответ содержит имя, фамилию, отчество, дату рождения и адрес. Для компании вместо этих полей могут возвращаться `name`, `registered_at`, `inn`, `kpp`, `head` и `legal_address`.

Поле `is_verified` относится к текущему `Application`, а не к клиенту вообще. Оно может быть `true`, `false` или `null`, если backend не смог определить контекст приложения.

### Получение текущего клиента

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty`  
**Авторизация:** Bearer token клиента  
**Headers:** `Authorization: Bearer {counterparty_token}`  

#### Запрос

```http
GET /api/counterparty HTTP/1.1
Host: api.gigma.ru
Authorization: Bearer <counterparty_token>
Accept: application/json
```

#### Ответ

Сокращённый ответ для физического лица:

```json
{
    "counterparty": {
        "id": 1,
        "type": {
            "id": 2,
            "name": "Розница"
        },
        "manager": null,
        "avatar": null,
        "first_name": "Алексей",
        "last_name": "Петров",
        "middle_name": null,
        "birthday": null,
        "address": "г Москва, ул Деловая, д 20",
        "phone_1": "79999999990",
        "phone_2": null,
        "email": "client@example.com",
        "created_at": "2026-08-15T10:00:00+00:00",
        "registration_date": "2026-08-15T10:00:00+00:00",
        "updated_at": "2026-08-16T10:00:00+00:00",
        "is_verified": false,
        "favourite_products": []
    }
}
```

#### Описание полей ответа

- `registration_date` — дата регистрации клиента; совпадает с created_at
- `is_verified` — результат проверки клиента для текущего Application: true, false или null, если приложение определить нельзя
- `favourite_products` — краткие карточки избранного клиента.

#### Ошибки

- `401` — Bearer отсутствует, истёк или отозван.


### Обновление профиля

**Метод:** PUT  
**URL:** `https://api.gigma.ru/api/counterparty`  
**Авторизация:** Bearer token клиента  
**Headers:** `Authorization: Bearer {counterparty_token}`  

#### Параметры запроса

Передавайте только изменяемые поля:

- `avatar_id` *(integer|null, опционально)* — ID файла, принадлежащего текущему клиенту; `null` очищает аватар;
- `email` *(email|null, опционально)* — электронная почта;
- `first_name` *(string|null, опционально)* — имя, 2–255 символов;
- `last_name` *(string|null, опционально)* — фамилия, 2–255 символов;
- `address` *(string|null, опционально)* — адрес;
- `phone_2` *(string|null, опционально)* — дополнительный контактный номер, до 20 символов.

Основной номер `phone_1` этим методом не меняется. Для него используется отдельный OTP-flow ниже. Значение `avatar_id: 0` недопустимо: чтобы удалить аватар, передайте `null`.

#### Пример запроса

```json
{
    "first_name": "Алексей",
    "last_name": "Петров",
    "email": "client@example.com",
    "address": "г Москва, ул Деловая, д 20",
    "phone_2": "79990000000"
}
```

#### Ответ

API возвращает HTTP `200` и объект `counterparty` той же формы, что при получении профиля.

#### Ошибки

- `401` — Bearer недействителен;
- `422` — поле не прошло валидацию или `avatar_id` не принадлежит текущему клиенту.


## Смена основного телефона

Смена выполняется в два запроса. Новый номер хранится как незавершённая заявка до подтверждения кода.

### Запрос кода на новый номер

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/counterparty/phone/request_change`  
**Авторизация:** Bearer token клиента  
**Headers:** `Authorization: Bearer {counterparty_token}`  

#### Параметры запроса

- `new_phone_number` *(string, обязательно)* — новый основной номер телефона.

Backend нормализует номер, проверяет, что он отличается от текущего и не занят другим клиентом в том же проекте, затем отправляет четырёхзначный OTP.

#### Пример запроса

```json
{
    "new_phone_number": "+7 999 123-45-67"
}
```

#### Ответ

```json
{
    "message": "Код подтверждения отправлен на указанный номер телефона."
}
```

#### Ошибки

- `401` — Bearer недействителен;
- `422` — номер совпадает с текущим, уже используется или не прошёл валидацию;
- `429` — запрос на смену номера уже выполняется слишком часто;
- `500` — код не удалось отправить.


### Подтверждение нового номера

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/counterparty/phone/verify_change`  
**Авторизация:** Bearer token клиента  
**Headers:** `Authorization: Bearer {counterparty_token}`  

#### Параметры запроса

- `password` *(string, обязательно)* — четырёхзначный OTP.

Повторно передавать телефон не нужно: backend использует номер из незавершённой заявки.

#### Пример запроса

```json
{
    "password": "4821"
}
```

#### Ответ

При успехе API возвращает HTTP `200` и обновлённый объект `counterparty`.

#### Ошибки

- `401` — Bearer недействителен;
- `422` — заявка отсутствует, код неверен или истёк, либо номер успел занять другой клиент;
- `429` — эта проверка уже выполняется или превышен лимит попыток.


## Проверка клиента через СБП

Проверка создаёт платёж на 1 ₽ и подтверждает клиента только для текущего `Application`. Не используйте `is_verified` как универсальный признак оплаты заказа или подписки.

### Создание или получение СБП-проверки

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/counterparty/verifications/sbp-payment`  
**Авторизация:** App Token + Bearer token  
**Headers:** `Token: {application_token}; Authorization: Bearer {counterparty_token}`  

#### Параметры запроса

Тело запроса не требуется.

#### Пример запроса

```http
POST /api/counterparty/verifications/sbp-payment HTTP/1.1
Host: api.gigma.ru
Token: <application_token>
Authorization: Bearer <counterparty_token>
Accept: application/json
```

#### Ответ

```json
{
    "data": {
        "method": "sbp_payment",
        "status": "pending",
        "is_verified": false,
        "payment_link": "https://yoomoney.ru/checkout/...",
        "expires_at": "2026-08-16T11:00:00.000000Z",
        "verified_at": null
    }
}
```

HTTP `201` означает, что создана новая попытка; `200` — что возвращена или синхронизирована существующая.

##### Описание полей ответа

- `data.method` — способ проверки; для этого метода всегда `sbp_payment`.
- `data.status` — состояние проверки: `pending`, `verified`, `failed` или `canceled`.
- `data.is_verified` — `true`, когда проверочный платёж подтверждён.
- `data.payment_link` — ссылка на оплату или `null`, если переход больше не нужен.
- `data.expires_at` — время окончания действия платёжной ссылки в ISO 8601 или `null`.
- `data.verified_at` — время подтверждения клиента в ISO 8601 или `null`.

После оплаты повторите запрос или получите профиль. Доверяйте только `is_verified: true`, подтверждённому backend.

#### Ошибки

- `401` — проверьте оба токена;
- `404` — клиент и `Application` относятся к разным проектам;
- `409` — платёж уже создаётся;
- `429` — превышен лимит 6 запросов в минуту;
- `503` — для приложения не настроен платёжный провайдер или он временно недоступен.


### Удаление аккаунта клиента

**Метод:** DELETE  
**URL:** `https://api.gigma.ru/api/counterparty`  
**Авторизация:** Bearer token клиента  
**Headers:** `Authorization: Bearer {counterparty_token}`  

#### Запрос

```http
DELETE /api/counterparty HTTP/1.1
Host: api.gigma.ru
Authorization: Bearer <counterparty_token>
Accept: application/json
```

#### Ответ

```json
{
    "message": "Counterparty successfully deleted"
}
```

Операция отзывает токены и удаляет персональные данные, сохранённые способы оплаты, контакты, историю поиска и избранное. Учётные заказы сохраняются в обезличенном виде. После успеха локальную сессию клиента необходимо удалить.

---

## Каталог, тарифы и цены

Source: https://docs.gigma.ru/E-Commerce/%D0%A2%D0%BE%D0%B2%D0%B0%D1%80%D1%8B/

# Каталог, тарифы и цены

Этот раздел нужен для двух разных витрин:

- **обычный каталог** — товары или услуги, которые попадают в корзину и обычный заказ;
- **подписочный каталог** — тарифы, которые оформляются через checkout подписки.

Публичный каталог требует App Token. Избранное дополнительно требует Counterparty Bearer, потому что принадлежит конкретному клиенту.

## Как выбрать endpoint подписочного каталога

| Endpoint | Когда использовать |
| --- | --- |
| `subscription-catalog` | основной вариант; ответ сам становится сгруппированным, если в каталоге есть варианты периода |
| `subscription-catalog/grouped` | интерфейс всегда ожидает группы и массив `variants` |
| `subscription-plans` | нужен плоский список с `slug`, числовым `amount` и периодом |

Все три endpoint читают тарифы текущего `Application`. Это разные представления одного каталога, а не независимые наборы тарифов.

### Получение подписочного каталога

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/subscription-catalog`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}`  

#### Ответ

Если в каталоге нет дочерних вариантов, `data` содержит плоские тарифы:

```json
{
    "data": [
        {
            "id": 34780,
            "name": "Базовый",
            "description": "Доступ к сервису",
            "avatar_url": null,
            "price": "490.00",
            "currency": "RUB",
            "billing_period_months": 1
        }
    ]
}
```

Если есть хотя бы один дочерний вариант, весь ответ переводится в групповой формат:

```json
{
    "data": [
        {
            "id": 34780,
            "name": "Базовый",
            "description": "Доступ к сервису",
            "avatar_url": null,
            "price": "490.00",
            "currency": "RUB",
            "billing_period_months": 1,
            "variants": [
                {
                    "id": 34780,
                    "label": "1 месяц",
                    "price": "490.00",
                    "currency": "RUB",
                    "billing_period_months": 1
                },
                {
                    "id": 34786,
                    "label": "3 месяца",
                    "price": "1290.00",
                    "currency": "RUB",
                    "billing_period_months": 3
                }
            ]
        }
    ]
}
```

При включённом управляемом каталоге возвращаются только активные тарифы, назначенные текущему `Application`. Если назначений нет, `data` будет пустым массивом. В режиме совместимости backend может вернуть все подписочные тарифы проекта.

Для оформления передайте ID выбранного тарифа в `POST /api/counterparty/subscriptions/checkout`.

#### Ошибки

- `401` — App Token отсутствует или не распознан;
- `429` — превышен лимит 60 запросов в минуту.


### Получение всегда сгруппированного каталога

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/subscription-catalog/grouped`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}`  

Endpoint всегда возвращает группы с массивом `variants`, даже когда вариант у тарифа один. Поля и правила доступности совпадают с `subscription-catalog`.

#### Ответ

```json
{
    "data": [
        {
            "id": 34780,
            "name": "Базовый",
            "price": "490.00",
            "currency": "RUB",
            "billing_period_months": 1,
            "variants": [
                {
                    "id": 34780,
                    "label": "1 месяц",
                    "price": "490.00",
                    "currency": "RUB",
                    "billing_period_months": 1
                }
            ]
        }
    ]
}
```


### Получение плоских планов подписки

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/subscription-plans`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}`  

#### Ответ

```json
{
    "data": [
        {
            "name": "Базовый",
            "slug": "nomenclature-34780",
            "amount": 490,
            "currency": "RUB",
            "period_months": 1
        }
    ]
}
```

В этом представлении `amount` — число. `slug` номенклатурного тарифа имеет формат `nomenclature-{id}` и может использоваться при создании подписки с сохранённым способом оплаты.


## Обычный каталог

### Получение списка товаров

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/products`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}`  

#### Параметры запроса

- `page` *(integer, опционально)* — номер страницы, по умолчанию `1`;
- `per_page` *(integer, опционально)* — размер страницы, по умолчанию `10`;
- `query` *(string, опционально)* — поиск по названию, 1–255 символов;
- `category_id[]` *(integer[], опционально)* — категории;
- `brand_id[]` *(integer[], опционально)* — бренды;
- `country_id[]` *(integer[], опционально)* — страны;
- `tag_id[]` *(integer[], опционально)* — теги;
- `order_by` *(string, опционально)* — `name_asc`, `name_desc`, `popularity_asc`, `popularity_desc`, `price_asc` или `price_desc`;
- `price_from` *(number, опционально)* — нижняя граница цены, от `0`;
- `price_to` *(number, опционально)* — верхняя граница цены, от `1`.

Параметры `available` и `sale` текущим backend не поддерживаются и не влияют на выборку.

#### Пример запроса

```http
GET /api/counterparty/products?page=1&per_page=20&category_id[]=12&tag_id[]=4&order_by=price_asc HTTP/1.1
Host: api.gigma.ru
Token: <application_token>
Accept: application/json
```

#### Ответ

```json
{
    "products": {
        "current_page": 1,
        "data": [
            {
                "id": 26896,
                "views_count": 23,
                "photo": "https://api.gigma.ru/storage/uploads/product.png",
                "photos": [],
                "name": "Товар",
                "brand": {
                    "id": 99,
                    "name": "Бренд"
                },
                "old_price": "2450.00",
                "price": "1960.00",
                "discount": 20,
                "quantity": 5,
                "unit": null,
                "is_favourite": false,
                "tags": [],
                "parameters": {
                    "wholesale": false,
                    "pieces_per_pack": 1,
                    "quantity_pack": 5
                }
            }
        ],
        "per_page": 20,
        "total": 1,
        "last_page": 1
    }
}
```

`price` — строка с двумя десятичными знаками. `quantity` и `parameters.quantity_pack` рассчитываются из доступного остатка. `is_favourite` имеет смысл после авторизации клиента; для публичного запроса значение обычно `false`.

#### Ошибки

- `401` — проверьте App Token;
- `422` — один из фильтров имеет неверный формат или ссылается на несуществующий ID.


### Получение карточки товара

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/products/{id}`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}`  

Возвращает расширенную карточку: описание, характеристики, фотографии, цену, остаток, теги и параметры упаковки.

#### Пример запроса

```http
GET /api/counterparty/products/26896 HTTP/1.1
Host: api.gigma.ru
Token: <application_token>
Accept: application/json
```

#### Ответ

```json
{
    "product": {
        "id": 26896,
        "name": "Товар",
        "description": "<p>Описание</p>",
        "specification": "<p>Характеристики</p>",
        "price": "1960.00",
        "quantity": 5,
        "photos": [],
        "is_favourite": false,
        "share_link": null,
        "tags": [],
        "parameters": {
            "wholesale": false,
            "pieces_per_pack": 1,
            "quantity_pack": 5
        }
    }
}
```

Backend увеличивает `views_count` не чаще одного раза за 10 минут для одного IP и товара.

#### Ошибки

- `401` — App Token отсутствует или недействителен;
- `404` — товара с таким ID нет.


### Получение диапазона цен

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/prices`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}`  

#### Параметры запроса

Endpoint принимает те же товарные фильтры, что и список товаров; `page` и `per_page` не влияют на результат:

- `query` *(string, опционально)* — поиск по названию, 1–255 символов;
- `category_id[]` *(integer[], опционально)* — категории;
- `brand_id[]` *(integer[], опционально)* — бренды;
- `country_id[]` *(integer[], опционально)* — страны;
- `tag_id[]` *(integer[], опционально)* — теги;
- `order_by` *(string, опционально)* — `name_asc`, `name_desc`, `popularity_asc`, `popularity_desc`, `price_asc` или `price_desc`;
- `price_from` *(number, опционально)* — нижняя граница цены, от `0`;
- `price_to` *(number, опционально)* — верхняя граница цены, от `1`.

#### Ответ

```json
{
    "min_price": 100,
    "max_price": 10000
}
```

Если подходящих товаров нет, обе границы возвращаются как `0`.


## Избранное клиента

Все методы ниже требуют App Token и Counterparty Bearer.

### Получение избранных товаров

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/products/favourites`  
**Авторизация:** App Token + Bearer token  
**Headers:** `Token: {application_token}; Authorization: Bearer {counterparty_token}`  

#### Параметры запроса

- `page` *(integer, опционально)* — номер страницы, по умолчанию `1`;
- `per_page` *(integer, опционально)* — размер страницы, по умолчанию `10`.

#### Ответ

```json
{
    "products": {
        "current_page": 1,
        "data": [
            {
                "id": 26896,
                "name": "Товар",
                "price": "1960.00",
                "is_favourite": true
            }
        ],
        "per_page": 10,
        "total": 1,
        "last_page": 1
    }
}
```

Backend формирует список по избранному текущего клиента и затем вручную применяет пагинацию.


### Получение карточки товара через маршрут избранного

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/products/favourites/{product_id}`  
**Авторизация:** App Token + Bearer token  
**Headers:** `Token: {application_token}; Authorization: Bearer {counterparty_token}`  

Текущий runtime возвращает карточку товара по ID, но **не проверяет**, находится ли товар в избранном текущего клиента. Для обычной карточки используйте `GET /api/counterparty/products/{id}`, а принадлежность избранному определяйте по списку `GET /api/counterparty/products/favourites`.

#### Ответ

```json
{
    "product": {
        "id": 26896,
        "name": "Товар",
        "price": "1960.00",
        "is_favourite": false
    }
}
```

#### Ошибки

- `404` — товара с таким ID нет. Отсутствие товара в избранном само по себе `404` не вызывает.


### Добавление товара в избранное

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/counterparty/products/favourites`  
**Авторизация:** App Token + Bearer token  
**Headers:** `Token: {application_token}; Authorization: Bearer {counterparty_token}`  

#### Параметры запроса

- `product_id` *(integer, обязательно)* — ID существующего товара.

#### Пример запроса

```json
{
    "product_id": 26896
}
```

#### Ответ

```json
{
    "product": {
        "id": 26896,
        "name": "Товар",
        "price": "1960.00",
        "is_favourite": true
    }
}
```

Операция идемпотентна на уровне пары клиент–товар: повторный запрос не создаёт вторую запись и возвращает текущую карточку `product`.


### Удаление товара из избранного

**Метод:** DELETE  
**URL:** `https://api.gigma.ru/api/counterparty/products/favourites/{product_id}`  
**Авторизация:** App Token + Bearer token  
**Headers:** `Token: {application_token}; Authorization: Bearer {counterparty_token}`  

В path передаётся ID товара, а не ID записи избранного.

#### Ответ

```json
{
    "message": "Product successfully deleted from favourites"
}
```

Если товар не находится в избранном текущего клиента, API вернёт `404`.


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

- Для обычной покупки перейдите к [заказам и подпискам](/E-Commerce/Заказы/).
- Для фильтров, доставки, оплаты и магазинов используйте [справочники витрины](/E-Commerce/Справочники/).
- Для работы с избранным сначала подключите [вход клиента](/E-Commerce/Авторизация/).

---

## Заказы и подписки

Source: https://docs.gigma.ru/E-Commerce/%D0%97%D0%B0%D0%BA%D0%B0%D0%B7%D1%8B/

# Заказы и подписки

Gigma поддерживает два разных сценария оплаты:

- **обычный заказ** — клиент один раз покупает товары или услуги;
- **подписка** — клиент оплачивает период доступа, а backend хранит состояние продления.

Не смешивайте их в интерфейсе. У обычного заказа главным объектом остаётся `order`, у подписочного продукта — `subscription`, даже если первый платёж подписки технически создаёт связанный заказ.

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

| Операция | App Token | Counterparty Bearer |
| --- | ---: | ---: |
| Рассчитать корзину | да | нет |
| Создать, получить или показать заказ клиента | да | да |
| Получить тарифы | да | нет |
| Checkout и управление подпиской | да | да |
| Получить и отвязать сохранённый способ оплаты | да | да |

## Обычный заказ: рекомендуемый поток

1. Получите каталог, доставку, оплату и магазины.
2. Рассчитайте корзину через `orders/precalculate`.
3. Авторизуйте клиента.
4. Создайте заказ.
5. Если API вернул `payment_link`, перенаправьте клиента на оплату.
6. После возврата снова запросите заказ и покажите состояние, подтверждённое backend.

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

### Предварительный расчёт корзины

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/counterparty/orders/precalculate`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}`  

#### Тело запроса

- `products` *(array, обязательно)* — позиции корзины;
- `products[].id` *(integer, обязательно)* — ID товара;
- `products[].quantity` *(integer, обязательно)* — количество, от `1`;
- `promo_code` *(string, опционально)* — латинские буквы, цифры и дефис, до 64 символов.

```json
{
    "products": [
        {
            "id": 28504,
            "quantity": 3
        }
    ],
    "promo_code": "WELCOME-10"
}
```

#### Ответ

```json
{
    "price": 1952.4,
    "discount": 195.24,
    "total": 1657.16,
    "quantity_pack": 3,
    "original_price": 1952.4,
    "product_discount_amount": 195.24,
    "promo_discount_amount": 100,
    "total_discount_amount": 295.24,
    "final_price": 1657.16,
    "applied_discount": {
        "id": 7,
        "code": "WELCOME-10",
        "name": "Приветственная скидка",
        "type": "fixed",
        "value": 100
    },
    "discount_error": null,
    "products": [
        {
            "id": 28504,
            "price": 650.8,
            "quantity": 3,
            "pieces_per_pack": 1,
            "quantity_pack": 3,
            "wholesale": false
        }
    ]
}
```

`price`, `discount` и `total` сохранены для совместимости. Для нового интерфейса используйте явные поля `original_price`, `product_discount_amount`, `promo_discount_amount`, `total_discount_amount` и `final_price`.

Неприменимый промокод не ломает расчёт: backend возвращает цены без промо-скидки и объект `discount_error`. Ошибка товара или остатка возвращается как `422`.


### Создание заказа

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/counterparty/orders`  
**Авторизация:** App Token + Bearer token  
**Headers:** `Token: {application_token}; Authorization: Bearer {counterparty_token}`  

#### Тело запроса

- `delivery_type_id` *(integer, обязательно)* — способ доставки;
- `delivery_subtype_id` *(integer, условно обязательно)* — требуется при `delivery_type_id = 2`;
- `delivery_subtype_param_id` *(integer, условно обязательно)* — требуется при `delivery_subtype_id = 1`;
- `shop_id` *(integer, условно обязательно)* — требуется при `delivery_type_id = 1`;
- `address` *(string, условно обязательно)* — требуется при `delivery_subtype_id = 2`;
- `payment_type_id` *(integer, опционально)* — способ оплаты;
- `payment_method_type` *(string, опционально)* — допустимый тип способа онлайн-оплаты;
- `promo_code` *(string, опционально)* — промокод;
- `products` *(array, обязательно)* — позиции корзины;
- `products[].id` *(integer, обязательно)* — ID товара;
- `products[].quantity` *(integer, обязательно)* — количество, от `1`.

Всегда получайте ID доставки, оплаты и магазина из [справочников витрины](/E-Commerce/Справочники/). Не переносите ID из примера в production-конфигурацию.

```json
{
    "delivery_type_id": 2,
    "delivery_subtype_id": 2,
    "payment_type_id": 2,
    "address": "115477, г Москва, ул Деловая, д 20",
    "promo_code": "WELCOME-10",
    "products": [
        {
            "id": 28504,
            "quantity": 3
        }
    ]
}
```

#### Ответ

```json
{
    "order": {
        "id": 169,
        "status": {
            "id": 1,
            "name": "Ожидает оплаты"
        },
        "price": "1657.16",
        "promo_code": "WELCOME-10",
        "original_price": 1952.4,
        "product_discount_amount": 195.24,
        "promo_discount_amount": 100,
        "total_discount_amount": 295.24,
        "final_price": 1657.16,
        "delivery_type": {},
        "delivery_subtype": {},
        "delivery_subtype_param": null,
        "payment_type": {},
        "yookassa_payment_method_type": null,
        "address": "115477, г Москва, ул Деловая, д 20",
        "shop": null,
        "products": [],
        "payment_link": "https://yoomoney.ru/checkout/...",
        "created_at": "2026-08-16T10:00:00+00:00",
        "redeem_token": null,
        "redeemed_count": 0,
        "total_tickets": 0,
        "last_redeemed_at": null
    }
}
```

Для карточной оплаты backend создаёт платёж после фиксации заказа. Если платёж создать не удалось, заказ отменяется и API возвращает `502`. Ошибки цены, промокода, доставки или остатка возвращаются как `422`.


### Получение заказов клиента

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/orders`  
**Авторизация:** App Token + Bearer token  
**Headers:** `Token: {application_token}; Authorization: Bearer {counterparty_token}`  

Возвращает только заказы текущего клиента в текущем `Application`.

#### Ответ

```json
{
    "orders": [
        {
            "id": 169,
            "status": {
                "id": 1,
                "name": "Ожидает оплаты"
            },
            "final_price": 1657.16,
            "payment_link": "https://yoomoney.ru/checkout/...",
            "created_at": "2026-08-16T10:00:00+00:00"
        }
    ],
    "ordersCount": 1
}
```


### Получение одного заказа

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/orders/{id}`  
**Авторизация:** App Token + Bearer token  
**Headers:** `Token: {application_token}; Authorization: Bearer {counterparty_token}`  

Backend проверяет и владельца, и `Application`. Чужой заказ или заказ другого приложения возвращается как `404`, чтобы не раскрывать его существование.

Для билетов и пропусков ответ может содержать `redeem_token`, `redeemed_count`, `total_tickets` и `last_redeemed_at`. Эти поля возвращаются только владельцу заказа.

#### Ответ

```json
{
    "order": {
        "id": 169,
        "status": {
            "id": 1,
            "name": "Ожидает оплаты"
        },
        "final_price": 1657.16,
        "payment_link": "https://yoomoney.ru/checkout/...",
        "redeem_token": null,
        "redeemed_count": 0,
        "total_tickets": 0,
        "last_redeemed_at": null
    }
}
```

#### Ошибки

- `401` — один из токенов отсутствует или недействителен;
- `404` — заказа нет, он принадлежит другому клиенту либо другому `Application`.


## Упрощённый гостевой заказ

### Создание заказа из контактной формы

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/counterparty/contact_form`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}`  

Этот endpoint создаёт клиента и заказ без предварительного входа. Используйте его только для простой контактной формы, а не как основной checkout: runtime фиксирует курьерскую доставку и не поддерживает полный набор условий обычного заказа.

#### Параметры запроса

- `first_name` *(string, обязательно)* — имя клиента;
- `last_name` *(string, обязательно)* — фамилия клиента;
- `middle_name` *(string|null, опционально)* — отчество;
- `phone` *(string, обязательно)* — телефон клиента;
- `address` *(string, обязательно)* — адрес;
- `payment_type_id` *(integer, обязательно)* — способ оплаты;
- `products` *(array, обязательно)* — позиции заказа;
- `products[].id` *(integer, обязательно)* — ID товара;
- `products[].quantity` *(integer, обязательно)* — количество.

#### Пример запроса

```json
{
    "first_name": "Иван",
    "last_name": "Иванов",
    "middle_name": null,
    "phone": "79991234567",
    "address": "г Москва, ул Деловая, д 20",
    "payment_type_id": 2,
    "products": [
        {
            "id": 28504,
            "quantity": 1
        }
    ]
}
```

#### Ответ

API возвращает созданный объект `order` той же формы, что обычное создание заказа.

Запрос ограничен отдельными лимитами по IP и телефону. Для личного кабинета, истории и повторных покупок используйте обычный вход клиента.


## Подписки

### Как подтверждать платный доступ

После checkout клиент может вернуться на ваш сайт раньше, чем платёж будет окончательно обработан. Поэтому доступ выдаётся не по факту возврата и не только по `latest_payment.status`.

Считайте подписку действующей, только когда одновременно:

```text
status == "active"
current_period_end > текущее время
```

При `charging`, `past_due` или `canceled` закрытый доступ не выдаётся. Проверка на frontend нужна для интерфейса; ваш backend обязан повторять её перед защищённым действием.

В управляемом каталоге список ограничен текущим `Application`. В режиме совместимости могут встречаться проектные подписки с `application_id = null`; не трактуйте такую запись как эксклюзивно назначенную текущему приложению.

### Основной поток: checkout первого платежа

### Создание checkout подписки

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/counterparty/subscriptions/checkout`  
**Авторизация:** App Token + Bearer token  
**Headers:** `Token: {application_token}; Authorization: Bearer {counterparty_token}`  

Передайте ровно одно поле: `nomenclature_id` или `nomenclature_ids`.

#### Параметры запроса

- `nomenclature_id` *(integer, условно обязательно)* — один тариф;
- `nomenclature_ids` *(integer[], условно обязательно)* — от 1 до 20 уникальных ID тарифов;
- `autopay_consent` *(boolean, обязательно)* — должно быть `true`;
- `payment_method_type` *(string, опционально)* — допустимый тип оплаты.

#### Пример запроса

```json
{
    "nomenclature_id": 34780,
    "autopay_consent": true
}
```

#### Ответ

Ответ для одного тарифа:

```json
{
    "order_id": 501,
    "nomenclature_id": 34780,
    "amount": "490.00",
    "currency": "RUB",
    "billing_period_months": 1,
    "payment_method_type": "bank_card",
    "payment_link": "https://yoomoney.ru/checkout/..."
}
```

- `201` — создан новый checkout;
- `200` — возвращён уже существующий незавершённый checkout;
- `202` — результат создания платежа ещё уточняется. Не создавайте параллельный checkout: повторите запрос или получите состояние заказа.

Конфликт с другим незавершённым платежом возвращается как `409`. Недоступный тариф, отсутствие платёжного склада или неверные условия — как `422`.


### Получение подписок клиента

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/subscriptions`  
**Авторизация:** App Token + Bearer token  
**Headers:** `Token: {application_token}; Authorization: Bearer {counterparty_token}`  

#### Ответ

```json
{
    "data": [
        {
            "id": 42,
            "application_id": 17,
            "plan_slug": "nomenclature-34780",
            "nomenclature_id": 34780,
            "billing_period_months": 1,
            "amount": "490.00",
            "currency": "RUB",
            "status": "active",
            "current_period_start": "2026-08-15T10:00:00+00:00",
            "current_period_end": "2026-09-15T10:00:00+00:00",
            "next_charge_at": "2026-09-15T10:00:00+00:00",
            "latest_payment": {
                "status": "succeeded"
            },
            "can_retry_payment": false,
            "retry_payment_reason": "already_paid"
        }
    ]
}
```

`next_charge_at` означает «не раньше этого времени»; фактическая попытка выполняется ближайшим запуском планировщика.


### Создание подписки с уже сохранённым способом оплаты

### Создание подписки с немедленным списанием

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/counterparty/subscriptions`  
**Авторизация:** App Token + Bearer token  
**Headers:** `Token: {application_token}; Authorization: Bearer {counterparty_token}`  

Используйте endpoint только когда у клиента уже есть активный `saved_payment_method_id` текущего `Application`.

#### Параметры запроса

- `nomenclature_id` *(integer, условно обязательно)* — ID тарифа;
- `plan_slug` *(string, условно обязательно)* — slug тарифа вместо `nomenclature_id`;
- `saved_payment_method_id` *(integer, обязательно)* — сохранённый способ оплаты;
- `autopay_consent` *(boolean, обязательно)* — должно быть `true`.

#### Пример запроса

```json
{
    "nomenclature_id": 34780,
    "saved_payment_method_id": 9,
    "autopay_consent": true
}
```

#### Ответ

Успешно активированная подписка возвращается как `201`; продолжающееся или требующее проверки списание — как `202`. Ответ содержит объект `data` с подпиской. Окончательная ошибка первого списания возвращается как `422`.


### Управление подпиской

### Изменение тарифа или сохранённого способа оплаты

**Метод:** PATCH  
**URL:** `https://api.gigma.ru/api/counterparty/subscriptions/{id}`  
**Авторизация:** App Token + Bearer token  
**Headers:** `Token: {application_token}; Authorization: Bearer {counterparty_token}`  

#### Параметры запроса

- `nomenclature_id` *(integer, опционально)* — новый тариф;
- `plan_slug` *(string, опционально)* — новый тариф по slug;
- `saved_payment_method_id` *(integer, опционально)* — уже сохранённый способ оплаты;
- `autopay_consent` *(boolean, условно обязательно)* — передайте `true`, если меняются тариф, цена, период или способ оплаты.

#### Пример запроса

```json
{
    "nomenclature_id": 34786,
    "autopay_consent": true
}
```

#### Ответ

API возвращает объект `data` с обновлённой подпиской.

Не используйте этот endpoint для ввода новой карты. Он принимает только уже сохранённый способ оплаты того же платёжного контура.


### Отмена подписки

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/counterparty/subscriptions/{id}/cancel`  
**Авторизация:** App Token + Bearer token  
**Headers:** `Token: {application_token}; Authorization: Bearer {counterparty_token}`  

#### Ответ

Отмена переводит подписку в `canceled`, записывает `canceled_at` и возвращает объект `data` с обновлённой подпиской. Повторная отмена или попытка отменить подписку во время актуального списания возвращается как `422`.


### Возобновление отменённой подписки

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/counterparty/subscriptions/{id}/resume`  
**Авторизация:** App Token + Bearer token  
**Headers:** `Token: {application_token}; Authorization: Bearer {counterparty_token}`  

#### Параметры запроса

- `autopay_consent` *(boolean, обязательно)* — должно быть `true`.

#### Пример запроса

```json
{
    "autopay_consent": true
}
```

#### Ответ

API возвращает объект `data` с возобновлённой подпиской. Если оплаченный период истёк, подписка переходит в `past_due`; иначе — в `active`.

Возобновить можно только ранее активированную отменённую подписку с доступным тарифом и действующим способом оплаты.


### Платежи подписки

### Получение истории платежей

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/subscriptions/{id}/payments`  
**Авторизация:** App Token + Bearer token  
**Headers:** `Token: {application_token}; Authorization: Bearer {counterparty_token}`  

#### Параметры запроса

- `per_page` *(integer, опционально)* — от `1` до `100`, по умолчанию `20`.

#### Ответ

Возвращается стандартная paginated collection платежей только для подписки текущего клиента и `Application`.


### Повтор последней неуспешной оплаты

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/counterparty/subscriptions/{id}/payments/{payment_id}/retry`  
**Авторизация:** App Token + Bearer token  
**Headers:** `Token: {application_token}; Authorization: Bearer {counterparty_token}`  

#### Ответ

Повторить можно только последнюю финализированную неуспешную попытку, если условия подписки не изменились и предыдущий результат не требует сверки. Перед показом кнопки используйте `can_retry_payment` и `retry_payment_reason` из подписки.

`409` означает, что платёж ещё обрабатывается или требует reconciliation; `422` — попытка не подходит для повтора.


### Сохранённые способы оплаты

### Получение способов оплаты клиента

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/payment-methods`  
**Авторизация:** App Token + Bearer token  
**Headers:** `Token: {application_token}; Authorization: Bearer {counterparty_token}`  

#### Ответ

```json
{
    "data": [
        {
            "id": 9,
            "payment_method_type": "bank_card",
            "card_type": "Visa",
            "card_last_4": "4242",
            "title": "Visa •••• 4242",
            "is_active": true,
            "created_at": "2026-08-15T10:00:00+00:00"
        }
    ]
}
```

API возвращает только безопасное представление карты. Полный номер и CVC не сохраняются в этом контракте.


### Отвязка сохранённого способа оплаты

**Метод:** DELETE  
**URL:** `https://api.gigma.ru/api/counterparty/payment-methods/{id}`  
**Авторизация:** App Token + Bearer token  
**Headers:** `Token: {application_token}; Authorization: Bearer {counterparty_token}`  

#### Ответ

```json
{
    "message": "Способ оплаты отвязан"
}
```

Backend деактивирует способ оплаты только в контексте текущего клиента и `Application`. Если он нужен действующей подписке, операция может быть отклонена.


### Начало безопасной смены карты подписки

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/counterparty/subscriptions/{id}/payment-method-change`  
**Авторизация:** App Token + Bearer token  
**Headers:** `Token: {application_token}; Authorization: Bearer {counterparty_token}`  

#### Параметры запроса

- `autopay_consent` *(boolean, обязательно)* — должно быть `true`.

Не передавайте `card`, `card_number`, `cvc`, `payment_method_data` или собственный `return_url`: validation специально запрещает эти поля.

#### Пример запроса

```json
{
    "autopay_consent": true
}
```

#### Ответ

Backend создаёт provider-flow и возвращает его состояние:

```json
{
    "id": 31,
    "subscription_id": 42,
    "status": "pending",
    "confirmation_url": "https://yoomoney.ru/confirmation/...",
    "saved_payment_method_id": null,
    "expires_at": "2026-08-16T11:00:00+00:00"
}
```

Откройте `confirmation_url`, затем синхронизируйте попытку.


### Синхронизация смены карты

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/counterparty/subscriptions/{id}/payment-method-changes/{change_id}/sync`  
**Авторизация:** App Token + Bearer token  
**Headers:** `Token: {application_token}; Authorization: Bearer {counterparty_token}`  

#### Ответ

Возвращает тот же объект попытки. Завершённый статус содержит `saved_payment_method_id`; для незавершённого `confirmation_url` может оставаться доступным.


## Что делать после оплаты

- Обычный заказ: повторно получите `GET /orders/{id}` и покажите backend-статус.
- Подписка: повторно получите `GET /subscriptions` и проверьте `active` + `current_period_end`.
- Закрытый сервис: выполняйте проверку на собственном backend; начните с [backend-интеграции](</E-Commerce/Интеграция%20через%20backend/>).

---

## Контентные блоки

Source: https://docs.gigma.ru/E-Commerce/%D0%94%D0%B8%D0%BD%D0%B0%D0%BC%D0%B8%D1%87%D0%B5%D1%81%D0%BA%D0%B8%D0%B9%20%D0%BA%D0%BE%D0%BD%D1%82%D0%B5%D0%BD%D1%82/

# Контентные блоки

Блоки позволяют менять отдельные части интерфейса без выпуска новой версии frontend: баннер, текст, изображение, ссылку или группу дочерних элементов.

Каждый запрос ограничен текущим `Application`. Для интеграции предпочтителен человекочитаемый `identifier`: он стабильнее внутреннего числового `code` и понятнее в коде продукта.

### Получение блока по code

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/blocks/{code}`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}`  

#### Пример запроса

```http
GET /api/counterparty/blocks/9 HTTP/1.1
Host: api.gigma.ru
Token: <application_token>
Accept: application/json
```

#### Ответ

```json
{
    "block": {
        "id": 42,
        "code": 9,
        "identifier": "home-hero",
        "name": "Главный баннер",
        "avatar": null,
        "block_type": {
            "id": 3,
            "name": "Картинка"
        },
        "link": "/catalog",
        "file": null,
        "text": "Новая коллекция",
        "parent": null,
        "children": [],
        "created_at": "2026-08-15T10:00:00+00:00"
    }
}
```

#### Ошибки

- `401` — App Token отсутствует или недействителен;
- `404` — блок с таким `code` не найден в текущем `Application`.


### Получение блока по identifier

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/blocks/id/{identifier}`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}`  

#### Пример запроса

```http
GET /api/counterparty/blocks/id/home-hero HTTP/1.1
Host: api.gigma.ru
Token: <application_token>
Accept: application/json
```

#### Ответ

```json
{
    "block": {
        "id": 42,
        "code": 9,
        "identifier": "home-hero",
        "name": "Главный баннер",
        "avatar": null,
        "block_type": {
            "id": 3,
            "name": "Картинка"
        },
        "link": "/catalog",
        "file": null,
        "text": "Новая коллекция",
        "parent": null,
        "children": [],
        "created_at": "2026-08-15T10:00:00+00:00"
    }
}
```

#### Ошибки

- `401` — App Token отсутствует или недействителен;
- `404` — блок с таким `identifier` не найден в текущем `Application`.


## Как читать ответ

- `avatar` и `file` — объекты загруженных файлов или `null`;
- `block_type` определяет назначение блока;
- `parent` содержит краткую ссылку на родителя;
- `children` содержит вложенные блоки текущего элемента;
- `link` и `text` могут быть `null`.

Не используйте `id` или `code` блока одного приложения в другом: одинаковые значения не означают одинаковый контент.

---

## Страницы и публикации

Source: https://docs.gigma.ru/E-Commerce/%D0%A1%D1%82%D1%80%D0%B0%D0%BD%D0%B8%D1%86%D1%8B/

# Страницы и публикации

Страницы подходят для новостей, статей, справочных материалов и других публикаций, которые должны обновляться без релиза frontend. Ответ содержит HTML в поле `content`; перед выводом применяйте правила безопасного рендеринга вашего приложения.

Все страницы списка ограничены текущим `Application`.

### Получение типов страниц

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/page_types`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}`  

#### Ответ

```json
{
    "items": [
        {
            "id": 1,
            "name": "Страница",
            "photo": null,
            "created_at": "2026-08-15T10:00:00+00:00"
        }
    ],
    "itemsCount": 1
}
```

Используйте `id` из этого ответа как `page_type_id`. Не фиксируйте справочные ID по примеру.


### Получение списка страниц

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/pages`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}`  

#### Параметры запроса

- `page_type_id` *(integer, опционально)* — тип страницы;
- `query` *(string, опционально)* — поиск по заголовку, описанию и HTML-содержимому, от 3 символов;
- `order_by` *(string, опционально)* — `date_asc`, `date_desc`, `popularity_asc` или `popularity_desc`;
- `page` *(integer, опционально)* — номер страницы, по умолчанию `1`;
- `per_page` *(integer, опционально)* — размер страницы, по умолчанию `10`.

Параметр `application_id` проходит validation, но текущий controller его не использует: контекст всегда определяется App Token.

#### Пример запроса

```http
GET /api/counterparty/pages?page_type_id=3&query=интеграция&order_by=date_desc&page=1&per_page=10 HTTP/1.1
Host: api.gigma.ru
Token: <application_token>
Accept: application/json
```

#### Ответ

```json
{
    "pages": {
        "current_page": 1,
        "data": [
            {
                "id": 101,
                "slug": "integration-guide",
                "title": "Как подключить сервис",
                "description": "Краткое описание",
                "preview": null,
                "content": "<p>Содержимое страницы</p>",
                "views_count": 12,
                "author": null,
                "tags": [],
                "created_at": "2026-08-15T10:00:00+00:00"
            }
        ],
        "per_page": 10,
        "total": 1,
        "last_page": 1
    }
}
```


### Получение страницы по slug

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/pages/{slug}`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}`  

#### Пример запроса

```http
GET /api/counterparty/pages/integration-guide HTTP/1.1
Host: api.gigma.ru
Token: <application_token>
Accept: application/json
```

#### Ответ

```json
{
    "page": {
        "id": 101,
        "slug": "integration-guide",
        "title": "Как подключить сервис",
        "description": "Краткое описание",
        "preview": null,
        "content": "<p>Содержимое страницы</p>",
        "views_count": 13,
        "author": null,
        "tags": [],
        "created_at": "2026-08-15T10:00:00+00:00"
    }
}
```

Backend увеличивает `views_count` не чаще одного раза за 10 минут для одного IP и страницы.

> Текущее ограничение runtime: при неизвестном `slug` controller может вернуть резервную страницу вместо `404`. До исправления backend сравнивайте `page.slug` с запрошенным значением и не показывайте резервный контент как найденную публикацию.

---

## Меню и навигация

Source: https://docs.gigma.ru/E-Commerce/%D0%9D%D0%B0%D0%B2%D0%B8%D0%B3%D0%B0%D1%86%D0%B8%D0%BE%D0%BD%D0%BD%D0%B0%D1%8F%20%D0%BF%D0%B0%D0%BD%D0%B5%D0%BB%D1%8C/

# Меню и навигация

Меню хранит управляемую структуру навигации: подпись, иконку, изображение, путь и дочерние пункты. Frontend сам решает, как отрисовать эту структуру и какие внутренние маршруты считать допустимыми.

## Меню, привязанное к Application

### Получение меню по slug

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/menus/{slug?}`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}`  

`slug` опционален. Если его не передать, backend ищет меню со slug `navpanel`.

#### Пример запроса

```http
GET /api/counterparty/menus/navpanel HTTP/1.1
Host: api.gigma.ru
Token: <application_token>
Accept: application/json
```

#### Ответ

```json
{
    "menuItems": {
        "code": 1,
        "avatar": "https://api.gigma.ru/storage/uploads/default.svg",
        "preview": "https://api.gigma.ru/storage/uploads/default.svg",
        "name": "Главное меню",
        "url": "/catalog",
        "children": [
            {
                "code": 2,
                "avatar": "https://api.gigma.ru/storage/uploads/default.svg",
                "preview": "https://api.gigma.ru/storage/uploads/default.svg",
                "name": "Каталог",
                "url": "/catalog",
                "children": []
            }
        ]
    }
}
```

`url` формируется из поля `slug` пункта меню. `avatar` и `preview` получают URL изображения-заглушки, если собственный файл не задан.

#### Ошибки

- `401` — App Token отсутствует или недействителен;
- `404` — меню с таким slug не найдено в текущем `Application`.


## Проектное меню по имени

### Получение пунктов проектного меню

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/menus/{name}/items`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}`  

Этот endpoint использует другую модель меню: ищет меню по точному `name` внутри проекта текущего `Application` и возвращает его корневые пункты.

#### Ответ

```json
{
    "menuItems": [],
    "menuItemsCount": 0
}
```

#### Ошибки

- `401` — App Token отсутствует или недействителен;
- `404` — проектное меню с таким точным именем не найдено.

Используйте один вариант меню последовательно. Не считайте `slug` application-меню и `name` проектного меню взаимозаменяемыми.


## Безопасный рендеринг

- сопоставляйте `url` с разрешёнными маршрутами frontend;
- не выполняйте значения как JavaScript;
- сохраняйте возможность показать базовую навигацию, если API вернул `404` или временно недоступен;
- не кэшируйте меню одного App Token как общее для других приложений.

---

## Настройки и поиск

Source: https://docs.gigma.ru/E-Commerce/%D0%92%D1%81%D0%BF%D0%BE%D0%BC%D0%BE%D0%B3%D0%B0%D1%82%D0%B5%D0%BB%D1%8C%D0%BD%D1%8B%D0%B5%20%D0%B7%D0%B0%D0%BF%D1%80%D0%BE%D1%81%D1%8B/

# Настройки и поиск

Эти методы дополняют основной каталог. Не используйте их как источник истины для оплаты, доступа или состояния заказа.

### Получение настроек витрины

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/settings`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}`  

#### Ответ

```json
{
    "wholesale": false
}
```

`wholesale` показывает, включён ли оптовый режим текущего `Application`. Это также удобный минимальный запрос для проверки App Token.


### Получение тегов товаров

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/tags`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}`  

#### Ответ

```json
{
    "tags": [
        {
            "id": 1,
            "name": "Новинка",
            "photo": null,
            "created_at": "2026-08-15T10:00:00+00:00"
        }
    ],
    "tagsCount": 1
}
```

ID можно передать как `tag_id[]` в [список товаров](/E-Commerce/Товары/#products-list).

> Текущее ограничение runtime: controller возвращает общий список тегов и не фильтрует его по `Application`. Не показывайте тег как доступный фильтр, пока не убедились, что он встречается в товарах текущей витрины.


### Получение истории поиска клиента

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/search/history`  
**Авторизация:** App Token + Bearer token  
**Headers:** `Token: {application_token}; Authorization: Bearer {counterparty_token}`  

#### Ответ

```json
{
    "searchRequests": [
        {
            "id": 1,
            "value": "тональный крем",
            "created_at": "2026-08-15T10:00:00+00:00"
        }
    ],
    "searchRequestsCount": 1
}
```

Backend возвращает записи текущего авторизованного клиента в обратном порядке создания. Пагинации и фильтров у метода нет.


## Популярные запросы: текущий маршрут не использовать

### Текущее поведение маршрута популярных запросов

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/search/popular`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}`  

Маршрут существует, но фактически вызывает ту же персональную выборку, что и история поиска. Bearer на route не авторизуется, поэтому текущий runtime обычно возвращает пустой список вместо агрегированных популярных запросов.

#### Ответ

```json
{
    "searchRequests": [],
    "searchRequestsCount": 0
}
```

Не стройте продуктовый интерфейс на этом endpoint. Для популярных запросов требуется отдельный агрегирующий backend-контракт с обязательной областью проекта или приложения; расхождение зафиксировано в сопровождающем аудите документации.

---

## Уведомления клиента

Source: https://docs.gigma.ru/E-Commerce/%D0%A3%D0%B2%D0%B5%D0%B4%D0%BE%D0%BC%D0%BB%D0%B5%D0%BD%D0%B8%D1%8F/

# Уведомления клиента

Метод возвращает уведомления текущего клиента в текущем `Application`. Передавайте App Token приложения и Bearer token клиента вместе.

### Получение списка уведомлений

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/notifications`  
**Авторизация:** App Token + Bearer token  
**Headers:** `Token: {application_token}; Authorization: Bearer {counterparty_token}`  

#### Параметры запроса

- `page` *(integer, опционально)* — номер страницы, начиная с 1.
- `per_page` *(integer, опционально)* — количество уведомлений на странице. По умолчанию 10, максимум 50.

#### Пример запроса

```http
GET /api/counterparty/notifications?page=1&per_page=10 HTTP/1.1
Host: api.gigma.ru
Token: <application_token>
Authorization: Bearer <counterparty_token>
Accept: application/json
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "notifications": [
        {
            "id": 1,
            "icon": null,
            "title": "Не удалось продлить подписку",
            "status": "subscription.charge_failed",
            "body": "Проверьте способ оплаты и повторите платёж.",
            "action_url": "/account/subscriptions/42",
            "created_at": "2026-07-30T03:15:00+00:00"
        }
    ],
    "pagination": {
        "total": 1,
        "per_page": 10,
        "current_page": 1,
        "last_page": 1,
        "from": 1,
        "to": 1
    }
}
```

##### Описание полей ответа

- `notifications.id` — идентификатор уведомления.
- `notifications.icon` — иконка уведомления. Сейчас возвращается `null`.
- `notifications.title` — заголовок уведомления.
- `notifications.status` — код события, например `subscription.charge_failed`.
- `notifications.body` — текст уведомления или `null`.
- `notifications.action_url` — ссылка на связанное действие или `null`.
- `notifications.created_at` — время создания в ISO 8601.
- `pagination` — данные текущей страницы.

Если уведомлений нет, API вернёт пустой массив `notifications` и объект `pagination` с нулевым `total`.

#### Возможные ошибки

- `401` — проверьте App Token и Bearer token.
- `404` — проверьте проект; для application-scoped Bearer также проверьте `Application`.
- `429` — превышен лимит 60 запросов в минуту. Повторите запрос после паузы.

---

## Справочники витрины

Source: https://docs.gigma.ru/E-Commerce/%D0%A1%D0%BF%D1%80%D0%B0%D0%B2%D0%BE%D1%87%D0%BD%D0%B8%D0%BA%D0%B8/

# Справочники витрины

Справочники дают frontend допустимые ID для фильтров и checkout. Получайте их из API и не переносите значения из примеров в production-код.

## Какая область данных у метода

| Данные | Фактическая область |
| --- | --- |
| Категории и бренды | текущий `Application` |
| Слайды | текущий `Application` |
| Магазины | весь проект текущего `Application` |
| Страны, доставка и оплата | общие системные справочники |
| Теги | общий список runtime, не отфильтрованный по приложению |

Диапазон цен описан вместе с [каталогом](/E-Commerce/Товары/#prices), потому что принимает те же товарные фильтры.

## Фильтры каталога

### Получение категорий

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/categories`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}`  

#### Параметры запроса

- `limit` *(integer, опционально)* — ограничение числа элементов, от `1`;
- `parent_id` *(integer, опционально)* — получить дочерние категории указанного узла.

Без `parent_id` backend возвращает корневые категории текущего `Application`.

#### Ответ

```json
{
    "categories": [
        {
            "id": 12,
            "name": "Аксессуары",
            "photo": "https://api.gigma.ru/storage/uploads/category.jpg",
            "parent": null
        }
    ],
    "categoriesCount": 1
}
```


### Получение брендов

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/brands`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}`  

#### Параметры запроса

- `limit` *(integer, опционально)* — ограничение числа элементов, от `1`.

Бренды текущего `Application` возвращаются по убыванию приоритета.

#### Ответ

```json
{
    "brands": [
        {
            "id": 99,
            "name": "Бренд",
            "photo": null,
            "created_at": "2026-08-15T10:00:00+00:00"
        }
    ],
    "brandsCount": 1
}
```


### Получение стран

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/countries`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}`  

#### Ответ

```json
{
    "countries": [
        {
            "id": 1,
            "name": "Россия",
            "photo": null,
            "created_at": "2026-08-15T10:00:00+00:00"
        }
    ],
    "countriesCount": 1
}
```

Страны — системный справочник. Наличие страны в ответе не означает, что в текущей витрине есть товары с таким значением.


## Доставка и оплата обычного заказа

Получайте цепочку в таком порядке:

```text
delivery_types
  └─ delivery subtype
       └─ subtype params

payment_types
shops — при самовывозе
search_address — при вводе адреса
```

### Получение способов доставки

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/delivery_types`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}`  

#### Ответ

```json
{
    "deliveryTypes": [
        {
            "id": 1,
            "name": "Самовывоз",
            "price": "0.00",
            "is_active": 1
        },
        {
            "id": 2,
            "name": "Доставка",
            "price": "300.00",
            "is_active": 1
        }
    ],
    "deliveryTypesCount": 2
}
```

Показывайте клиенту только элементы с активным состоянием. Точный ID самовывоза или доставки получайте из ответа и конфигурации проекта, а не определяйте по названию примера.


### Получение одного способа доставки

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/delivery_types/{type_id}`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}`  

#### Ответ

```json
{
    "deliveryType": {
        "id": 2,
        "name": "Доставка",
        "price": "300.00",
        "is_active": 1
    }
}
```


### Получение подтипов доставки

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/delivery_types/{type_id}/subtypes`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}`  

#### Ответ

```json
{
    "deliverySubtypes": [
        {
            "id": 2,
            "name": "Курьер",
            "price": "1000.00",
            "is_active": 1
        }
    ],
    "deliverySubtypesCount": 1
}
```


### Получение одного подтипа доставки

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/delivery_types/{type_id}/subtypes/{subtype_id}`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}`  

#### Ответ

```json
{
    "deliverySubtype": {
        "id": 2,
        "name": "Курьер",
        "price": "1000.00",
        "is_active": 1
    }
}
```

> Текущее ограничение runtime: controller не проверяет, что `subtype_id` действительно относится к `type_id` из path. Используйте ID только из списка подтипов выбранного способа доставки.


### Получение параметров подтипа

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/delivery_types/{type_id}/subtypes/{subtype_id}/params`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}`  

Параметры представляют дополнительные варианты подтипа, например конкретные пункты выдачи.

#### Ответ

```json
{
    "deliverySubtypeParams": [
        {
            "id": 7,
            "name": "г Москва, ул Деловая, д 20"
        }
    ],
    "deliverySubtypeParamsCount": 1
}
```

> Текущее ограничение runtime: `type_id` не сверяется с родителем `subtype_id`. Получайте подтип через предыдущий endpoint и не подставляйте несвязанные ID.


### Получение способов оплаты

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/payment_types`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}`  

#### Ответ

```json
{
    "paymentTypes": [
        {
            "id": 2,
            "photo": null,
            "name": "Онлайн",
            "description": "Оплата через платёжный сервис"
        }
    ],
    "paymentTypesCount": 1
}
```

Этот справочник выбирает тип оплаты обычного заказа. Сохранённые карты подписки получайте через `GET /api/counterparty/payment-methods`.


### Получение магазинов и пунктов самовывоза

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/shops`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}`  

#### Ответ

```json
{
    "shops": [
        {
            "id": 4,
            "photo": null,
            "name": "Центральный",
            "address": "г Москва, ул Деловая, д 20",
            "phone": "+79991234567",
            "schedule": "Пн–Пт, 10:00–18:00"
        }
    ],
    "shopsCount": 1
}
```

Список ограничен проектом, но не отдельным `Application`. Показывайте только магазины, которые бизнес разрешил для данного продукта.


### Текущее поведение маршрута карточки магазина

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/shops/{id}`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}`  

Этот route **не является карточкой магазина**. Route model binding проверяет существование переданного shop ID, но controller игнорирует выбранный объект и возвращает первую глобальную страницу со slug `shops-info`.

#### Ответ

```json
{
    "page": {
        "id": 103,
        "slug": "shops-info",
        "title": "Информация о магазинах",
        "content": "<p>Справочная информация</p>"
    }
}
```

Не используйте endpoint для получения адреса или проверки принадлежности магазина проекту. До исправления backend берите карточки только из `GET /api/counterparty/shops`.


### Поиск адреса

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/counterparty/search_address`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}`  

#### Параметры запроса

- `query` *(string, обязательно)* — поисковая строка от 3 до 1024 символов.

#### Пример запроса

```json
{
    "query": "Деловая 20, Москва"
}
```

#### Ответ

```json
{
    "addresses": [
        {
            "name": "г Москва, ул Деловая, д 20",
            "value": "115477, г Москва, ул Деловая, д 20"
        }
    ],
    "addressesCount": 1
}
```

Сохраняйте в заказе выбранное полное значение `value`, а `name` используйте как краткую подпись.


## Контент витрины

### Получение рекламных слайдов

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/slides`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}`  

Слайды ограничены текущим `Application`.

#### Ответ

```json
{
    "slides": [
        {
            "id": 1,
            "photo": "https://api.gigma.ru/storage/uploads/slide.jpg",
            "name": "Новая коллекция",
            "description": "Скидка на выбранные товары",
            "link": "/catalog"
        }
    ],
    "slidesCount": 1
}
```

Проверяйте `link` по allowlist маршрутов frontend перед переходом.


## Объединённая загрузка

### Получение нескольких справочников одним запросом

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty/dictionaries`  
**Авторизация:** App Token  
**Headers:** `Token: {application_token}`  

#### Параметры запроса

- `include` *(string, опционально)* — список через запятую: `categories`, `brands`, `countries`, `tags`, `popular_requests`.

Без `include` backend возвращает все пять наборов. Неизвестные значения игнорируются.

#### Пример запроса

```http
GET /api/counterparty/dictionaries?include=categories,brands,countries HTTP/1.1
Host: api.gigma.ru
Token: <application_token>
Accept: application/json
```

#### Ответ

```json
{
    "dictionaries": {
        "categories": [],
        "brands": [],
        "countries": []
    }
}
```

- `categories` и `brands` ограничены текущим `Application`;
- `countries` — системный справочник;
- `tags` сейчас не ограничены приложением;
- `popular_requests` агрегируются без фильтра по проекту или приложению и не должны использоваться в tenant-facing интерфейсе до исправления backend.

Запрашивайте только нужные наборы: endpoint не кэширует область данных за вас.


## Как использовать при создании заказа

1. Получите актуальные способы доставки и оплаты.
2. Для самовывоза выберите `shop_id` из списка магазинов.
3. Для доставки выберите подтип и, если требуется, `delivery_subtype_param_id` либо адрес из Dadata.
4. Передайте выбранные ID в [создание заказа](/E-Commerce/Заказы/#create-order).
5. Обработайте `422`: справочник или доступность товара могли измениться после отображения checkout.


# Платформа

---

## Обзор платформы

Source: https://docs.gigma.ru/ERP/

# API управления бизнесом

Раздел «Платформа» описывает административный API Gigma. Через него сотрудники, внутренние сервисы и MCP-агенты управляют бизнесом: настраивают приложения, ведут каталог и остатки, работают с клиентами и заказами, публикуют контент и получают операционные справочники.

Клиентский интерфейс сайта или приложения использует другой контур — [«Сайты и приложения»](/E-Commerce/). Не передавайте Bearer сотрудника или агента в браузерную витрину и не заменяйте им App Token или Counterparty Bearer. App Token в прямой frontend-интеграции виден пользователю и сам по себе не подтверждает личность клиента, оплату или право доступа.

## Что можно автоматизировать

- доступ сотрудников и MCP-агентов, роли и проектные ограничения;
- бизнесы, реквизиты, приложения и webhooks;
- товары, услуги, категории, бренды и подписочные тарифы;
- склады, остатки, импорт, резервы и точки выдачи;
- стратегии продаж, акции, скидки и промокоды;
- клиентов, заказы, возвраты и задачи команды;
- страницы, контентные блоки, меню и файлы.

## Кто обращается к API

| Потребитель | Авторизация | Для чего используется |
| --- | --- | --- |
| Административный интерфейс | Bearer сотрудника | ежедневная работа с каталогом, заказами, клиентами и настройками |
| Внутренний backend | Bearer отдельной технической учётной записи | автоматизация операций внутри одного проекта |
| MCP-агент | отдельный Agent Token | выполнение разрешённых действий внутри проекта без парольного входа |
| Сайт или мобильное приложение клиента | App Token; Counterparty Bearer — после входа для персональных методов | клиентский вход, каталог, покупки и подписки; это другой API-контур |

Большинство методов платформы требуют заголовок:

```http
Authorization: Bearer <access_token>
```

Для сотрудника это токен после обычного входа. Для MCP-агента — отдельный токен, выданный через согласование владельца или административный API. Точные права, обязательные заголовки и ограничения смотрите в карточке конкретного endpoint.

## Основная модель

| Сущность | Роль в продукте |
| --- | --- |
| `Project` | граница данных, пользователей и прав одного владельца |
| `User` | сотрудник, оператор или менеджер внутри проекта |
| `Agent` | специальная техническая учётная запись проекта с отдельными токенами и permissions |
| `Branch` | бизнес, юридическое лицо, филиал или операционное направление |
| `Application` | сайт, приложение или сервис, через который бизнес работает с клиентами |
| `Counterparty` | клиент или компания, с которыми работает бизнес |
| `Nomenclature` | товар, услуга или подписочный тариф |
| `Warehouse` | место хранения и источник доступных остатков |
| `Inventory` | количество, цена и параметры позиции на конкретном складе |
| `Reservation` | временно заблокированное количество товара под заказ или клиента |
| `Order` | разовая операция продажи и её состояние |
| `Task` | внутренняя работа сотрудника, часто связанная с заказом или клиентом |

`Project` задаёт границу доступа. Наличие числового `id` не подтверждает право на объект: backend и интеграция должны проверять, что пользователь или агент и ресурс относятся к одному проекту.

## С чего начать

### Подключить сотрудника

1. Создайте сотрудника в нужном проекте и выдайте минимально необходимые права.
2. Запросите одноразовый пароль через `POST /api/send_password`.
3. Выполните вход через `POST /api/login` и сохраните Bearer как секрет.
4. Получите `GET /api/user`, чтобы проверить текущего пользователя, роль и permissions.

Подробный контракт находится на странице [«Доступ сотрудников»](/ERP/Авторизация/).

### Подключить MCP-агента

Парольный вход агенту запрещён: `/api/send_password` и `/api/login` возвращают `403` для учётных записей с `is_agent = true`.

Используйте один из двух flow:

1. MCP-клиент создаёт `POST /api/agent-access-requests`, владелец подтверждает запрос, клиент проверяет статус и один раз забирает Agent Token через `consume`.
2. Сотрудник с правами управления агентами создаёт `POST /api/agents`, затем выпускает токен через `POST /api/agents/{agent}/tokens`.

После выдачи токена внешний MCP-сервер выполняет обычные ERP endpoints — например, `/api/orders`, `/api/counterparties` и `/api/nomenclatures`. Отдельного `/api/mcp/*` в backend нет. Проверку подключения и рабочие allowlist-профили смотрите в разделе [«MCP: рабочие методы»](/ERP/МСП/), самостоятельное согласование — в [«Получении доступа»](/ERP/МСП/Получение доступа/), а ручное создание и ротацию токенов — в [«Управлении агентами»](/ERP/МСП/Управление агентами/).

### Запустить сайт, приложение или новый канал

1. Создайте или выберите [бизнес и реквизиты](/ERP/Бизнесы/).
2. Создайте [Application и настройте webhooks](/ERP/Приложения/).
3. Подготовьте [каталог товаров и услуг](/ERP/Номенклатура/).
4. Настройте [склады](/ERP/Склады/) и [остатки](/ERP/Остатки/).
5. При необходимости добавьте [стратегии продаж](</ERP/Стратегии%20продаж/>), [акции и скидки](/ERP/Промоакции/) и [магазины](/ERP/Магазины/).
6. Для клиентского интерфейса перейдите в раздел [«Сайты и приложения»](/E-Commerce/).

### Автоматизировать работу с заказами

1. Получите или создайте [клиента или контрагента](/ERP/Контрагенты/).
2. Создайте либо найдите [заказ](/ERP/Заказы/).
3. Проверьте доступность товара по [остаткам](/ERP/Остатки/) и существующим [резервам](/ERP/Резервирование/).
4. Назначьте [задачу сотруднику](/ERP/Задачи/), если заказ требует ручного действия.
5. После неизвестного результата записи сначала повторно прочитайте состояние, а не создавайте вторую операцию вслепую.

### Управлять контентом продукта

Используйте [контентные блоки](/ERP/Блоки/) для отдельных элементов интерфейса, [страницы и публикации](/ERP/Страницы/) для материалов по slug, [меню сотрудников](/ERP/Меню/) для административной навигации и [файлы](/ERP/Файлы/) для загрузки медиа и документов.

Меню сотрудников из платформенного API и клиентское меню из раздела «Сайты и приложения» — разные модели. Не смешивайте их в одной интеграции.

## Ресурсный и табличный ответы

Для части сущностей Gigma предоставляет две поверхности:

| Поверхность | Когда использовать |
| --- | --- |
| `/api/<resource>` | доменные операции, интеграции и получение обычных JSON-объектов |
| `/api/tables/<resource>` | административные таблицы с описанием колонок, фильтрами и пагинацией |

Табличный ответ может содержать UI-обёртки вида `{ icon, value, link }` и не обязан совпадать с ресурсным ответом. Для серверной интеграции выбирайте ресурсный endpoint, если он поддерживает нужный сценарий; табличный используйте, когда действительно нужны колонки и представление административного интерфейса.

Навигация называет пользовательскую задачу, поэтому пункт «Доступ сотрудников» ведёт на каноническую страницу ресурса «Авторизация», а «Каталог товаров и услуг» — на страницу «Номенклатура». Заголовок подробной страницы и карточка endpoint остаются источником истины для конкретного HTTP-контракта. Обзор `/ERP/` объясняет порядок работы, но не дублирует и не переопределяет endpoint.

## Карта документации

| Задача | Разделы |
| --- | --- |
| Вход, текущий пользователь и выход | [Доступ сотрудников](/ERP/Авторизация/) |
| Рабочие MCP methods, получение доступа и управление agent accounts | [MCP: рабочие методы](/ERP/МСП/), [получение доступа](/ERP/МСП/Получение доступа/), [управление агентами](/ERP/МСП/Управление агентами/) |
| Сотрудники, менеджеры и ответственные | [Сотрудники и менеджеры](/ERP/Пользователи/) |
| Юридические лица, реквизиты и банковские интеграции | [Бизнесы и реквизиты](/ERP/Бизнесы/) |
| Каналы, настройки, App Token и webhooks | [Приложения и webhooks](/ERP/Приложения/) |
| Ассортимент, склады и доступное количество | [Каталог](/ERP/Номенклатура/), [склады](/ERP/Склады/), [остатки](/ERP/Остатки/), [резервы](/ERP/Резервирование/) |
| Ценообразование и стимулирование продаж | [Стратегии продаж](</ERP/Стратегии%20продаж/>), [акции и скидки](/ERP/Промоакции/) |
| Операционная работа | [Клиенты и контрагенты](/ERP/Контрагенты/), [заказы](/ERP/Заказы/), [задачи](/ERP/Задачи/) |
| Управляемый контент | [Блоки](/ERP/Блоки/), [страницы](/ERP/Страницы/), [меню](/ERP/Меню/), [файлы](/ERP/Файлы/) |
| Допустимые ID, роли и вспомогательный поиск | [Справочники и права](/ERP/Справочники/), [калькулятор и подсказки](</ERP/Вспомогательные%20запросы/>) |

## Правила безопасной интеграции

- храните Bearer сотрудника или агента как секрет и не помещайте его в URL, аналитику или публичные клиентские логи;
- создавайте отдельный agent account для каждого профиля permissions; отдельный Agent Token используйте для каждой установки и ротации, а не как замену отдельным правам;
- выдавайте только те permissions, которые нужны конкретному сценарию;
- не выбирайте `project_id` произвольно и не пытайтесь обходить `403` или `404` подбором других ID;
- значения справочников получайте из API, а не фиксируйте по примерам документации;
- перед массовым изменением, возвратом денег или удалением добавляйте подтверждение и журналирование;
- при сетевом сбое после write-запроса сначала сверяйте текущее состояние ресурса.

---

## Доступ сотрудников

Source: https://docs.gigma.ru/ERP/%D0%90%D0%B2%D1%82%D0%BE%D1%80%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D1%8F/

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

### Отправка пароля на электронную почту

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/send_password`  
**Авторизация:** Не требуется  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Параметры запроса

- `login` — адрес электронной почты

#### Пример запроса

```json
{
    "login": "2141349@mail.ru"
}
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "message": "Password successfully send"
}
```

##### Описание полей ответа

- `message` — информационное поле


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

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/login`  
**Авторизация:** Не требуется  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Параметры запроса

- `login` *(string, обязательно)* — адрес электронной почты
- `password` *(string, обязательно)* — пароль из письма, отправленного по `POST /api/send_password`

> **Про пароль.** В примерах ниже стоит условный `"1111"`. На реальном сервере пароль строго из письма, которое приходит после `POST /api/send_password`.

#### Пример запроса

```json
{
    "login": "2141349@mail.ru",
    "password": "1111"
}
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "user": {
        "access_token": {
            "value": "28|dCWBGIqC9algoNXr6NVVg9D2fKWBaq7BJkRFyxq009cd040b"
        },
        "id": 1,
        "role": {
            "id": 1,
            "name": "owner",
            "description": "Собственник",
            "created_at": "2024-03-27T07:00:46.000000Z"
        },
        "branch": null,
        "department": null,
        "login": "2141349@mail.ru",
        "phone": "79139121349",
        "first_name": "Артём",
        "last_name": "Полищук",
        "middle_name": "Николаевич",
        "birthday": "1981-05-20",
        "employment_date": null,
        "dismissal_date": null,
        "avatar": null,
        "employment_contract": null,
        "is_banned": false,
        "is_sick": false,
        "creator": null,
        "active_time": 0,
        "last_activity_at": null,
        "permissions": [
            {
                "id": 2,
                "screen": null,
                "name": "edit-admins",
                "description": "Редактирование администраторов",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            {
                "id": 4,
                "screen": null,
                "name": "edit-users",
                "description": "Редактирование пользователей",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            {
                "id": 5,
                "screen": null,
                "name": "edit-roles",
                "description": "Редактирование ролей",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            {
                "id": 6,
                "screen": null,
                "name": "edit-permissions",
                "description": "Редактирование прав доступа",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            {
                "id": 7,
                "screen": null,
                "name": "edit-branches",
                "description": "Редактирование филиалов",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            {
                "id": 8,
                "screen": null,
                "name": "edit-departments",
                "description": "Редактирование отделов",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            {
                "id": 10,
                "screen": {
                    "id": 1,
                    "name": "Контрагенты",
                    "created_at": "2024-03-27T07:00:46.000000Z"
                },
                "name": "edit-counterparties",
                "description": "Редактирование контрагентов",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            {
                "id": 12,
                "screen": null,
                "name": "edit-communications",
                "description": "Редактирование коммуникаций",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            {
                "id": 14,
                "screen": {
                    "id": 2,
                    "name": "Заказы",
                    "created_at": "2024-03-27T07:00:46.000000Z"
                },
                "name": "edit-orders",
                "description": "Редактирование заказов",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            {
                "id": 16,
                "screen": {
                    "id": 3,
                    "name": "Задачи",
                    "created_at": "2024-03-27T07:00:46.000000Z"
                },
                "name": "edit-tasks",
                "description": "Редактирование задач",
                "created_at": "2024-03-27T07:00:46.000000Z"
            }
        ],
        "created_at": "2024-03-27T07:00:46.000000Z",
        "updated_at": "2024-04-03T07:07:11.000000Z"
    }
}
```

##### Описание полей ответа

- `access_token.value` *(string)* — Bearer-токен. Во всех последующих запросах слать заголовком:

  ```http
  Authorization: Bearer <access_token.value>
  ```

  При `401 Unauthenticated` нужно повторить `/api/login`. См. [Соглашения → Авторизация](/conventions/#auth).

Описание прочих полей приведено в запросе получения текущего пользователя.


### Получение текущего пользователя

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/user`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Параметры запроса

Отсутствуют.

#### Пример запроса

```
https://api.gigma.ru/api/user
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "user": {
        "id": 1,
        "role": {
            "id": 1,
            "name": "owner",
            "description": "Собственник",
            "created_at": "2024-03-27T07:00:46.000000Z"
        },
        "branch": null,
        "department": null,
        "login": "2141349@mail.ru",
        "phone": "79139121349",
        "first_name": "Артём",
        "last_name": "Полищук",
        "middle_name": "Николаевич",
        "birthday": "1981-05-20",
        "employment_date": null,
        "dismissal_date": null,
        "avatar": null,
        "employment_contract": null,
        "is_banned": false,
        "is_sick": false,
        "creator": null,
        "active_time": 0,
        "last_activity_at": "2024-04-03T07:07:19.000000Z",
        "permissions": [
            {
                "id": 2,
                "screen": null,
                "name": "edit-admins",
                "description": "Редактирование администраторов",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            {
                "id": 4,
                "screen": null,
                "name": "edit-users",
                "description": "Редактирование пользователей",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            {
                "id": 5,
                "screen": null,
                "name": "edit-roles",
                "description": "Редактирование ролей",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            {
                "id": 6,
                "screen": null,
                "name": "edit-permissions",
                "description": "Редактирование прав доступа",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            {
                "id": 7,
                "screen": null,
                "name": "edit-branches",
                "description": "Редактирование филиалов",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            {
                "id": 8,
                "screen": null,
                "name": "edit-departments",
                "description": "Редактирование отделов",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            {
                "id": 10,
                "screen": {
                    "id": 1,
                    "name": "Контрагенты",
                    "created_at": "2024-03-27T07:00:46.000000Z"
                },
                "name": "edit-counterparties",
                "description": "Редактирование контрагентов",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            {
                "id": 12,
                "screen": null,
                "name": "edit-communications",
                "description": "Редактирование коммуникаций",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            {
                "id": 14,
                "screen": {
                    "id": 2,
                    "name": "Заказы",
                    "created_at": "2024-03-27T07:00:46.000000Z"
                },
                "name": "edit-orders",
                "description": "Редактирование заказов",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            {
                "id": 16,
                "screen": {
                    "id": 3,
                    "name": "Задачи",
                    "created_at": "2024-03-27T07:00:46.000000Z"
                },
                "name": "edit-tasks",
                "description": "Редактирование задач",
                "created_at": "2024-03-27T07:00:46.000000Z"
            }
        ],
        "created_at": "2024-03-27T07:00:46.000000Z",
        "updated_at": "2024-04-03T07:07:11.000000Z"
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ пользователя
- `role` — объект, содержащий роль пользователя в системе
- `branch` — объект филиала, если есть
- `department` — объект отдела, если есть
- `login` — адрес электронной почты пользователя
- `phone` — номер телефона пользователя
- `first_name` — имя пользователя
- `last_name` — фамилия пользователя
- `middle_name` — отчество пользователя
- `birthday` — дата рождения пользователя
- `employment_date` — дата приема на работу
- `dismissal_date` — дата увольнения
- `avatar` — ссылка на аватар пользователя
- `employment_contract` — ссылка на трудовой договор
- `is_banned` — статус блокировки пользователя
- `is_sick` — статус больничного
- `creator` — объект, содержащий информацию о создателе пользователя, если есть
- `active_time` — активное время пользователя в системе
- `last_activity_at` — дата и время последней активности пользователя
- `permissions` — массив объектов, содержащих права доступа пользователя


### Выход пользователя из системы

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/user/logout`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Параметры запроса

- `from_all_devices` — признак, указывающий на необходимость выхода сразу со всех устройств

#### Пример запроса

```json
{
    "from_all_devices": true
}
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "message": "User successfully logout from all devices"
}
```

##### Описание полей ответа

- `message` — информационное поле

---

## MCP: рабочие методы

Source: https://docs.gigma.ru/ERP/%D0%9C%D0%A1%D0%9F/

# MCP: как агент работает с Gigma ERP

MCP в Gigma — это **внешний слой tools над обычным ERP API**. В Laravel backend нет отдельного маршрута `/api/mcp/*` и нет отдельного MCP-контроллера.

После получения Agent Token MCP-сервер вызывает обычные ERP endpoints:

```text
MCP tool
→ точный allowlist HTTP method + path
→ Authorization: Bearer <agent_token>
→ middleware auth:user + banned
→ controller и policy конкретного endpoint
→ response обычного ERP API
```

Наличие route внутри authenticated group ещё не доказывает безопасный MCP-контракт. Для каждого tool нужно отдельно проверить permission, project/branch scope, привязку вложенных ресурсов и состав ответа.

## Три разные API-поверхности

| Поверхность | Назначение | Кто вызывает |
| --- | --- | --- |
| `/api/agent-access-requests/*` | первоначальный запрос доступа и одноразовая выдача первого Agent Token | MCP-клиент и подтверждающий человек |
| обычные `/api/orders`, `/api/counterparties`, `/api/nomenclatures` и другие ERP endpoints | работа с бизнес-данными | MCP-сервер с Agent Token |
| `/api/agents/*` и `/api/tables/agents` | создание, изменение и отключение agent accounts, управление токенами | административный actor; token operations — только человек |

> `/api/agents` — не рабочие бизнес-ручки агента. Это административный ресурс для управления учётными записями агентов.

Получение первого токена описано на странице [«Получение доступа»](/ERP/МСП/Получение доступа/), а административные операции — на странице [«Управление агентами»](/ERP/МСП/Управление агентами/).

## Откуда берутся права

Agent Token создаётся Laravel Sanctum с abilities `*`, но эти abilities не являются бизнес-правами. Для endpoints, где policy подключена, фактический доступ определяется текущим agent account:

```text
Bearer
→ User с is_agent = true
→ project_id и branch_id этого User
→ текущие role + permissions
→ middleware, controller и policy конкретного endpoint
```

Разные токены одного agent account используют **один и тот же** набор role и permissions. Отдельный токен удобен для ротации или разных установок MCP-сервера, но не создаёт отдельную границу полномочий. Для изоляции профилей нужен отдельный agent account.

Если администратор удалил permission, заблокировал агента или отозвал токен, следующий запрос должен перестать работать. Старый Bearer после отзыва или блокировки не восстанавливается.

## Статусы профилей

| Профиль | Статус | Что разрешено сейчас |
| --- | --- | --- |
| P0 Connectivity | `current` | проверить Bearer через `GET /api/user` |
| P1 Sales Readonly | `current` | заказы, контрагенты и безопасные справочники |
| People Directory | `sensitive / opt-in` | сотрудники только при отдельной необходимости и фильтрации ответа |
| P2 Sales Operator | `conditional` | calculator сразу; записи — после проверки permission catalog и negative tests |
| P3 Catalog / Warehouse | `conditional` | после проверки наличия catalog permissions в БД |
| P4 Applications / Content | `blocked for normal assistant` | текущие responses раскрывают application `token` |
| P5 Agent Administration | `current` | account operations по permissions; token operations только для human actor |

Профиль — конфигурация MCP-сервера, а не сущность backend. Он состоит из permissions agent account, точного allowlist `method + path`, request schema и правил подтверждения write-операций.

## P0. Preflight: проверить токен

### Проверка рабочего Agent Token

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/user`  
**Авторизация:** Agent Bearer  

"
	success="200"
>

Endpoint возвращает wrapper `user` с обычным `UserResource`: ID, login, ФИО, роль, филиал, отдел, состояние блокировки, permissions и даты активности.

Используйте ответ, чтобы проверить:

- токен принят backend;
- учётная запись не заблокирована;
- роль, филиал и permissions соответствуют ожидаемому профилю tools.

**Ограничение текущего контракта:** `GET /api/user` не возвращает `is_agent` и `project_id`. Поэтому MCP-сервер не может доказать эти два значения по whoami. Тип учётной записи и ожидаемый проект должны храниться в конфигурации подключения, сформированной при выдаче доступа.

### Ошибки

- `401` — токен отсутствует, недействителен, истёк или отозван;
- `403` — доступ запрещён middleware или policy;
- заблокированный agent account не должен доходить до бизнес-контроллера.


## P1. Проверенный read-only профиль продаж

Минимальный набор permissions:

```json
[
	"view-orders",
	"view-counterparties"
]
```

### Рабочие списки

```http
GET /api/user

GET /api/orders
GET /api/tables/orders

GET /api/counterparties
GET /api/tables/counterparties
```

### Карточки и безопасные вложенные чтения

Сначала получите ID из списка, доступного текущему agent account, затем вызывайте:

```http
GET /api/orders/{order}
GET /api/orders/{order}/history
GET /api/tables/orders/{order}/files
GET /api/tables/orders/{order}/nomenclatures

GET /api/counterparties/{counterparty}
```

Для заказов backend применяет project scope, а для пользователя без роли `owner`/`admin` и с назначенным филиалом — ещё и branch scope. Вложенные order routes защищены `can:view,order`. `CounterpartyPolicy` проверяет permission и проект карточки.

### Контекстные справочники только на чтение

В tool allowlist можно добавить только `GET`:

```http
GET /api/order_statuses
GET /api/counterparty_types
GET /api/delivery_types
GET /api/sales_channels
GET /api/brands
GET /api/cities
GET /api/countries
GET /api/vats
GET /api/storage_units
```

Не добавляйте `POST`, `PUT`, `PATCH` и `DELETE` для справочников в обычный read-only профиль.

Подробные query-параметры и response schemas находятся в разделах [«Заказы»](/ERP/Заказы/) и [«Контрагенты»](/ERP/Контрагенты/).

## Отдельный sensitive-профиль: сотрудники

`GET /api/users`, `GET /api/tables/users` и `GET /api/users/{user}` не входят в минимальный P1. В текущем `UserPolicy` чтение разрешается не только по `view-users`, но также при наличии `create-users` или `edit-users`. Любое из этих трёх permissions нужно считать доступом к каталогу сотрудников.

Полный `UserResource` возвращает персональные и кадровые данные, включая `phone`, `birthday`, `employment_contract` и `dismissal_date`. Табличный resource короче, но всё равно содержит ФИО, login, роль, филиал, отдел и активность.

Подключайте эти endpoints только отдельному people-directory agent account. Для такого профиля:

- выдавайте минимальное право `view-users`, если запись сотрудников не нужна;
- не передавайте модели полный сырой ответ без необходимости;
- возвращайте только нужные поля, например ID и отображаемое имя;
- не включайте кадровые поля в логи и контекст модели;
- не рассчитывайте на отдельный токен того же агента как на изоляцию permissions.

Helper endpoints `GET /api/managers` и `GET /api/responsible_users` возвращают более короткие записи, но не вызывают `UserPolicy` и не требуют `view-users`, поэтому в production allowlist они пока не рекомендуются.

## Endpoints, которые нельзя включать в production MCP allowlist

Ниже перечислены зарегистрированные routes, для которых текущий runtime не обеспечивает ожидаемую комбинацию permission check, project scope, parent-child scope или безопасный response contract.

### Задачи

```http
GET   /api/tasks
GET   /api/tables/tasks
GET   /api/tasks/{task}
POST  /api/tasks
PATCH /api/tasks/{task}
```

`TaskController` не вызывает policy:

- list endpoints вручную добавляют только `project_id`;
- `show` принимает route model напрямую;
- `update` изменяет полученную модель без object-level project check;
- permissions `view-tasks` и `edit-tasks` в контроллере не проверяются.

Особенно опасны `GET /api/tasks/{task}` и `PATCH /api/tasks/{task}`. Не выдавайте их MCP-серверу до backend-hardening и negative tests на объект чужого проекта.

### Контакты и история контрагента

```http
GET    /api/counterparties/{counterparty}/history
GET    /api/counterparties/{counterparty}/contacts
GET    /api/counterparties/{counterparty}/contacts/{contact}
POST   /api/counterparties/{counterparty}/contacts
PATCH  /api/counterparties/{counterparty}/contacts/{contact}
DELETE /api/counterparties/{counterparty}/contacts/{contact}
```

`CounterpartyHistoryController` не проверяет проект. `ContactController` проверяет permission, но `ContactPolicy` не проверяет проект, а nested routes не обеспечивают связь `contact → counterparty`. Эти endpoints нельзя считать безопасными только из-за наличия `view-counterparties` или `edit-counterparties`.

### Приложения и интеграционные токены

Не включайте обычному MCP-помощнику:

```http
GET   /api/applications
GET   /api/tables/applications
GET   /api/applications/{application}
POST  /api/applications
PATCH /api/applications/{application}
GET   /api/applications/{application}/history
```

Текущие `ApplicationResource` и `Tables\ApplicationResource` возвращают поле `token`. Значит даже read-only list раскрывает интеграционный секрет всем, кому выдан `view-applications`.

Есть и второе несоответствие: list фильтрует приложения по текущему проекту и допускает глобальные записи с `project_id = null`, а `ApplicationPolicy::view()` для detail требует точного совпадения `application.project_id === user.project_id`. Поэтому объект может появиться в списке, но вернуть `403` на карточке.

`GET /api/applications/{application}/history` дополнительно использует базовый `Controller::history()` без project check для `Application`.

До исправления backend нужен один из вариантов:

1. убрать `token` из стандартных application resources;
2. вернуть секрет только отдельным endpoint с отдельным permission и аудитом;
3. после этого заново доказать list/detail scope и добавить negative tests.

### Webhooks и notification channels

Не включайте в обычный assistant-профиль:

```http
/api/applications/{application}/webhooks*
/api/applications/{application}/notification-channels/*
```

Эти методы могут раскрывать конфигурацию, ротировать секреты и повторно отправлять внешние доставки. Для них нужен отдельный integration-admin agent account, отдельный короткоживущий токен и подтверждение каждой write-операции.

### Inventory detail и write

```http
GET    /api/inventories/{inventory}
POST   /api/inventories
PATCH  /api/inventories/{inventory}
DELETE /api/inventories/{inventory}
```

`InventoryController` не подключает `authorizeResource`. `show`, `update` и `destroy` работают с route model без object-level project check; permission `view-inventories` или `edit-inventories` также не проверяется. Эти методы требуют исправления backend до подключения к MCP.

## P2. Подтверждаемые операции с заказами и контрагентами

### Готовый вычислительный tool

```http
POST /api/orders/calculator
```

Endpoint выполняет чистый расчёт по `price`, `markup` и `discount`, не читает модели из БД и не создаёт бизнес-сущность. Payload всё равно должен проходить фиксированную schema.

### Условные write-tools

```http
POST  /api/orders
PATCH /api/orders/{order}
POST  /api/orders/{order}/files
POST  /api/orders/{order}/nomenclatures
PATCH /api/orders/{order}/nomenclatures/{nomenclature}
DELETE /api/orders/{order}/nomenclatures/{nomenclature}

POST  /api/counterparties
PATCH /api/counterparties/{counterparty}
```

Фактическая логика permissions:

- создание заказа разрешается с `create-orders` **или** `edit-orders`;
- изменение заказа требует `edit-orders`;
- создание контрагента разрешается с `create-counterparties` **или** `edit-counterparties`;
- изменение контрагента требует `edit-counterparties`.

Базовый `PermissionSeeder` создаёт `edit-orders` и `edit-counterparties`, но не создаёт `create-orders` и `create-counterparties`. Поэтому create-only профиль нельзя считать доступным во всех инсталляциях. Перед включением write-tools:

1. проверьте, что точные permission records существуют с `guard_name = user`;
2. не подменяйте отсутствующее create-only право более широким `edit-*` без явного решения владельца;
3. проверьте положительный запрос в своём проекте и отрицательный запрос к ID другого проекта;
4. включите только фиксированные methods и paths.

Каждый write-tool обязан:

1. построить payload по фиксированной schema;
2. показать человеку окончательные method, path и JSON;
3. получить явное подтверждение;
4. выполнить запрос один раз;
5. перечитать созданный или изменённый объект и сверить результат.

Не повторяйте автоматически `POST`, `PATCH` или `DELETE` после `401`, `403`, `404`, `409` или `422`.

## P3. Каталог и склады

Контроллеры номенклатуры, категорий и складов используют resource policies и project-scoped списки:

```http
GET   /api/nomenclatures
GET   /api/tables/nomenclatures
GET   /api/nomenclatures/{nomenclature}
POST  /api/nomenclatures
PATCH /api/nomenclatures/{nomenclature}

GET   /api/categories
GET   /api/tables/categories
GET   /api/categories/{category}
POST  /api/categories
PATCH /api/categories/{category}

GET   /api/warehouses
GET   /api/tables/warehouses
GET   /api/warehouses/{warehouse}
POST  /api/warehouses
PATCH /api/warehouses/{warehouse}
```

Их policies используют permissions вида `view-*`, `create-*`, `edit-*`, но catalog permissions не входят в базовый `PermissionSeeder`. Профиль можно включать только после проверки, что нужные permission records реально существуют с `guard_name = user`, назначены agent account и проходят negative tests на чужой проект.

Inventory endpoints в этот профиль не входят из-за описанного выше authorization gap.

## P4. Приложения и контент

В текущем backend P4 **не является обычным production-профилем**. Основные application endpoints возвращают `token`, а nested CMS/integration routes требуют отдельного аудита scopes и секретов.

До redaction application token и отдельного permission contract не создавайте generic tools для:

```http
/api/applications*
/api/pages*
/api/menus*
/api/applications/{application}/blocks*
/api/applications/{application}/webhooks*
/api/applications/{application}/notification-channels/*
```

Разрешать отдельные storefront resources можно только отдельным agent account после проверки конкретного controller, policy, permission record и negative test. Не объединяйте content-admin и обычного sales assistant в одном agent account.

## P5. Администрирование агентов

Административная поверхность:

```http
GET    /api/agents
GET    /api/tables/agents
GET    /api/agents/{agent}
POST   /api/agents
PATCH  /api/agents/{agent}
DELETE /api/agents/{agent}

GET    /api/agents/{agent}/tokens
POST   /api/agents/{agent}/tokens
DELETE /api/agents/{agent}/tokens/{token}
```

Для неё используются отдельные permissions:

```json
[
	"view-agents",
	"create-agents",
	"edit-agents",
	"manage-agent-tokens"
]
```

Текущий `UserPolicy` не вводит глобальный запрет для agent actor на list, show, create, update или disable. Эти операции доступны authenticated actor, который прошёл соответствующие permission, project и delegation checks. Поэтому обычному MCP-помощнику нельзя выдавать agent-management permissions.

Для token operations действует отдельное правило: `UserPolicy::manageAgentTokens()` явно запрещает actor с `is_agent = true`. Выпуск, список и отзыв токенов через `/api/agents/{agent}/tokens*` выполняются Bearer-токеном человека. Полные request/response contracts находятся на странице [«Управление агентами»](/ERP/МСП/Управление агентами/).

## Обязательные правила MCP-сервера

### Только точный allowlist

Tool должен хранить конкретные:

```text
HTTP method + path pattern
```

Запрещён generic REST/curl proxy, через который модель может передать произвольный URL, method или JSON.

### ID только после scoped lookup

Не принимайте произвольный ID от модели. Сначала получите сущность из проверенного списка текущего проекта. Затем используйте возвращённый ID в следующем tool.

Исключение «ID получен из списка» не делает route безопасным, если сам list возвращает глобальные записи или чувствительные поля. Именно поэтому application endpoints сейчас заблокированы.

### Строгий payload

- удаляйте неизвестные поля;
- не отправляйте `undefined` и UI-placeholder;
- не используйте `0` как «не выбрано»: middleware `ConvertZeroToNull` может преобразовать его в `null`;
- отправляйте `null` только когда tool явно поддерживает очистку поля;
- показывайте человеку именно тот JSON, который будет отправлен.

### Секреты и чувствительные данные

Не записывайте в логи и историю:

- Agent Bearer;
- `request_token`;
- `approval_token`;
- ответ первого `consume`;
- `agent_token.value` из административной выдачи;
- application `token`;
- кадровые и персональные поля сотрудников, если они не нужны сценарию.

### Ошибки

| Код | Что означает для MCP-сервера |
| --- | --- |
| `401` | токен отсутствует, истёк или отозван; остановить запросы и запросить ротацию |
| `403` | permission или policy запретили действие; не обходить другим endpoint |
| `404` | объект отсутствует либо скрыт scope; не перебирать соседние ID |
| `409` | конфликт состояния; перечитать ресурс и показать человеку |
| `422` | payload или бизнес-правило не прошло валидацию; исправить данные, не повторять тот же запрос |
| `429` | применить backoff только для безопасного read/polling; write не дублировать вслепую |

## Минимальный production-набор

Для первого агента используйте:

```text
P0 Connectivity
+ P1 Sales Readonly
+ отдельные подтверждаемые write-tools только после проверки permission catalog
```

Не выдавайте обычному помощнику права и endpoints для сотрудников, приложений, интеграционных секретов, webhooks, ролей, permissions, других агентов и административных операций.

---

## MCP: получение доступа

Source: https://docs.gigma.ru/ERP/%D0%9C%D0%A1%D0%9F/%D0%9F%D0%BE%D0%BB%D1%83%D1%87%D0%B5%D0%BD%D0%B8%D0%B5%20%D0%B4%D0%BE%D1%81%D1%82%D1%83%D0%BF%D0%B0/

# Получение доступа MCP-агентом

Эта страница описывает только **создание agent account и получение первого Bearer-токена**. После этого агент работает не через эти endpoints, а через обычные ERP-методы, перечисленные в разделе [«MCP: как агент работает с Gigma ERP»](/ERP/МСП/).

Agent account не может войти по одноразовому паролю:

```http
POST /api/send_password
POST /api/login
```

Для пользователя с `is_agent = true` оба метода возвращают `403`.

## Полный self-service flow

```text
1. MCP-клиент создаёт access request
2. Gigma отправляет владельцу письмо
3. Владелец просматривает и подтверждает permissions
4. MCP-клиент опрашивает status
5. После approved один раз вызывает consume
6. Backend создаёт agent account и возвращает Agent Token
7. MCP-сервер сохраняет токен как секрет и переходит к обычным ERP endpoints
```

Access request живёт **30 минут**. Возможные состояния:

| Статус | Значение |
| --- | --- |
| `pending` | ожидается решение владельца |
| `approved` | можно выполнить `consume` |
| `declined` | владелец отказал |
| `expired` | TTL истёк |
| `consumed` | agent account и первый токен уже созданы |

## 1. Создать запрос

### Создание запроса доступа

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/agent-access-requests`  
**Авторизация:** Не требуется  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Параметры запроса

- `owner_email` *(string, обязательно)* — e-mail владельца или уполномоченного администратора проекта, до 255 символов;
- `agent_name` *(string, обязательно)* — понятное имя агента, от 1 до 255 символов;
- `agent_login` *(string, необязательно)* — уникальный технический login, от 3 до 255 символов;
- `permissions` *(string[], необязательно)* — до 100 существующих permissions с `guard_name = user`;
- `purpose` *(string, необязательно)* — назначение агента, до 5000 символов.

`project_id` и `role_id` клиент не передаёт.

#### Пример запроса

```json
{
	"owner_email": "owner@example.com",
	"agent_name": "MCP Order Assistant",
	"agent_login": "mcp-order-assistant",
	"permissions": [
		"view-orders",
		"view-counterparties"
	],
	"purpose": "Читать заказы и готовить сводки"
}
```

#### Ответ

```json
{
	"message": "Если такой администратор есть, мы отправили запрос.",
	"request": {
		"public_id": "3f48862d-516d-4c7b-b486-9b7bb205f920",
		"request_token": "<request_token>",
		"expires_at": "2026-08-16T16:30:00+00:00"
	}
}
```

Сохраните `public_id` и `request_token` сразу. `request_token` показывается клиенту в этом ответе и используется для `status` и `consume`.

Ответ намеренно нейтрален: он не раскрывает, существует ли `owner_email` и имеет ли пользователь право подтверждать запрос.

Backend ограничивает отправку approval-письма одному владельцу: не чаще одного письма за **10 минут**. Новый access request при этом всё равно может получить `201`, но письмо для него не будет отправлено. Не создавайте запросы повторно сразу после успешного ответа.


## 2. Открыть страницу подтверждения

### Страница подтверждения для владельца

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/agent-access-requests/{publicId}/review`  
**Авторизация:** Не требуется  
**Headers:** `Accept: text/html`  

#### Параметры пути

- `publicId` *(string, обязательно)* — публичный UUID запроса из ответа создания.

#### Пример запроса

```http
GET /api/agent-access-requests/3f48862d-516d-4c7b-b486-9b7bb205f920/review
Accept: text/html
```

#### Ответ

Backend возвращает HTML-страницу подтверждения. Ссылка из письма содержит секрет во fragment:

```text
https://api.gigma.ru/api/agent-access-requests/{publicId}/review#approval_token=<secret>
```

Fragment не отправляется серверу в URL. Страница читает `approval_token`, удаляет его из адресной строки и передаёт дальше только в JSON body.


## 3. Получить данные запроса

### Получение данных для review

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/agent-access-requests/{publicId}/review`  
**Авторизация:** Approval token из письма  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Параметры запроса

- `approval_token` *(string, обязательно)* — секрет из fragment ссылки подтверждения.

`approval_token` запрещено передавать в query string. Backend вернёт `422`.

#### Пример запроса

```json
{
	"approval_token": "<approval_token>"
}
```

#### Ответ

```json
{
	"status": "pending",
	"request": {
		"public_id": "3f48862d-516d-4c7b-b486-9b7bb205f920",
		"agent_name": "MCP Order Assistant",
		"agent_login": "mcp-order-assistant",
		"role": {
			"id": 14,
			"name": "employee"
		},
		"requested_permissions": [
			"view-orders",
			"view-counterparties"
		],
		"approved_permissions": null,
		"purpose": "Читать заказы и готовить сводки",
		"expires_at": "2026-08-16T16:30:00+00:00"
	}
}
```


## 4. Одобрить или отклонить

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

- owner или admin;
- либо пользователь с `edit-admins`;
- либо пользователь с `edit-permissions`.

Agent account подтверждать запрос не может.

### Одобрение доступа

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/agent-access-requests/{publicId}/approve`  
**Авторизация:** Approval token из письма  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Параметры запроса

- `approval_token` *(string, обязательно)* — секрет подтверждения;
- `permissions` *(string[], необязательно)* — итоговое подмножество первоначально запрошенных permissions.

Если `permissions` не переданы, backend пытается одобрить весь requested-набор. Недоступные права не отбрасываются автоматически: запрос вернёт `422`.

Во время `approve` backend выбирает роль проекта:

1. `employee`;
2. если её нет — legacy `employer`.

Если подходящей роли нет или подтверждающий пользователь не может её назначить, backend возвращает `422`.

#### Пример запроса

```json
{
	"approval_token": "<approval_token>",
	"permissions": [
		"view-orders"
	]
}
```

#### Ответ

```json
{
	"status": "approved",
	"message": "Доступ одобрен. Агент может забрать токен."
}
```


### Отклонение доступа

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/agent-access-requests/{publicId}/decline`  
**Авторизация:** Approval token из письма  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Параметры запроса

- `approval_token` *(string, обязательно)* — секрет подтверждения.

#### Пример запроса

```json
{
	"approval_token": "<approval_token>"
}
```

#### Ответ

```json
{
	"status": "declined",
	"message": "Запрос доступа отклонён."
}
```


## 5. Проверить статус

### Статус запроса доступа

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/agent-access-requests/{publicId}/status`  
**Авторизация:** Request token MCP-клиента  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Параметры запроса

- `request_token` *(string, обязательно)* — секрет, полученный при создании access request.

`request_token` передаётся только в JSON body. Query string отклоняется с `422`.

#### Пример запроса

```json
{
	"request_token": "<request_token>"
}
```

#### Ответ

```json
{
	"status": "approved",
	"expires_at": "2026-08-16T16:30:00+00:00",
	"server_time": "2026-08-16T16:05:12+00:00"
}
```

Polling:

- используйте интервал не меньше 3–5 секунд;
- применяйте backoff после `429`;
- после `approved` переходите к `consume`;
- остановитесь после `declined`, `expired` или `consumed`.


## 6. Один раз получить Agent Token

### Создание агента и получение первого токена

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/agent-access-requests/{publicId}/consume`  
**Авторизация:** Request token MCP-клиента  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Параметры запроса

- `request_token` *(string, обязательно)* — секрет, полученный при создании access request.

Вызывайте endpoint только после статуса `approved`.

#### Пример запроса

```json
{
	"request_token": "<request_token>"
}
```

#### Ответ

Первый успешный ответ:

```json
{
	"status": "consumed",
	"agent": {
		"id": 214,
		"name": "MCP Order Assistant",
		"login": "mcp-order-assistant"
	},
	"agent_token": {
		"id": 901,
		"name": "mcp-self-service",
		"value": "<agent_bearer>",
		"expires_at": "2027-08-16T16:05:20+00:00"
	}
}
```

`agent_token.value` показывается только в этом ответе. Сохраните его в secret storage до завершения операции.

Повторный `consume` не возвращает секрет:

```json
{
	"status": "consumed",
	"already_consumed": true
}
```

Backend окончательно проверяет уникальность `agent_login` именно во время `consume`. Если login уже занят, ответ — `409`; изменить login в одобренном request нельзя, нужен новый запрос.

Перед созданием агента backend повторно проверяет, что владелец всё ещё активен, имеет право подтверждать доступ и остаётся в том же проекте. После временного `403` или project conflict тот же одобренный request можно повторить после устранения причины, пока не истёк общий 30-минутный TTL.


## Текущие route limits

| Endpoint | Текущий limit |
| --- | --- |
| `POST /api/agent-access-requests` | `5/min` |
| `GET /api/agent-access-requests/{publicId}/review` | `30/min` |
| `POST /api/agent-access-requests/{publicId}/review` | `30/min` |
| `POST /api/agent-access-requests/{publicId}/approve` | `10/min` |
| `POST /api/agent-access-requests/{publicId}/decline` | `10/min` |
| `POST /api/agent-access-requests/{publicId}/status` | `30/min` |
| `POST /api/agent-access-requests/{publicId}/consume` | `10/min` |

Это текущая runtime-конфигурация routes, а не бессрочное продуктовое обещание. Клиент обязан обрабатывать `429`, учитывать `Retry-After`, если заголовок присутствует, и не дублировать write-запрос вслепую.

## После consume

1. Сохраните `agent_token.value` как секрет.
2. Выполните `GET /api/user`.
3. Сверьте фактическую роль, филиал и permissions.
4. Включите только заранее определённый allowlist tools.
5. Перейдите к обычным ERP endpoints из раздела [«MCP: как агент работает с Gigma ERP»](/ERP/МСП/).

Если первый Bearer потерян, восстановить его нельзя. Сотрудник с `manage-agent-tokens` должен выпустить новый токен через `/api/agents/{agent}/tokens`.

---

## Управление агентами

Source: https://docs.gigma.ru/ERP/%D0%9C%D0%A1%D0%9F/%D0%A3%D0%BF%D1%80%D0%B0%D0%B2%D0%BB%D0%B5%D0%BD%D0%B8%D0%B5%20%D0%B0%D0%B3%D0%B5%D0%BD%D1%82%D0%B0%D0%BC%D0%B8/

# Управление агентами

Эта страница описывает административные resources `/api/agents*` и `/api/tables/agents`.

Они не используются для чтения заказов, клиентов или других бизнес-данных. Рабочие методы MCP перечислены в разделе [«MCP: как агент работает с Gigma ERP»](/ERP/МСП/), а получение первого токена через владельца — в разделе [«Получение доступа»](/ERP/МСП/Получение доступа/).

Agent account хранится в таблице пользователей, но имеет `is_agent = true`. Поэтому:

- агенты исключены из `/api/users`;
- обычные сотрудники не открываются через `/api/agents/{agent}`;
- agent routes ограничивают целевой объект проектом текущего actor;
- отключение не удаляет запись, а устанавливает `is_banned = true` и отзывает все токены.

## Кто может вызывать административные endpoints

Backend не вводит единый запрет «agent actor не может администрировать агентов».

- list, show и table-list проверяют соответствующий agent permission;
- create проверяет `create-agents` и допустимость назначаемой роли/permissions;
- update и disable проверяют `edit-agents`, проект и текущий набор прав целевого агента;
- **token operations дополнительно требуют, чтобы actor не был агентом**.

Следовательно, технически agent account с административными permissions может читать, создавать, изменять и отключать другие agent accounts. Обычному MCP-помощнику такие permissions выдавать не следует. Для выпуска, просмотра и отзыва токенов в любом случае нужен Bearer человека.

## Permissions

| Permission | Операции |
| --- | --- |
| `view-agents` | список, table-list и карточка |
| `create-agents` | создание |
| `edit-agents` | изменение и отключение |
| `manage-agent-tokens` | список, выпуск и отзыв токенов; только human actor |

`view-users`, `create-users` и `edit-users` не заменяют agent permissions.

### Дополнительная проверка текущего агента

Одного permission `edit-agents` или `manage-agent-tokens` недостаточно. Перед update, disable и token operations policy проверяет уже назначенные агенту роль и permissions:

- для агента с ролью `owner` или `admin` actor должен иметь `edit-admins` либо `edit-permissions`;
- без `edit-permissions` actor может управлять только агентом, чей текущий permission set является подмножеством permissions actor;
- если агент уже сильнее actor, backend вернёт `403` даже при попытке уменьшить его права, отключить его или отозвать токен.

## Список агентов

### Список агентов проекта

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/agents`  
**Авторизация:** Bearer actor с view-agents  

"
	success="200"
>

#### Параметры запроса

- `role_id[]` *(integer[], необязательно)* — роли агентов;
- `branch_id[]` *(integer[], необязательно)* — филиалы;
- `department_id[]` *(integer[], необязательно)* — отделы;
- `is_banned` *(boolean, необязательно)* — состояние блокировки;
- `date_from` *(date, необязательно)* — дата создания от;
- `date_to` *(date, необязательно)* — дата создания по;
- `query` *(string, необязательно)* — поиск по имени или login, от 3 до 255 символов.

Фильтры не расширяют project scope: backend всегда подставляет `project_id` текущего actor.

#### Пример запроса

```http
GET /api/agents?is_banned=false&role_id[]=14&query=order
Authorization: Bearer <actor_token>
Accept: application/json
```

#### Ответ

```json
{
	"agents": [
		{
			"id": 214,
			"code": "12345678901",
			"name": "Order Assistant",
			"login": "order-assistant",
			"role": {
				"id": 14,
				"name": "employee"
			},
			"branch": null,
			"department": null,
			"agent_description": "Готовит сводки по заказам",
			"is_agent": true,
			"is_banned": false,
			"creator": {
				"id": 7,
				"avatar": "https://api.gigma.ru/storage/uploads/default.svg",
				"first_name": "Артём",
				"last_name": "Полищук",
				"middle_name": null,
				"name": "Полищук Артём"
			},
			"last_activity_at": null,
			"permissions": [
				{
					"name": "view-orders"
				}
			],
			"created_at": "2026-08-16T16:00:00.000000Z",
			"updated_at": "2026-08-16T16:00:00.000000Z"
		}
	],
	"agentsCount": 1
}
```

`code` генерируется backend как случайная уникальная строка из 11 цифр. Endpoint возвращает всю отфильтрованную коллекцию без стандартного pagination wrapper.


### Табличный список агентов

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/tables/agents`  
**Авторизация:** Bearer actor с view-agents  

"
	success="200"
>

#### Параметры запроса

Поддерживаются те же фильтры, что у `GET /api/agents`, и параметры табличной пагинации:

- `role_id[]` *(integer[], необязательно)* — роли агентов;
- `branch_id[]` *(integer[], необязательно)* — филиалы;
- `department_id[]` *(integer[], необязательно)* — отделы;
- `is_banned` *(boolean, необязательно)* — состояние блокировки;
- `date_from` *(date, необязательно)* — дата создания от;
- `date_to` *(date, необязательно)* — дата создания по;
- `query` *(string, необязательно)* — поиск по имени или login, от 3 до 255 символов;
- `page` *(integer, необязательно)* — номер страницы;
- `per_page` *(integer, необязательно)* — размер страницы.

#### Пример запроса

```http
GET /api/tables/agents?page=1&per_page=20&is_banned=false
Authorization: Bearer <actor_token>
Accept: application/json
```

#### Ответ

```json
{
	"columns": [
		{
			"id": 1,
			"table_id": 1,
			"order": 0,
			"key": "id",
			"has_icon": 0,
			"text": "№"
		}
	],
	"agents": [
		{
			"id": {
				"icon": null,
				"value": 214,
				"url": "<frontend_url>/agents/list-agents/214"
			},
			"code": "12345678901",
			"name": {
				"icon": null,
				"value": "Order Assistant",
				"url": "<frontend_url>/agents/list-agents/214"
			},
			"branch": null,
			"department": null,
			"role": "Сотрудник",
			"login": "order-assistant",
			"is_banned": false,
			"last_activity_at": "Ожидание входа"
		}
	],
	"pagination": {
		"total": 1,
		"per_page": 20,
		"current_page": 1,
		"last_page": 1,
		"from": 1,
		"to": 1
	}
}
```

Для server-to-server интеграции обычно достаточно ресурсного `GET /api/agents`; table-list нужен, когда действительно требуются UI-колонки и табличная пагинация.


## Карточка агента

### Получение агента

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/agents/{agent}`  
**Авторизация:** Bearer actor с view-agents  

"
	success="200"
>

#### Параметры пути

- `agent` *(integer, обязательно)* — ID agent account из проекта actor.

#### Пример запроса

```http
GET /api/agents/214
Authorization: Bearer <actor_token>
Accept: application/json
```

#### Ответ

```json
{
	"agent": {
		"id": 214,
		"code": "12345678901",
		"name": "Order Assistant",
		"login": "order-assistant",
		"role": {
			"id": 14,
			"name": "employee"
		},
		"branch": null,
		"department": null,
		"agent_description": "Готовит сводки по заказам",
		"is_agent": true,
		"is_banned": false,
		"creator": {
			"id": 7,
			"avatar": "https://api.gigma.ru/storage/uploads/default.svg",
			"first_name": "Артём",
			"last_name": "Полищук",
			"middle_name": null,
			"name": "Полищук Артём"
		},
		"last_activity_at": null,
		"permissions": [
			{
				"name": "view-orders"
			}
		],
		"created_at": "2026-08-16T16:00:00.000000Z",
		"updated_at": "2026-08-16T16:00:00.000000Z"
	}
}
```

#### Возможные ошибки

- `403` — нет `view-agents`;
- `404` — ID не существует, относится к человеку или agent account другого проекта.

Не перебирайте соседние ID после `404`.


## Создать agent account вручную

### Создание агента

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/agents`  
**Авторизация:** Bearer actor с create-agents  

"
	success="200"
>

#### Параметры запроса

- `name` *(string, обязательно)* — имя агента, от 1 до 255 символов;
- `login` *(string, обязательно)* — уникальный среди всех users технический login, от 3 до 255 символов;
- `role_id` *(integer, обязательно)* — роль текущего проекта;
- `branch_id` *(integer, необязательно)* — филиал текущего проекта или `null`;
- `department_id` *(integer, необязательно)* — отдел текущего проекта или `null`;
- `permissions` *(string[], необязательно)* — permissions с `guard_name = user`, которые actor вправе делегировать;
- `agent_description` *(string, необязательно)* — назначение агента, до 5000 символов, или `null`;
- `is_banned` *(boolean, необязательно)* — создать агента сразу отключённым.

Для роли `owner` или `admin` actor должен иметь `edit-admins` либо `edit-permissions`. Другие роли текущего проекта отдельной иерархией не сравниваются.

Без `edit-permissions` каждое передаваемое permission должно уже принадлежать actor. С `edit-permissions` можно выбирать любое существующее permission с `guard_name = user`.

`project_id`, `creator_id`, `code` и `is_agent` backend назначает сам.

#### Пример запроса

```json
{
	"name": "Order Assistant",
	"login": "order-assistant",
	"role_id": 14,
	"branch_id": null,
	"department_id": null,
	"permissions": [
		"view-orders",
		"view-counterparties"
	],
	"agent_description": "Готовит сводки по заказам",
	"is_banned": false
}
```

#### Ответ

```json
{
	"agent": {
		"id": 214,
		"code": "12345678901",
		"name": "Order Assistant",
		"login": "order-assistant",
		"role": {
			"id": 14,
			"name": "employee"
		},
		"branch": null,
		"department": null,
		"agent_description": "Готовит сводки по заказам",
		"is_agent": true,
		"is_banned": false,
		"creator": {
			"id": 7,
			"avatar": "https://api.gigma.ru/storage/uploads/default.svg",
			"first_name": "Артём",
			"last_name": "Полищук",
			"middle_name": null,
			"name": "Полищук Артём"
		},
		"last_activity_at": null,
		"permissions": [
			{
				"name": "view-orders"
			},
			{
				"name": "view-counterparties"
			}
		],
		"created_at": "2026-08-16T16:00:00.000000Z",
		"updated_at": "2026-08-16T16:00:00.000000Z"
	}
}
```

`AgentService::create()` возвращает повторно загруженную через `fresh()` модель. Поэтому `AgentResource` получает HTTP `200`, а не автоматический `201`. Токен автоматически не создаётся: после создания его отдельно выпускает человек через `POST /api/agents/{agent}/tokens`.


## Изменить агента

### Изменение агента

**Метод:** PATCH  
**URL:** `https://api.gigma.ru/api/agents/{agent}`  
**Авторизация:** Bearer actor с edit-agents и правом управлять текущим агентом  

"
	success="200"
>

#### Параметры запроса

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

- `name` *(string, необязательно)* — новое имя, от 1 до 255 символов;
- `login` *(string, необязательно)* — новый уникальный login, от 3 до 255 символов;
- `role_id` *(integer, необязательно)* — новая роль текущего проекта;
- `branch_id` *(integer, необязательно)* — филиал текущего проекта или `null` для очистки;
- `department_id` *(integer, необязательно)* — отдел текущего проекта или `null` для очистки;
- `permissions` *(string[], необязательно)* — полный новый набор permissions; пустой массив или `null` очищает права;
- `agent_description` *(string, необязательно)* — новое описание или `null`;
- `is_banned` *(boolean, необязательно)* — состояние блокировки.

Если поле отсутствует, его текущее значение сохраняется. До валидации нового payload policy проверяет **текущие** роль и permissions агента. Поэтому actor, который не вправе управлять текущим набором, получает `403` и не сможет использовать update как способ сначала понизить агента.

#### Пример запроса

```json
{
	"name": "Order Assistant v2",
	"login": "order-assistant",
	"role_id": 14,
	"branch_id": null,
	"department_id": null,
	"permissions": [
		"view-orders"
	],
	"agent_description": "Готовит только сводки заказов",
	"is_banned": false
}
```

#### Ответ

```json
{
	"agent": {
		"id": 214,
		"code": "12345678901",
		"name": "Order Assistant v2",
		"login": "order-assistant",
		"role": {
			"id": 14,
			"name": "employee"
		},
		"branch": null,
		"department": null,
		"agent_description": "Готовит только сводки заказов",
		"is_agent": true,
		"is_banned": false,
		"creator": {
			"id": 7,
			"avatar": "https://api.gigma.ru/storage/uploads/default.svg",
			"first_name": "Артём",
			"last_name": "Полищук",
			"middle_name": null,
			"name": "Полищук Артём"
		},
		"last_activity_at": null,
		"permissions": [
			{
				"name": "view-orders"
			}
		],
		"created_at": "2026-08-16T16:00:00.000000Z",
		"updated_at": "2026-08-16T16:10:00.000000Z"
	}
}
```

Если `is_banned` становится `true`, backend сразу удаляет все Agent Token. Последующее включение через `is_banned: false` не восстанавливает прежние токены.


## Отключить агента

### Отключение агента

**Метод:** DELETE  
**URL:** `https://api.gigma.ru/api/agents/{agent}`  
**Авторизация:** Bearer actor с edit-agents и правом управлять текущим агентом  

"
	success="200"
>

#### Параметры пути

- `agent` *(integer, обязательно)* — ID agent account из проекта actor.

Endpoint не удаляет строку пользователя. Он устанавливает `is_banned = true`, удаляет все personal access tokens агента и оставляет agent account в административном списке.

#### Пример запроса

```http
DELETE /api/agents/214
Authorization: Bearer <actor_token>
Accept: application/json
```

#### Ответ

```json
{
	"message": "Агент успешно отключён"
}
```

Чтобы вернуть агента в работу:

1. `PATCH /api/agents/{agent}` с `{"is_banned": false}`;
2. человек вызывает `POST /api/agents/{agent}/tokens`;
3. новый Bearer безопасно передаётся MCP-серверу.


## Токены агента: только human actor

`UserPolicy::manageAgentTokens()` первым делом проверяет `is_agent`. Agent actor получает `403` независимо от наличия `manage-agent-tokens`.

### Список токенов агента

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/agents/{agent}/tokens`  
**Авторизация:** Bearer человека с manage-agent-tokens и правом управлять текущим агентом  

"
	success="200"
>

#### Параметры пути

- `agent` *(integer, обязательно)* — ID agent account из проекта actor.

#### Пример запроса

```http
GET /api/agents/214/tokens
Authorization: Bearer <user_token>
Accept: application/json
```

#### Ответ

```json
{
	"agent_tokens": [
		{
			"id": 901,
			"name": "production-mcp",
			"created_at": "2026-08-16T16:00:00+00:00",
			"last_used_at": null,
			"expires_at": "2027-08-16T16:00:00+00:00"
		}
	],
	"agentTokensCount": 1
}
```

Поле `value` в списке отсутствует. Уже выпущенный Bearer нельзя прочитать повторно.


### Выпуск Agent Token

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/agents/{agent}/tokens`  
**Авторизация:** Bearer человека с manage-agent-tokens и правом управлять текущим агентом  

"
	success="201"
>

#### Параметры запроса

- `name` *(string, обязательно)* — назначение токена, от 3 до 100 символов;
- `expires_at` *(date-time, необязательно)* — дата истечения в будущем, не дальше одного года.

Если `expires_at` не передан, backend устанавливает срок один год. Отключённому агенту новый токен не выдаётся: `422`.

#### Пример запроса

```json
{
	"name": "production-mcp",
	"expires_at": "2027-02-16T16:00:00+00:00"
}
```

#### Ответ

```json
{
	"agent_token": {
		"id": 901,
		"name": "production-mcp",
		"created_at": "2026-08-16T16:00:00+00:00",
		"last_used_at": null,
		"expires_at": "2027-02-16T16:00:00+00:00",
		"value": "<agent_bearer>"
	}
}
```

`value` показывается только один раз. Сохраните его в secret storage до завершения операции.

Созданный `AgentTokenResource` получает HTTP `201`: underlying `PersonalAccessToken` передаётся в resource без повторного `fresh()`. Токен имеет Sanctum abilities `*`; рабочие права по-прежнему берутся из permissions agent account.


### Отзыв Agent Token

**Метод:** DELETE  
**URL:** `https://api.gigma.ru/api/agents/{agent}/tokens/{token}`  
**Авторизация:** Bearer человека с manage-agent-tokens и правом управлять текущим агентом  

"
	success="200"
>

#### Параметры пути

- `agent` *(integer, обязательно)* — ID agent account из проекта actor;
- `token` *(integer, обязательно)* — ID токена из `GET /api/agents/{agent}/tokens`.

Backend ищет token только внутри выбранного агента. Чужой token ID возвращает `404`.

#### Пример запроса

```http
DELETE /api/agents/214/tokens/901
Authorization: Bearer <user_token>
Accept: application/json
```

#### Ответ

```json
{
	"message": "Токен агента успешно отозван"
}
```

После отзыва MCP-сервер должен прекратить использование секрета. Для ротации сначала выпустите новый токен и проверьте его через `GET /api/user`, затем отзовите старый.


## Границы административного API

- `/api/users*` не управляет agent accounts: `UserPolicy` отклоняет целевые модели с `is_agent = true`;
- все agent и token endpoints проверяют принадлежность целевого агента проекту actor;
- наличие Agent Token само по себе не даёт agent permissions;
- текущий backend не запрещает agent actor list/create/update/disable, если ему фактически выданы соответствующие permissions;
- управление токенами agent actor запрещено policy независимо от выданного permission;
- разные токены одного агента не имеют разных business permissions: права меняются на самом agent account.

---

## Сотрудники и менеджеры

Source: https://docs.gigma.ru/ERP/%D0%9F%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D0%B8/

# Пользователи

Endpoint'ы делятся на два слоя:

1. **Полный поиск пользователей** (`/api/users`) — возвращает развёрнутые объекты пользователей с ролями, филиалами, правами.
2. **Упрощённые списки** (`/api/managers`, `/api/responsible_users`) — для UI-фильтров и dropdown'ов, возвращают только `id` и `name`.

См. также: [ERP/Авторизация](/ERP/Авторизация/) для получения текущего пользователя (`GET /api/user`).

### Поиск пользователей

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/users`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Параметры запроса (query string)

- `query` — поисковая строка по ФИО или login

#### Пример запроса

```
GET https://api.gigma.ru/api/users?query=Stewart
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "users": [
        {
            "id": 31,
            "role": {
                "id": 3,
                "name": "manager",
                "avatar": null,
                "description": "Руководитель отдела",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            "branch": {
                "id": 1,
                "name": "ООО \"АЙТЕКО\"",
                "avatar": "https://api.gigma.ru/storage/uploads/9qzh2GCaYpRpaxXnql0JZYpIesu3qlvQLV2OBhcN.png",
                "created_at": "2024-03-27T07:26:29.000000Z"
            },
            "department": {
                "id": 1,
                "name": "Технический",
                "avatar": "https://api.gigma.ru/storage/uploads/default.svg",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            "login": "yaroslav42@er.fs",
            "phone": "71235512351",
            "first_name": "Jon",
            "last_name": "Doe",
            "middle_name": "Stewart",
            "birthday": "2024-07-03",
            "employment_date": null,
            "dismissal_date": null,
            "avatar": {
                "id": 456,
                "name": "photo.jpg",
                "type": { "id": 2, "name": "Аватар", "avatar": "https://api.gigma.ru/storage/uploads/default.svg", "created_at": "2024-03-27T07:00:46.000000Z" },
                "path": "https://api.gigma.ru/storage/uploads/YiSnszaC109sWAJKsvcWvK6IDR8sF1JC3X9Nve5X.jpg",
                "created_at": "2024-07-24T10:48:49.000000Z",
                "updated_at": "2024-07-24T10:48:49.000000Z"
            },
            "employment_contract": null,
            "is_banned": false,
            "is_sick": false,
            "creator": { "id": 1, "first_name": "Артём", "last_name": "Полищук", "middle_name": "Николаевич", "name": "Полищук Артём" },
            "active_time": 0,
            "last_activity_at": null,
            "permissions": [],
            "created_at": "2024-07-19T16:14:14.000000Z",
            "updated_at": "2024-07-25T12:19:56.000000Z"
        }
    ],
    "usersCount": 1
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `role` — роль в системе (`id`, `name`, `description`)
- `branch` — филиал, к которому привязан
- `department` — отдел
- `login` — логин (email)
- `phone` — телефон
- `first_name`, `last_name`, `middle_name`, `birthday` — ФИО + ДР
- `employment_date`, `dismissal_date` — даты трудоустройства/увольнения
- `avatar` — объект файла аватара или `null`
- `employment_contract` — файл трудового договора или `null`
- `is_banned`, `is_sick` — флаги
- `creator` — кто завёл этого пользователя
- `active_time`, `last_activity_at` — активность
- `permissions[]` — массив прав доступа
- `created_at`, `updated_at` — таймстампы


### Список менеджеров (упрощённый)

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/managers`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

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

#### Ответ

```json
{
    "managers": [
        { "id": 1, "name": "Полищук Артём" },
        { "id": 2, "name": "Жуков Алексей" }
    ],
    "managersCount": 2
}
```

##### Описание полей ответа

- `managers[]` — массив: `id`, `name` (готовая склейка ФИО)
- `managersCount` — общее количество


### Список ответственных пользователей

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/responsible_users`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

Используется в фильтре «Ответственный» в таблице бизнесов и других местах.

#### Ответ

```json
{
    "responsibleUsers": [
        { "id": 2, "name": "Жуков Алексей" },
        { "id": 3, "name": "Иванов Сергей" }
    ],
    "responsibleUsersCount": 2
}
```

---

## Бизнесы и реквизиты

Source: https://docs.gigma.ru/ERP/%D0%91%D0%B8%D0%B7%D0%BD%D0%B5%D1%81%D1%8B/

# Бизнесы

Бизнес (`branch`) — юридическое лицо/филиал, к которому привязаны заказы, сотрудники, склады, реквизиты и интеграции с банками.

## Список и таблица

### Список бизнесов

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/branches`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Параметры запроса (query string)

- `query` — поисковая строка (необязательно)

#### Пример запроса

```
GET https://api.gigma.ru/api/branches
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "branches": [
        {
            "id": 1,
            "code": "1349",
            "responsible_user": {
                "id": 2,
                "first_name": "Алексей",
                "last_name": "Жуков",
                "middle_name": "Игоревич",
                "name": "Жуков Алексей"
            },
            "avatar": {
                "id": 40,
                "name": "organic-cosmetics.png",
                "path": "https://beta.back.erp.itecho.ru/storage/uploads/organic-cosmetics.png",
                "created_at": "2024-06-17T16:05:02.000000Z",
                "updated_at": "2024-06-17T16:05:02.000000Z"
            },
            "title": "Продажа косметики",
            "inn": "5403057658",
            "name": "ООО \"АЙТЕКО\"",
            "kpp": "540301001",
            "phone_1": "79139121349",
            "phone_2": "71231231231",
            "email": "support@itecho.ru",
            "head": "Снегирёв Алексей Игоревич",
            "address": "630073, г. Новосибирск, Новогодняя ул., д. 20/1, кв. 26",
            "legal_address": "630073, г. Новосибирск, Новогодняя ул., д. 20/1, кв. 26",
            "created_at": "2024-03-27T07:26:29.000000Z"
        }
    ],
    "branchesCount": 1
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `code` — внутренний код бизнеса
- `responsible_user` — ответственный пользователь (объект): `id`, `first_name`, `last_name`, `middle_name`, `name`
- `avatar` — файл аватара/логотипа или `null`
- `title` — короткое название проекта/бизнеса
- `name` — полное юридическое наименование
- `inn`, `kpp` — реквизиты юрлица
- `head` — ФИО директора
- `phone_1`, `phone_2`, `email`
- `address` — фактический адрес
- `legal_address` — юридический адрес
- `created_at` — дата создания
- `branchesCount` — общее количество бизнесов


### Таблица бизнесов (для UI с колонками и пагинацией)

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/tables/branches`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

Возвращает данные, готовые к отрисовке таблицы: список колонок, упрощённые бизнесы и пагинацию.

#### Параметры запроса (query string)

- `query` — поисковая строка
- `responsible_user_id[]` — фильтр по ответственному
- `page`, `per_page` — пагинация

#### Ответ

```json
{
    "columns": [
        { "id": 1, "table_id": 4, "order": 1, "key": "title", "has_icon": 1, "text": "Название" },
        { "id": 2, "table_id": 4, "order": 2, "key": "responsible_user", "has_icon": 1, "text": "Ответственный" },
        { "id": 3, "table_id": 4, "order": 3, "key": "inn", "has_icon": 0, "text": "ИНН" }
    ],
    "branches": [ { "id": 1, "code": "1349", "title": "Продажа косметики", "inn": "5403057658" } ],
    "pagination": {
        "total": 5,
        "per_page": 15,
        "current_page": 1,
        "last_page": 1,
        "from": 1,
        "to": 5
    },
    "message": ""
}
```

##### Описание полей ответа

- `columns[]` — определения колонок (`id`, `table_id`, `order`, `key`, `has_icon`, `text`)
- `branches[]` — упрощённые объекты бизнесов для таблицы
- `pagination` — стандартный Laravel-пагинатор
- `message` — служебное сообщение (обычно пусто)


## Карточка бизнеса

### Получение бизнеса по ID

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/branches/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Параметры запроса

Только `id` бизнеса в пути URL.

#### Ответ

```json
{
    "branch": {
        "id": 1,
        "code": "1349",
        "responsible_user": {
            "id": 2,
            "first_name": "Алексей",
            "last_name": "Жуков",
            "middle_name": "Игоревич",
            "name": "Жуков Алексей"
        },
        "avatar": null,
        "title": "Разработка и продажа ПО",
        "inn": "5403057658",
        "name": "ООО \"АЙТЕКО\"",
        "kpp": "540301001",
        "phone_1": "79139121349",
        "phone_2": null,
        "email": "support@itecho.ru",
        "head": "Снегирёв Алексей Игоревич",
        "address": "630073, г. Новосибирск, Новогодняя ул., д. 20/1, кв. 26",
        "legal_address": "630073, г. Новосибирск, Новогодняя ул., д. 20/1, кв. 26",
        "created_at": "2024-03-27T07:26:29.000000Z"
    }
}
```


### Создание бизнеса

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/branches`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Параметры запроса (тело)

- `title` — короткое название проекта
- `name` — полное юридическое наименование
- `code` — внутренний код
- `inn`, `kpp` — реквизиты юрлица
- `head` — ФИО директора
- `phone_1`, `phone_2`, `email`
- `address` — фактический адрес
- `legal_address` — юридический адрес
- `responsible_user_id` — ID ответственного пользователя (nullable)
- `avatar_id` — ID файла аватара (необязательно)

#### Пример запроса

```json
{
    "title": "Продажа косметики",
    "name": "ООО \"АЙТЕКО\"",
    "code": "1349",
    "inn": "5403057658",
    "kpp": "540301001",
    "head": "Снегирёв Алексей Игоревич",
    "phone_1": "79139121349",
    "phone_2": "71231231231",
    "email": "support@itecho.ru",
    "address": "630073, г. Новосибирск, Новогодняя ул., д. 20/1, кв. 26",
    "legal_address": "630073, г. Новосибирск, Новогодняя ул., д. 20/1, кв. 26",
    "responsible_user_id": 2,
    "avatar_id": 40
}
```

#### Ответ

```json
{
    "branch": { "id": 42, "...": "поля как в GET" }
}
```


### Изменение бизнеса

**Метод:** PUT  
**URL:** `https://api.gigma.ru/api/branches/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Параметры запроса (тело)

Те же поля, что и в `POST /api/branches`.

#### Ответ

```json
{
    "branch": { "id": 1, "...": "обновлённый объект" }
}
```


### Удаление бизнеса

**Метод:** DELETE  
**URL:** `https://api.gigma.ru/api/branches/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Параметры запроса

Только `id` бизнеса в пути URL.

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "message": "Branch deleted"
}
```


## Банковские реквизиты бизнеса

### Список реквизитов бизнеса

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/branches/{id}/bank_requisites`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Ответ

```json
{
    "bankRequisites": [
        {
            "id": 1,
            "name": "Расчётный счёт в Сбербанке",
            "bik": "045004641",
            "kpp": "540301001",
            "payment_account": "40702810844050003101",
            "address": "630007, г. Новосибирск, Красный проспект, д. 5"
        }
    ],
    "bankRequisitesCount": 1
}
```


### Добавление реквизита бизнеса

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/branches/{id}/bank_requisites`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Параметры запроса (тело)

- `name` — название счёта/банка
- `bik` — БИК
- `kpp` — КПП
- `payment_account` — номер расчётного счёта
- `address` — адрес банка

#### Пример запроса

```json
{
    "name": "Расчётный счёт в Сбербанке",
    "bik": "045004641",
    "kpp": "540301001",
    "payment_account": "40702810844050003101",
    "address": "630007, г. Новосибирск, Красный проспект, д. 5"
}
```

#### Ответ

Структура аналогична GET — массив `bankRequisites` и `bankRequisitesCount`.


### Изменение реквизита бизнеса

**Метод:** PUT  
**URL:** `https://api.gigma.ru/api/branches/{id}/bank_requisites/{requisiteId}`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Параметры запроса (тело)

Те же поля, что и в POST.

#### Ответ

Структура аналогична GET.


## История

### История изменений бизнеса

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/branches/{id}/history`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Ответ

```json
{
    "histories": [
        {
            "id": 101,
            "icon": "edit",
            "color": "info",
            "title": "Изменён телефон",
            "description": "phone_1: 79139121349 → 79991112233",
            "datetime": "2024-04-03T07:07:11.000000Z"
        }
    ],
    "historiesCount": 1
}
```

##### Описание полей ответа

- `histories[]` — события таймлайна:
  - `id` — ID события
  - `icon` — имя иконки (`edit`, `add`, `delete`, …)
  - `color` — `primary | secondary | info | success | warning | error | dark | light`
  - `title` — короткий заголовок
  - `description` — описание изменения
  - `datetime` — ISO-8601
- `historiesCount` — общее количество событий


## Интеграции банковских реквизитов

Каждый банковский реквизит может иметь подключённые интеграции (например, для автоматической синхронизации операций). Интеграция имеет фиксированный набор `parameters` (определения параметров) и `values` (значения, заполняемые пользователем).

### Список интеграций реквизита

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/branches/{branchId}/bank_requisites/{bankId}/integrations`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Ответ

```json
{
    "integrations": [
        {
            "id": 1,
            "integration_id": 5,
            "name": "Сбербанк API",
            "avatar": "https://beta.back.erp.itecho.ru/storage/integrations/sberbank.svg",
            "is_active": 1,
            "parameters": [
                { "id": 1, "title": "Логин", "order": 1, "key_1": "login", "key_2": "password", "description_1": "Логин", "description_2": "Пароль" }
            ],
            "values": [
                { "id": 1, "key_1": "login", "key_2": "password", "description_1": "Логин", "description_2": "Пароль", "value_1": "user123", "value_2": "***" }
            ]
        }
    ],
    "integrationsCount": 1
}
```

##### Описание полей ответа

- `integrations[]`:
  - `id` — ID связи (реквизит ↔ интеграция)
  - `integration_id` — ID типа интеграции в каталоге
  - `name` — название интеграции
  - `avatar` — URL логотипа
  - `is_active` — `1` если активна, иначе `0`
  - `parameters[]` — определения параметров (метаданные)
  - `values[]` — заполненные значения параметров


### Изменение интеграции реквизита

**Метод:** PUT  
**URL:** `https://api.gigma.ru/api/branches/{branchId}/bank_requisites/{bankId}/integrations/{integrationsId}`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Параметры запроса (тело)

- `is_active` — `1` чтобы активировать, `0` чтобы выключить
- (опционально) другие поля для обновления

#### Ответ

```json
{
    "integration": {
        "id": 1,
        "integration_id": 5,
        "name": "Сбербанк API",
        "is_active": 1,
        "parameters": [],
        "values": []
    }
}
```


### Описание интеграции по ID

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/integrations/{integrationId}`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

Возвращает каталожное описание интеграции (без привязки к реквизиту) — нужно, чтобы узнать какие параметры она ждёт.

#### Ответ

```json
{
    "integration": {
        "id": 5,
        "name": "Сбербанк API",
        "avatar": "https://beta.back.erp.itecho.ru/storage/integrations/sberbank.svg",
        "params": [
            { "id": 1, "title": "Логин и пароль", "order": 1, "key_1": "login", "key_2": "password", "description_1": "Логин", "description_2": "Пароль" }
        ]
    }
}
```

##### Описание полей ответа

- `integration.params[]` — определения параметров: `id`, `title`, `order`, `key_1`/`key_2`, `description_1`/`description_2` (двухколоночный layout: ключ-значение)


### Параметры (значения) интеграции реквизита

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/branches/{branchId}/bank_requisites/{bankId}/integrations/{integrationId}/parameters`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Ответ

```json
{
    "parameters": [
        {
            "id": 1,
            "key_1": "login",
            "description_1": "Логин",
            "key_2": "password",
            "description_2": "Пароль",
            "value_1": "user123",
            "value_2": "***"
        }
    ],
    "parametersCount": 1
}
```

##### Описание полей ответа

- `parameters[]` — заполненные значения параметров интеграции: `id`, `key_1`/`description_1`/`value_1`, `key_2`/`description_2`/`value_2`
- `parametersCount` — общее количество


### Добавление значения параметра интеграции

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/branches/{branchId}/bank_requisites/{bankId}/integrations/{integrationsId}/parameters`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Параметры запроса (тело)

- `integration_parameter_id` — ID определения параметра (из `params[]` интеграции)
- `value_1` — значение первого поля
- `value_2` — значение второго поля

#### Пример запроса

```json
{
    "integration_parameter_id": 1,
    "value_1": "user123",
    "value_2": "secret"
}
```

#### Ответ

```json
{
    "parameter": {
        "id": 7,
        "key_1": "login",
        "description_1": "Логин",
        "key_2": "password",
        "description_2": "Пароль",
        "value_1": "user123",
        "value_2": "secret"
    }
}
```


### Удаление значения параметра интеграции

**Метод:** DELETE  
**URL:** `https://api.gigma.ru/api/branches/{branchId}/bank_requisites/{bankId}/integrations/{integrationId}/parameters/{parameterId}`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Ответ

```json
{
    "message": "Parameter deleted"
}
```


## Вспомогательные

### Список ответственных пользователей (для фильтра)

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/responsible_users`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

Используется в фильтре «Ответственный» на таблице бизнесов.

#### Ответ

```json
{
    "responsibleUsers": [
        { "id": 2, "name": "Жуков Алексей" },
        { "id": 3, "name": "Иванов Сергей" }
    ],
    "responsibleUsersCount": 2
}
```


### Поиск пользователя по строке

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/users`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

Используется при выборе ответственного пользователя в форме бизнеса (autocomplete).

#### Параметры запроса (query string)

- `query` — поисковая строка по ФИО

#### Пример запроса

```
GET https://api.gigma.ru/api/users?query=Иванов
```

#### Ответ

```json
{
    "users": [
        {
            "id": 3,
            "first_name": "Сергей",
            "last_name": "Иванов",
            "middle_name": "Петрович",
            "name": "Иванов Сергей",
            "login": "ivanov@itecho.ru"
        }
    ],
    "usersCount": 1
}
```

---

## Приложения и webhooks

Source: https://docs.gigma.ru/ERP/%D0%9F%D1%80%D0%B8%D0%BB%D0%BE%D0%B6%D0%B5%D0%BD%D0%B8%D1%8F/

# Приложения

Раздел API для управления приложениями в системе ERP. Поддерживает получение списка приложений, управление вебхуками, категориями, брендами и пунктами меню приложения.

Практический порядок запуска и понятие `Application` описаны на странице [«Сайты и приложения»](</E-Commerce/Сайты%20и%20приложения/>). Для серверной схемы используйте отдельную [карту интеграции через backend](</E-Commerce/Интеграция%20через%20backend/>).

Для просмотра нужен доступ к тому же проекту и одно из прав: `view-applications`, `create-applications` или `edit-applications`. Создать приложение можно с правом `create-applications` или `edit-applications`; изменять и удалять — с правом `edit-applications`.

## Приложения

### Получение списка приложений

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/applications`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `query` *(string, необязательный)* — поиск по названию, не менее трёх символов.

#### Ответ

При успешном действии возвращается HTTP код `200`.


### Создание приложения

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/applications`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `name` *(string, обязательный)* — название приложения.
- `is_website` *(bool, обязательный)* — `true` для сайта, `false` для другого типа клиента.
- `branch_id` *(int, обязательный)* — ID филиала.
- `sales_strategy_id` *(int, обязательный)* — ID стратегии продаж.
- `code` *(int, необязательный)* — уникальный код в проекте. Если не передать, Gigma создаст его автоматически.
- `photo_id` *(int, необязательный)* — ID файла-обложки.
- `wholesale` *(bool, необязательный)* — признак оптового режима.
- `success_payment_url` *(string|null, необязательный)* — URL возврата после успешной оплаты.

```json
{
    "name": "Интернет-магазин",
    "is_website": true,
    "branch_id": 5,
    "sales_strategy_id": 1,
    "success_payment_url": "https://myshop.ru/success"
}
```

#### Ответ

Возвращает HTTP код `201` и созданный объект `application`. Поле `token` содержит App Token для запросов к E-Commerce API.


### Получение выбранного приложения

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/applications/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "application": {
        "id": 1,
        "branch": { "id": 5, "name": "Главный филиал" },
        "is_website": false,
        "photo": null,
        "code": 123456,
        "name": "Интернет-магазин",
        "is_token_active": true,
        "wholesale": false,
        "token": "abc123token",
        "success_payment_url": "https://myshop.ru/success",
        "warehouses": [{ "id": 3, "name": "Склад №1" }],
        "sales_strategy": { "id": 1, "name": "Стандартная" }
    }
}
```

##### Описание полей

- `branch` — объект филиала (`id`, `name`)
- `is_website` *(bool)* — является ли приложение сайтом
- `photo` — объект файла-обложки (или `null`)
- `code` — уникальный код приложения
- `name` — название приложения
- `is_token_active` *(bool)* — активен ли API-токен приложения
- `wholesale` *(bool)* — работает ли приложение в оптовом режиме
- `token` *(string|null)* — API-токен приложения для E-Commerce запросов
- `success_payment_url` *(string|null)* — URL редиректа после успешной оплаты
- `warehouses` — массив складов, привязанных к приложению
- `sales_strategy` *(object|null)* — стратегия продаж (`id`, `name`)


## Подписочные тарифы приложения

Эти методы нужны для экрана настройки тарифов ЭПС. Они не меняют общую номенклатуру и не влияют на клиентский checkout напрямую: приложение показывает клиенту только активные назначенные тарифы.

Для чтения и изменения нужен пользователь ERP из того же проекта с правом `edit-applications`.

### Каталог тарифов для настройки приложения

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/applications/{application}/subscription-nomenclatures/catalog`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

Возвращает все подписочные тарифы проекта и привязку каждого тарифа к выбранному приложению.

```json
{
    "data": [
        {
            "nomenclature": {
                "id": 34786,
                "name": "Uhoster — 1 месяц",
                "parent_nomenclature_id": 34780,
                "variant_label": "1 месяц",
                "variant_sort_order": 10,
                "price": "490.00",
                "billing_period_months": 1
            },
            "assignment": {
                "id": 42,
                "is_active": true,
                "sort_order": 0
            }
        }
    ],
    "meta": {
        "application_id": 275,
        "subscription_catalog_configured": true
    }
}
```

##### Описание полей

- `nomenclature` — тариф из общего справочника проекта.
- `price` *(string)* — цена тарифа. Строковый формат сохраняет точность денежных значений.
- `parent_nomenclature_id` — ID родительского тарифа для варианта или `null`.
- `assignment` — привязка тарифа к этому приложению. `null` означает, что тариф ещё не добавлен; объект с `is_active: false` означает, что он добавлен, но выключен.
- `sort_order` — порядок показа активных тарифов в клиентском каталоге.
- `subscription_catalog_configured` — включён ли у приложения режим управляемого каталога.

Варианты и родительские тарифы назначаются независимо. Если в старых данных доступен вариант, а его родитель недоступен, фронт показывает такой вариант самостоятельной группой.


### Назначить подписочный тариф приложению

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/applications/{application}/subscription-nomenclatures`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Тело запроса

```json
{
    "nomenclature_id": 34786,
    "is_active": true,
    "sort_order": 0
}
```

- `nomenclature_id` *(integer, обязательно)* — ID подписочного тарифа из management-каталога текущего проекта.
- `is_active` *(boolean, опционально, по умолчанию `true`)* — доступен ли тариф клиентам.
- `sort_order` *(integer, опционально, по умолчанию `0`)* — порядок в каталоге.

#### Ответ

HTTP `200` с созданной или обновлённой привязкой. Повторный POST того же тарифа не создаёт дубль, а обновляет существующую привязку.


### Изменить привязку подписочного тарифа

**Метод:** PATCH  
**URL:** `https://api.gigma.ru/api/applications/{application}/subscription-nomenclatures/{assignment}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Тело запроса

```json
{
    "is_active": false,
    "sort_order": 10
}
```

Можно передать `is_active`, `sort_order` или оба поля. `assignment` — ID объекта `assignment` из management-каталога, а не ID номенклатуры.

#### Ответ

HTTP `200` с обновлённой привязкой.


### Удалить привязку подписочного тарифа

**Метод:** DELETE  
**URL:** `https://api.gigma.ru/api/applications/{application}/subscription-nomenclatures/{assignment}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

HTTP `200`:

```json
{
    "message": "Subscription nomenclature assignment deleted"
}
```

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


## Вебхуки приложения

Webhook приложения отправляет событие `order.paid` во внешний бэкенд после подтверждённой оплаты заказа. Это дополнительная возможность, а не обязательная часть подключения через собственный бэкенд. Настройка доступна только ERP-пользователю роли `owner` или `admin` из того же проекта.

### Получение списка вебхуков

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/applications/{application}/webhooks`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200` с массивом вебхуков приложения.


### Создание вебхука

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/applications/{application}/webhooks`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `event` *(string, обязательно)* — сейчас поддерживается только `order.paid`.
- `url` *(string, обязательно, до 2048 символов)* — публичный HTTPS URL receiver. Приватные IP, небезопасные redirects и локальные адреса отклоняются.
- `secret` *(string, обязательно, от 16 до 512 символов)* — общий секрет для HMAC-подписи. В ответах значение не раскрывается.
- `headers` *(object|null, опционально, до 10 заголовков)* — дополнительные разрешённые заголовки доставки.
- `is_active` *(boolean, опционально, по умолчанию `true`)* — включить доставку.

#### Пример запроса

```json
{
    "event": "order.paid",
    "url": "https://service.example.com/api/webhooks/gigma",
    "secret": "replace-with-a-long-random-secret",
    "headers": {
        "X-Service": "billing"
    },
    "is_active": true
}
```

#### Ответ

При успешном действии возвращается HTTP код `201` с созданным webhook. Поле `secret` не возвращается; `has_secret: true` подтверждает, что секрет сохранён.


### Получение выбранного вебхука

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/applications/{application}/webhooks/{webhook}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200` с объектом вебхука.


### Обновление вебхука

**Метод:** PATCH  
**URL:** `https://api.gigma.ru/api/applications/{application}/webhooks/{webhook}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `url` *(string, опционально)* — новый публичный HTTPS URL.
- `headers` *(object|null, опционально)* — заменить дополнительные заголовки.
- `is_active` *(boolean, опционально)* — включить или выключить доставку.

`event` после создания не меняется. `secret` нельзя передавать в PATCH — используйте отдельную ротацию.

#### Пример запроса

```json
{
    "is_active": false
}
```

#### Ответ

При успешном действии возвращается HTTP код `200` с обновлённым вебхуком.


### Удаление вебхука

**Метод:** DELETE  
**URL:** `https://api.gigma.ru/api/applications/{application}/webhooks/{webhook}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200`. Webhook архивируется и выключается; журнал доставок сохраняется.


### Получение доставок вебхука

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/applications/{application}/webhooks/{webhook}/deliveries`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200` с пагинированной историей доставок.


### Повторная доставка вебхука

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/applications/{application}/webhooks/{webhook}/deliveries/{delivery}/resend`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200`. Вручную повторить можно только доставку в статусе `failed`; для других состояний backend возвращает `422`.


### Ротация секрета вебхука

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/applications/{application}/webhooks/{webhook}/rotate-secret`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

Генерирует новый 64-символьный секрет для следующих доставок. Ротация ограничена одним запросом в 60 секунд.

#### Ответ

При успешном действии возвращается HTTP код `200` с новым секретом.


### Контракт доставки `order.paid`

Gigma отправляет POST на настроенный URL с JSON body и заголовками:

```http
Content-Type: application/json
X-Webhook-Event: order.paid
X-Webhook-Event-Id: order.paid:<order_id>:<opaque_payment_part>
X-Webhook-Delivery-Id: <delivery_id>
X-Webhook-Timestamp: <unix_timestamp>
X-Signature: sha256=<hex_hmac>
```

Подпись рассчитывается по исходному телу запроса:

```text
expected = "sha256=" + HMAC_SHA256(secret, timestamp + "." + raw_body)
```

Перед обработкой проверьте полный `X-Signature` по `raw_body`. Gigma считает доставку успешной при любом ответе `2xx`. При ином ответе или транспортной ошибке она повторяет ту же delivery через `1`, `5`, `30`, `120` и `720` минут.

`event_id` — непрозрачный ключ идемпотентности: сохраните его и не обрабатывайте одно событие дважды. `event_id` и `X-Webhook-Delivery-Id` не меняются между попытками, а timestamp и HMAC вычисляются заново. Возвращайте `2xx` только после того, как событие принято вашим бэкендом.

Пример payload:

```json
{
	"event": "order.paid",
	"event_id": "order.paid:456:2f8d...",
	"occurred_at": "2026-07-18T10:00:00+00:00",
	"order": {
		"id": 456,
		"final_price": "990.00",
		"paid_at": "2026-07-18T10:00:00+00:00",
		"products": [
			{
				"id": 34786,
				"name": "AI assistant monthly",
				"quantity": 1
			}
		]
	},
	"counterparty": {
		"id": 123,
		"phone_1": "79999999990",
		"email": null
	},
	"shop": {
		"id": 10
	}
}
```

Webhook сообщает об оплате, но не заменяет проверку актуального состояния. Для выдачи доступа используйте [правило на странице списка подписок](/E-Commerce/Заказы/#subscriptions-list).

## Категории приложения

### Получение списка категорий приложения (табличное)

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/tables/applications/{id}/categories`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200`.


### Получение списка категорий приложения

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/applications/{id}/categories`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200`.


### Добавление категории в приложение

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/applications/{id}/categories`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `category_id` — ID категории

#### Ответ

При успешном действии возвращается HTTP код `200`.


### Получение категории приложения

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/applications/{id}/categories/{category_id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200`.


### Удаление категории из приложения

**Метод:** DELETE  
**URL:** `https://api.gigma.ru/api/applications/{id}/categories/{category_id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200` с сообщением подтверждения.


### Повышение приоритета категории

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/applications/{id}/categories/{category_id}/up`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200`.


### Понижение приоритета категории

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/applications/{id}/categories/{category_id}/down`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200`.


## Бренды приложения

### Получение списка брендов приложения (табличное)

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/tables/applications/{id}/brands`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200`.


### Получение списка брендов приложения

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/applications/{id}/brands`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200`.


### Добавление бренда в приложение

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/applications/{id}/brands`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `brand_id` — ID бренда

#### Ответ

При успешном действии возвращается HTTP код `200`.


### Получение бренда приложения

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/applications/{id}/brands/{brand_id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200`.


### Удаление бренда из приложения

**Метод:** DELETE  
**URL:** `https://api.gigma.ru/api/applications/{id}/brands/{brand_id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200` с сообщением подтверждения.


### Повышение приоритета бренда

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/applications/{id}/brands/{brand_id}/up`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200`.


### Понижение приоритета бренда

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/applications/{id}/brands/{brand_id}/down`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200`.


## Пункты меню

### Получение списка пунктов меню (табличное)

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/tables/applications/{id}/menu_items`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200`.


### Создание пункта меню

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/applications/{id}/menu_items`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `name` — название пункта меню
- `slug` — slug
- `parent_id` — ID родительского пункта
- `avatar_id` — ID файла аватара
- `preview_id` — ID файла превью

#### Ответ

При успешном действии возвращается HTTP код `200`.


### Обновление пункта меню

**Метод:** PUT  
**URL:** `https://api.gigma.ru/api/applications/{id}/menu_items/{menu_item_id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Те же параметры, что и в эндпоинте создания.

#### Ответ

При успешном действии возвращается HTTP код `200`.


### Удаление пункта меню

**Метод:** DELETE  
**URL:** `https://api.gigma.ru/api/applications/{id}/menu_items/{menu_item_id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200` с сообщением подтверждения.


### Повышение приоритета пункта меню

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/applications/{id}/menu_items/{menu_item_id}/up`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200`.


### Понижение приоритета пункта меню

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/applications/{id}/menu_items/{menu_item_id}/down`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200`.

---

## Каталог товаров и услуг

Source: https://docs.gigma.ru/ERP/%D0%9D%D0%BE%D0%BC%D0%B5%D0%BD%D0%BA%D0%BB%D0%B0%D1%82%D1%83%D1%80%D0%B0/

# Номенклатура

Раздел API для управления номенклатурой системы ERP: категории товаров, теги, типы, виды и сами позиции номенклатуры.

## Категории

### Получение списка категорий

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/tables/categories`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `page` — текущая страница (пагинация)
- `per_page` — количество элементов на странице
- `query` — поисковая строка
- `date_from` — фильтр по дате добавления (от)
- `date_to` — фильтр по дате добавления (до)

#### Пример запроса

```
https://api.gigma.ru/api/tables/categories?query=сей&date_from=30-01-2024
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

Возвращает данные категорий с метаданными столбцов, объекты категорий, содержащие: `id`, `code`, `date`, `parent`, `name` (с иконкой), `creator` (с иконкой), `type`, и информацию о пагинации.


### Получение выбранной категории

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/tables/categories/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200`.

Возвращает один объект категории с полями: `id`, `code`, `name`, `description`, `parent`, `photo`, `avatar`, `tags`.


### Обновление выбранной категории

**Метод:** PUT  
**URL:** `https://api.gigma.ru/api/categories/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `code` — уникальный системный код
- `name` — название категории
- `description` — описание в формате HTML
- `parent_id` — родительская категория
- `avatar_id` — ID файла аватара
- `photo_id` — ID файла фотографии
- `tag_id[]` — массив ID тегов

#### Ответ

При успешном действии возвращается HTTP код `200`.


### Добавление категории

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/categories`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

⚠ Реальный minimum (сверено): только `name`. `code` рекомендуется задавать вручную для дедупа, но бэкенд его не требует.

- `name` *(string, обязательно)* — название категории
- `code` *(string, опционально)* — уникальный системный код категории
- `description` *(string, опционально)* — описание в формате HTML
- `parent_id` *(int, опционально)* — ID родительской категории (для вложенности)
- `avatar_id` *(int, опционально)* — ID файла аватара (из `POST /api/files`)
- `photo_id` *(int, опционально)* — ID файла основной фотографии
- `tag_id` *(int[], опционально)* — массив ID тегов

#### Пример запроса

```json
{
    "code": "CAT-001",
    "name": "Косметика",
    "description": "<p>Категория косметической продукции</p>",
    "parent_id": 1,
    "avatar_id": 42,
    "photo_id": 43,
    "tag_id": [1, 2]
}
```

#### Ответ

При успешном действии возвращается HTTP код `201` с созданным объектом категории.

```json
{
    "category": {
        "id": 17,
        "code": "CAT-001",
        "name": "Косметика",
        "description": "<p>Категория косметической продукции</p>",
        "parent": { "id": 1, "name": "Товары для дома" },
        "avatar": { "id": 42, "path": "https://api.gigma.ru/storage/uploads/abc.jpg" },
        "photo": { "id": 43, "path": "https://api.gigma.ru/storage/uploads/def.jpg" },
        "tags": [{ "id": 1, "name": "новинка" }, { "id": 2, "name": "хит" }],
        "created_at": "2026-05-16T07:00:00.000000Z",
        "updated_at": "2026-05-16T07:00:00.000000Z"
    }
}
```


### Получение истории изменений категории

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/categories/{id}/history`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200`.

Возвращает массив объектов истории с полями: `id`, `icon`, `color`, `title`, `description`, `datetime`, `historiesCount`.


## Теги

### Получение списка тегов

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/tags`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200`.

Возвращает массив тегов с полями: `id`, `name`, `avatar` (URL), `created_at`, `tagsCount`.


## Типы

### Получение списка типов номенклатуры

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/nomenclature_types`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200`.

Возвращает типы номенклатуры с полями: `id`, `name`, `avatar`, `created_at`, `nomenclatureTypesCount`.


## Виды

### Получение списка видов номенклатуры

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/nomenclature_kinds`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200`.

Возвращает массив видов с полями: `id`, `name`, `avatar`, `created_at`, `nomenclatureKindsCount`.


## Номенклатура

### Получение списка номенклатуры (табличное представление)

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/tables/nomenclatures`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `query` — поисковая строка
- `type_id[]` — фильтр по ID типов
- `kind_id[]` — фильтр по ID видов
- `is_import` — boolean (1 — импортные, 0 — отечественные)

#### Ответ

При успешном действии возвращается HTTP код `200`.

Возвращает метаданные столбцов и позиции номенклатуры с полями: `id`, `code`, `name`, `type`, `kind`, `brand`, `unit`, `is_import`, `country`.


### Получение списка номенклатуры

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/nomenclatures`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Те же параметры, что и для табличного представления, плюс `page` и `per_page`.

#### Ответ

При успешном действии возвращается HTTP код `200`.

Возвращает данные номенклатуры с пагинацией. Объекты содержат: `id`, `code`, `name`, `avatar`, `preview`, `description`, `category`, `specification`, `country`, `type`, `kind`, `branch`, `tags`, `photos`, `unit`, `brand`, `price`, `cost_price`, `discount`, `vat`, `markup`, `pieces_per_pack`, `is_subscription`, `billing_period_months`, `parent_nomenclature_id`, `variant_label`, `variant_sort_order`, временные метки создания и обновления.


### Добавление позиции номенклатуры

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/nomenclatures`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

⚠ **Реальный minimum** (сверено через `POST {}` → 422): `name` + `kind_id`. Остальные технически опциональны, но для боевого создания обычно нужны `code`, `type_id`, `storage_unit_id`, `vat_id`, `price`.

- `name` *(string, обязательно)* — наименование позиции
- `kind_id` *(int, обязательно)* — ID вида (1=Услуга, 2=Товар; `GET /api/nomenclature_kinds`)
- `code` *(string, опционально)* — уникальный SKU позиции (рекомендуется ставить вручную)
- `type_id` *(int, опционально)* — ID типа (`GET /api/nomenclature_types`)
- `storage_unit_id` *(int, опционально)* — ID единицы измерения (`GET /api/storage_units` — **не** `/api/units`)
- `vat_id` *(int, опционально)* — ID ставки НДС (`GET /api/vats`)
- `price` *(string, опционально)* — цена в формате decimal-string, 2 знака (`"1000.00"`). Для услуг — обязательно по бизнес-логике.
- `category_id` *(int, опционально)* — ID категории (`GET /api/categories`)
- `brand_id` *(int, опционально)* — ID бренда (`GET /api/brands`)
- `country_id` *(int, опционально)* — ID страны производства
- `branch_id` *(int, опционально)* — ID бизнеса/филиала
- `description` *(string, опционально)* — HTML-описание для карточки
- `specification` *(string, опционально)* — HTML-характеристики
- `cost_price` *(string, опционально)* — себестоимость, decimal-string
- `markup` *(int, опционально)* — процент наценки
- `discount` *(int, опционально)* — процент скидки
- `avatar_id` *(int, опционально)* — ID файла-аватара (из `POST /api/files` c `file_type_id=2`)
- `preview_id` *(int, опционально)* — ID файла превью-картинки
- `photos` *(object[], опционально)* — массив дополнительных фото: `[{photo_id, order}]`
- `tags` *(int[], опционально)* — массив ID тегов

#### Пример запроса

```json
{
    "code": "SKU-001",
    "name": "Крем для лица «Нежность»",
    "kind_id": 2,
    "type_id": 1,
    "storage_unit_id": 1,
    "vat_id": 2,
    "price": "1000.00",
    "category_id": 17,
    "brand_id": 7,
    "country_id": 3,
    "branch_id": 5,
    "description": "<p>Увлажняющий крем с гиалуроновой кислотой.</p>",
    "specification": "<p>Объём: 50 мл. Срок годности: 24 месяца.</p>",
    "cost_price": "700.00",
    "markup": 30,
    "discount": 0,
    "avatar_id": 42,
    "preview_id": 43,
    "photos": [
        { "photo_id": 44, "order": 1 },
        { "photo_id": 45, "order": 2 }
    ],
    "tags": [1, 2]
}
```

#### Ответ

При успешном действии возвращается HTTP код `201` с созданным объектом номенклатуры.

```json
{
    "nomenclature": {
        "id": 100,
        "code": "SKU-001",
        "name": "Крем для лица «Нежность»",
        "kind": { "id": 2, "name": "Товар" },
        "type": { "id": 1, "name": "Простой" },
        "unit": { "id": 1, "name": "Штука" },
        "vat": { "id": 2, "rate": 20 },
        "price": "1000.00",
        "cost_price": "700.00",
        "markup": 30,
        "discount": 0,
        "category": { "id": 17, "name": "Косметика" },
        "brand": { "id": 7, "name": "Nivea" },
        "country": { "id": 3, "name": "Россия" },
        "branch": { "id": 5, "name": "Главный филиал" },
        "description": "<p>...</p>",
        "specification": "<p>...</p>",
        "avatar": { "id": 42, "path": "https://api.gigma.ru/storage/uploads/avatar.jpg" },
        "preview": { "id": 43, "path": "https://api.gigma.ru/storage/uploads/preview.jpg" },
        "photos": [
            { "id": 44, "path": "https://api.gigma.ru/storage/uploads/p1.jpg", "order": 1 },
            { "id": 45, "path": "https://api.gigma.ru/storage/uploads/p2.jpg", "order": 2 }
        ],
        "tags": [{ "id": 1, "name": "новинка" }, { "id": 2, "name": "хит" }],
        "created_at": "2026-05-16T07:00:00.000000Z",
        "updated_at": "2026-05-16T07:00:00.000000Z"
    }
}
```


### Обновление позиции номенклатуры

**Метод:** PUT  
**URL:** `https://api.gigma.ru/api/nomenclatures/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Те же параметры, что и в эндпоинте добавления.

#### Ответ

При успешном действии возвращается HTTP код `200`.


### Получение выбранной позиции номенклатуры

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/nomenclatures/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200`.

Возвращает полный объект позиции со всеми полями: `id`, `code`, `name`, `avatar`, `preview`, `description`, `category`, `specification`, `country`, `type`, `kind`, `branch`, `tags`, `photos`, `unit`, `brand`, `price`, `cost_price`, `discount`, `vat`, `markup`, `pieces_per_pack`, `is_subscription`, `billing_period_months`, `parent_nomenclature_id`, `variant_label`, `variant_sort_order`, временные метки.

##### Описание дополнительных полей

- `pieces_per_pack` *(int)* — количество единиц в упаковке
- `is_subscription` *(bool)* — является ли позиция подпиской (recurring billing)
- `billing_period_months` *(int|null)* — период подписки в месяцах (заполнено только если `is_subscription = true`)
- `parent_nomenclature_id` *(int|null)* — ID родительской позиции (для вариантов товара)
- `variant_label` *(string|null)* — метка варианта (напр. «Красный / L»)
- `variant_sort_order` *(int|null)* — порядок отображения среди вариантов


### Получение истории изменений позиции номенклатуры

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/nomenclatures/{id}/history`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200`.

Возвращает массив истории с полями: `id`, `icon`, `color`, `title`, `description`, `datetime`.


## Экспорт и импорт

### Экспорт файла номенклатуры

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/nomenclatures/export`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200`.


### Импорт файла номенклатуры

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/nomenclatures/import`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200` со статусом импорта и описанием полей.

---

## Склады

Source: https://docs.gigma.ru/ERP/%D0%A1%D0%BA%D0%BB%D0%B0%D0%B4%D1%8B/

# Склады

### Получение списка складов

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/tables/warehouses`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `owned_by_us` — иерархия (принадлежность) склада: свой (true), чужой (false)
- `type_id[]` — массив ID типов хранимых товаров
- `city_id[]` — массив ID городов
- `page` — текущая страница (для пагинации)
- `per_page` — кол-во элементов на странице
- `query` — поисковая строка
- `date_from` — "дата с..." (от даты добавления в систему)
- `date_to` — "дата по..." (от даты добавления в систему)

#### Пример запроса

```
https://api.gigma.ru/api/tables/warehouses?query=коледино&owned_by_us=0&storage_unit_id[]=1&city_id[]=1
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "columns": [
        {
            "id": 81,
            "table_id": 11,
            "order": 0,
            "key": "id",
            "has_icon": 0,
            "text": "№"
        },
        {
            "id": 82,
            "table_id": 11,
            "order": 1,
            "key": "name",
            "has_icon": 1,
            "text": "Название"
        },
        {
            "id": 83,
            "table_id": 11,
            "order": 2,
            "key": "owner",
            "has_icon": 0,
            "text": "Принадлежность"
        },
        {
            "id": 84,
            "table_id": 11,
            "order": 3,
            "key": "city",
            "has_icon": 0,
            "text": "Город"
        },
        {
            "id": 85,
            "table_id": 11,
            "order": 4,
            "key": "creator",
            "has_icon": 1,
            "text": "Добавил"
        },
        {
            "id": 86,
            "table_id": 11,
            "order": 5,
            "key": "storage_capacity",
            "has_icon": 0,
            "text": "Емкость"
        }
    ],
    "warehouses": [
        {
            "id": 3,
            "name": {
                "icon": "http://localhost:8000/storage/uploads/default.svg",
                "value": "Коледино WB"
            },
            "owner": "Чужой",
            "city": "Москва",
            "creator": {
                "icon": "http://localhost:8000/storage/uploads/default.svg",
                "value": "Полищук Артём"
            },
            "storage_capacity": 5000000,
            "storage_unit": "Литр"
        }
    ],
    "pagination": {
        "total": 1,
        "per_page": 10,
        "current_page": 1,
        "last_page": 1,
        "from": 1,
        "to": 1
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ (номер склада)
- `name` — название склада
- `owner` — принадлежность склада (свой/чужой)
- `city` — город
- `creator` — добавил в систему
- `storage_capacity` — объем склада
- `storage_unit` — единицы измерения


### Получение выбранного склада

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/warehouses/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/warehouses/1
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "warehouse": {
        "id": 1,
        "name": "Подольск",
        "avatar": null,
        "code": 1,
        "owned_by_us": false,
        "address": "Троицкая улица, 20, деревня Коледино, городской округ Подольск, Московская область",
        "storage_capacity": 5000000,
        "storage_unit": {
            "id": 1,
            "name": "Литр",
            "abbreviation": "л"
        },
        "city": {
            "id": 1,
            "name": "Москва",
            "avatar": "http://localhost:8000/storage/uploads/default.svg",
            "created_at": "2024-04-19T09:18:41.000000Z"
        },
        "counterparty": {
            "id": 54,
            "type": {
                "id": 2,
                "name": "Поставщик",
                "avatar": "http://localhost:8000/storage/uploads/default.svg",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            "manager": {
                "id": 1,
                "first_name": "Артём",
                "last_name": "Полищук",
                "middle_name": "Николаевич",
                "name": "Полищук Артём"
            },
            "avatar": null,
            "name": "ООО \"НЕТФЛИКС\"",
            "registered_at": "2008-10-20",
            "inn": "7743277284",
            "kpp": null,
            "head": "Чуйков Андрей Николаевич",
            "legal_address": "г Москва, ул Адмирала Макарова, д 8 стр 1, помещ V ком 15, 15",
            "phone_1": "71231412412",
            "phone_2": "74416763277",
            "email": "asdaslow@gmail.com",
            "created_at": "2024-06-11T15:00:33.000000Z",
            "updated_at": "2024-06-11T19:33:38.000000Z"
        }
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ (номер склада)
- `avatar` — объект с информацией об аватаре/фотографии склада (или `null`)
- `code` — уникальный код склада
- `owned_by_us` — принадлежность склада (свой/чужой)
- `address` — адрес склада
- `city` — объект с информацией о городе
- `counterparty` — объект с информацией о контрагенте
- `storage_capacity` — объем склада
- `storage_unit` — объект с информацией о единицах измерения


### Добавление склада

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/warehouses`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `photo_id` — ID файла аватара/фотографии склада (в ответе возвращается как поле `avatar`)
- `name` — название склада
- `code` — уникальный код склада
- `owned_by_us` — принадлежность склада (свой/чужой)
- `address` — адрес склада
- `city_id` — ID города
- `storage_capacity` — объем склада (целочисленное значение)
- `storage_unit_id` — ID единиц измерения
- `counterparty_id` — ID поставщика

#### Пример запроса

```
https://api.gigma.ru/api/warehouses
```

```json
{
    "photo_id": 1,
    "code": 1,
    "name": "Коледино WB",
    "owned_by_us": false,
    "address": "Троицкая улица, 20, деревня Коледино, городской округ Подольск, Московская область",
    "storage_capacity": 5000000,
    "storage_unit_id": 1,
    "city_id": 1,
    "counterparty_id": 54
}
```

#### Ответ

При успешном действии возвращается HTTP код `201`.

```json
{
    "warehouse": {
        "id": 5,
        "name": "Подольск",
        "avatar": null,
        "code": 1,
        "owned_by_us": false,
        "address": "Троицкая улица, 20, деревня Коледино, городской округ Подольск, Московская область",
        "storage_capacity": 5000000,
        "storage_unit": {
            "id": 1,
            "name": "Литр",
            "abbreviation": "л"
        },
        "city": {
            "id": 1,
            "name": "Москва",
            "avatar": "http://localhost:8000/storage/uploads/default.svg",
            "created_at": "2024-04-19T09:18:41.000000Z"
        },
        "counterparty": {
            "id": 54,
            "type": {
                "id": 2,
                "name": "Поставщик",
                "avatar": "http://localhost:8000/storage/uploads/default.svg",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            "manager": {
                "id": 1,
                "first_name": "Артём",
                "last_name": "Полищук",
                "middle_name": "Николаевич",
                "name": "Полищук Артём"
            },
            "avatar": null,
            "name": "ООО \"НЕТФЛИКС\"",
            "registered_at": "2008-10-20",
            "inn": "7743277284",
            "kpp": null,
            "head": "Чуйков Андрей Николаевич",
            "legal_address": "г Москва, ул Адмирала Макарова, д 8 стр 1, помещ V ком 15, 15",
            "phone_1": "71231412412",
            "phone_2": "74416763277",
            "email": "asdaslow@gmail.com",
            "created_at": "2024-06-11T15:00:33.000000Z",
            "updated_at": "2024-06-11T19:33:38.000000Z"
        }
    }
}
```

##### Описание полей ответа

Возвращаемые поля аналогичны запросу "Получение выбранного склада".


### Редактирование склада

**Метод:** PUT  
**URL:** `https://api.gigma.ru/api/warehouses/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `photo_id` — ID файла аватара/фотографии склада (в ответе возвращается как поле `avatar`)
- `name` — название склада
- `code` — уникальный код склада
- `owned_by_us` — принадлежность склада (свой/чужой)
- `address` — адрес склада
- `city_id` — ID города
- `storage_capacity` — объем склада (целочисленное значение)
- `storage_unit_id` — ID единиц измерения
- `counterparty_id` — ID поставщика (использовать с ID типа = 2 "Поставщик")

#### Пример запроса

```
https://api.gigma.ru/api/warehouses/1
```

```json
{
    "photo_id": 1,
    "code": 1,
    "name": "Коледино WB",
    "owned_by_us": false,
    "address": "Троицкая улица, 20, деревня Коледино, городской округ Подольск, Московская область",
    "storage_capacity": 5000000,
    "storage_unit_id": 1,
    "city_id": 1,
    "counterparty_id": 54
}
```

#### Ответ

При успешном действии возвращается HTTP код `201`.

```json
{
    "warehouse": {
        "id": 5,
        "name": "Коледино WB",
        "avatar": null,
        "code": 1,
        "owned_by_us": false,
        "address": "Троицкая улица, 20, деревня Коледино, городской округ Подольск, Московская область",
        "storage_capacity": 5000000,
        "storage_unit": {
            "id": 1,
            "name": "Литр",
            "abbreviation": "л"
        },
        "city": {
            "id": 1,
            "name": "Москва",
            "avatar": "http://localhost:8000/storage/uploads/default.svg",
            "created_at": "2024-04-19T09:18:41.000000Z"
        },
        "counterparty": {
            "id": 54,
            "type": {
                "id": 2,
                "name": "Поставщик",
                "avatar": "http://localhost:8000/storage/uploads/default.svg",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            "manager": {
                "id": 1,
                "first_name": "Артём",
                "last_name": "Полищук",
                "middle_name": "Николаевич",
                "name": "Полищук Артём"
            },
            "avatar": null,
            "name": "ООО \"НЕТФЛИКС\"",
            "registered_at": "2008-10-20",
            "inn": "7743277284",
            "kpp": null,
            "head": "Чуйков Андрей Николаевич",
            "legal_address": "г Москва, ул Адмирала Макарова, д 8 стр 1, помещ V ком 15, 15",
            "phone_1": "71231412412",
            "phone_2": "74416763277",
            "email": "asdaslow@gmail.com",
            "created_at": "2024-06-11T15:00:33.000000Z",
            "updated_at": "2024-06-11T19:33:38.000000Z"
        }
    }
}
```

##### Описание полей ответа

Возвращаемые поля аналогичны запросу "Получение выбранного склада".


### Удаление склада

**Метод:** DELETE  
**URL:** `https://api.gigma.ru/api/warehouses/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/warehouses/1
```

#### Ответ

При успешном действии возвращается HTTP код `201`.

```json
{
    "message": "Warehouse deleted."
}
```

##### Описание полей ответа

- `message` — информационное поле


## Интеграции

### Получение списка интеграций

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/warehouses/{id}/integrations`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/warehouses/7/integrations
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "integrations": [
        {
            "id": 1,
            "integration_id": 10,
            "name": "Wildberries",
            "avatar": "http://localhost:8000/storage/uploads/default.svg",
            "is_active": 0
        },
        {
            "id": 2,
            "integration_id": 11,
            "name": "Ozon",
            "avatar": "http://localhost:8000/storage/uploads/default.svg",
            "is_active": 0
        },
        {
            "id": 3,
            "integration_id": 12,
            "name": "Яндекс Маркет",
            "avatar": "http://localhost:8000/storage/uploads/default.svg",
            "is_active": 0
        },
        {
            "id": 4,
            "integration_id": 13,
            "name": "Купер",
            "avatar": "http://localhost:8000/storage/uploads/default.svg",
            "is_active": 0
        }
    ],
    "integrationsCount": 4
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `integration_id` — ID интеграции
- `name` — название интеграции
- `avatar` — URL-адрес фотографии
- `is_active` — статус (false — неактивна; true — активна)


### Обновление статуса выбранной интеграции

**Метод:** PUT  
**URL:** `https://api.gigma.ru/api/warehouses/{id}/integrations/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `is_active` — булевый флаг, означающий текущий статус интеграции

#### Пример запроса

```
https://api.gigma.ru/api/warehouses/7/integrations/1
```

```json
{
    "is_active": 1
}
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "integration": {
        "id": 1,
        "integration_id": 10,
        "name": "Wildberries",
        "avatar": "http://localhost:8000/storage/uploads/default.svg",
        "is_active": 1
    }
}
```

##### Описание полей ответа

Возвращаемые поля аналогичны ответу "Получение списка интеграций".


### Получение списка параметров интеграции

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/warehouses/{id}/integrations/{id}/parameters`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/warehouses/7/integrations/1/parameters
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "parameters": [
        {
            "id": 2,
            "key_1": "login",
            "description_1": "Логин/ID",
            "key_2": "password",
            "description_2": "Пароль",
            "value_1": "dsfsdfdsf",
            "value_2": "sdfdsfsd"
        }
    ],
    "parametersCount": 1
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `key_1` — ключ 1
- `description_1` — описание 1
- `key_2` — ключ 2
- `description_2` — описание 2
- `value_1` — значение 1
- `value_2` — значение 2


### Добавление параметров для выбранной интеграции

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/warehouses/{id}/integrations/{id}/parameters`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `integration_parameter_id` — ID параметра интеграции
- `value_1` — значение 1
- `value_2` — значение 2

#### Пример запроса

```
https://api.gigma.ru/api/warehouses/7/integrations/1/parameters
```

```json
{
    "integration_parameter_id": 10,
    "value_1": "83432434234",
    "value_2": "sdfdsxcvxcvfsd"
}
```

#### Ответ

При успешном действии возвращается HTTP код `201`.

```json
{
    "parameter": {
        "id": 2,
        "key_1": "login",
        "description_1": "Логин/ID",
        "key_2": "password",
        "description_2": "Пароль",
        "value_1": "dsfsdfdsf",
        "value_2": "sdfdsfsd"
    }
}
```

##### Описание полей ответа

Возвращаемые поля аналогичны ответу "Получение списка параметров интеграции".


### Удаление параметров из выбранной интеграции

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/warehouses/{id}/integrations/{id}/parameters/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/warehouses/7/integrations/1/parameters/1
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "message": "Parameter successfully deleted."
}
```

##### Описание полей ответа

- `message` — информационное сообщение


### Получение истории изменений

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/warehouses/{id}/history`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/warehouses/7/history
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "histories": [
        {
            "id": 283,
            "icon": "check",
            "color": "primary",
            "title": "Создание",
            "description": "Создание: Полищук Артём",
            "datetime": "15.07.2024 05:46"
        },
        {
            "id": 284,
            "icon": "edit",
            "color": "success",
            "title": "Редактирование",
            "description": "Редактирование: Полищук Артём",
            "datetime": "15.07.2024 07:06"
        }
    ],
    "historiesCount": 2
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `icon` — иконка
- `color` — цвет
- `title` — заголовок
- `description` — описание
- `datetime` — дата выполнения действия

---

## Остатки и импорт

Source: https://docs.gigma.ru/ERP/%D0%9E%D1%81%D1%82%D0%B0%D1%82%D0%BA%D0%B8/

# Остатки

Раздел API для управления остатками товаров по складам в системе ERP: просмотр, создание, обновление и импорт записей инвентаря.

### Получение списка остатков (табличное представление)

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/tables/inventories`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `query` — поисковая строка
- `owned_by_us` — иерархия складов (true/false)
- `warehouse_id[]` — массив ID складов
- `type_id[]` — массив ID типов товаров
- `city_id[]` — массив ID городов
- `brand_id[]` — массив ID производителей
- `vat_id[]` — ID НДС
- `application_id[]` — ID приложения

#### Ответ

При успешном действии возвращается HTTP код `200` с массивом `columns`, объектом `warehouseNomenclatures` и данными пагинации.


### Получение списка остатков (JSON)

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/inventories`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

⚠ **Backend bug:** на боевых данных возвращает `IncompleteRead(0 bytes read)` — запрос обрывается без ответа. Причина: нет пагинации (`->get()` без `->paginate()`), при большом каталоге сервер не успевает отдать весь ответ. Пока не починено — используй табличный эндпоинт с пагинацией (`GET /api/tables/inventories?per_page=50`).

#### Ответ

При успешном действии возвращается HTTP код `200` с массивом `inventories`, содержащим полные данные о товарах, количестве, ценах и НДС.


### Создание записи остатка

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/inventories`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

⚠ Реальный minimum (сверено): `nomenclature_id` + `warehouse_id`. Остальные опциональны на уровне валидатора, но `quantity` и `price` обязательны по смыслу.

- `nomenclature_id` *(int, обязательно)* — ID номенклатуры (`GET /api/nomenclatures`)
- `warehouse_id` *(int, обязательно)* — ID склада (`GET /api/warehouses`)
- `code` *(string, опционально)* — код позиции остатка
- `vat_id` *(int, опционально)* — ID ставки НДС (`GET /api/vats`)
- `quantity` *(int, опционально)* — количество в штуках, неотрицательное целое
- `price` *(string, опционально)* — цена в формате decimal-string, 2 знака (`"1000.00"`)
- `discount` *(int, опционально)* — процент скидки, 0–100
- `markup` *(int, опционально)* — процент наценки

#### Пример запроса

```json
{
    "code": "INV-001",
    "warehouse_id": 5,
    "nomenclature_id": 100,
    "vat_id": 2,
    "quantity": 50,
    "price": "1000.00",
    "discount": 0,
    "markup": 30
}
```

#### Ответ

При успешном действии возвращается HTTP код `201` с созданным объектом остатка.

```json
{
    "inventory": {
        "id": 200,
        "code": "INV-001",
        "warehouse": { "id": 5, "name": "Главный склад" },
        "nomenclature": { "id": 100, "name": "Крем для лица «Нежность»", "code": "SKU-001", "avatar": "https://api.gigma.ru/storage/uploads/avatar.jpg" },
        "counterparty": { "id": 3, "name": "ООО Поставщик", "inn": "7712345678", "type_id": 1 },
        "invoice": { "number": "РН-001", "date": "2026-05-16", "row_number": 1 },
        "vat": { "id": 2, "name": "НДС 20%" },
        "vat_rate": "20%",
        "vat_amount": "166.67",
        "quantity": 50,
        "price": "1000.00",
        "line_total_without_vat": "50000.00",
        "line_total_with_vat": "50000.00",
        "currency_code": "RUB",
        "discount": 0,
        "markup": 30,
        "created_at": "2026-05-16T07:00:00.000000Z",
        "updated_at": "2026-05-16T07:00:00.000000Z"
    }
}
```

##### Описание новых полей

- `nomenclature.avatar` *(string|null)* — URL аватара номенклатуры
- `counterparty` *(object|null)* — поставщик: `id`, `name`, `inn`, `type_id`
- `invoice` *(object|null)* — реквизиты накладной: `number`, `date`, `row_number`
- `vat` *(object|null)* — ставка НДС как объект `{id, name}` (не просто число)
- `vat_rate` *(string|null)* — строковое представление ставки («20%», «10%», «0%»)
- `vat_amount` *(string|null)* — сумма НДС по строке, decimal-string
- `line_total_without_vat` *(string|null)* — итого по строке без НДС
- `line_total_with_vat` *(string|null)* — итого по строке с НДС
- `currency_code` *(string|null)* — код валюты ISO 4217 (`"RUB"`)


### Обновление записи остатка

**Метод:** PUT  
**URL:** `https://api.gigma.ru/api/inventories/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Те же параметры, что и в эндпоинте создания.

#### Ответ

При успешном действии возвращается HTTP код `200` с обновлённым объектом остатка.


### Получение выбранного остатка

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/inventories/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200` с полной информацией о складе, номенклатуре, количестве, цене и НДС.


### Получение истории изменений остатка

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/inventories/{id}/history`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200` с записями истории, содержащими `icon`, `color`, `title`, `description`, `datetime`.


### Импорт остатков

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/inventories/upload`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

Два режима в зависимости от `Content-Type`. В обоих режимах `warehouse_id` обязателен.
**Режим А** (`multipart/form-data`): передаётся `file` — Excel `.xmr`.
**Режим Б** (`application/json`): передаётся `items[]` с полями накладной.

⚠ Реальный minimum (сверено через `POST {}` → 422): `warehouse_id` + (`file` **или** `items[]` со всеми полями ниже).

#### Параметры запроса

- `warehouse_id` *(int, обязательно)* — ID склада (`GET /api/warehouses`). Обязателен в обоих режимах.
- `file` *(binary, опционально)* — Excel-файл `.xmr`; режим А. Если передан — поля накладной и `items` не нужны.
- `invoice_number` *(string, опционально)* — номер накладной; обязателен в режиме Б.
- `invoice_date` *(string, опционально)* — дата накладной ISO 8601 (`"2026-05-16"`); обязателен в режиме Б.
- `supplier_inn` *(string, опционально)* — ИНН поставщика; обязателен в режиме Б.
- `supplier_name` *(string, опционально)* — наименование поставщика; обязателен в режиме Б.
- `currency_code` *(string, опционально)* — код валюты ISO 4217 (`"RUB"`); обязателен в режиме Б.
- `items` *(object[], опционально)* — строки накладной; обязателен в режиме Б. Каждая строка:
  - `row_number` *(int, обязательно)* — порядковый номер строки
  - `item_name` *(string, обязательно)* — наименование товара
  - `quantity` *(number, обязательно)* — количество
  - `price` *(string, обязательно)* — цена за единицу, decimal-string (`"4000.00"`)
  - `sum_without_vat` *(string, обязательно)* — сумма без НДС, decimal-string
  - `sum_with_vat` *(string, обязательно)* — сумма с НДС, decimal-string
  - `vat_rate` *(string, обязательно)* — ставка НДС: `"0%"`, `"10%"`, `"20%"`

#### Пример запроса (режим А — файл)

```bash
curl -X POST https://api.gigma.ru/api/inventories/upload \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -F "warehouse_id=1" \
  -F "file=@./inventories.xmr"
```

#### Пример запроса (режим Б — JSON)

```json
{
    "warehouse_id": 1,
    "invoice_number": "РН-001",
    "invoice_date": "2026-05-16",
    "supplier_inn": "7712345678",
    "supplier_name": "ООО Поставщик",
    "currency_code": "RUB",
    "items": [
        {
            "row_number": 1,
            "item_name": "Микрофон Shure SM58",
            "quantity": 5,
            "price": "4000.00",
            "sum_without_vat": "20000.00",
            "sum_with_vat": "20000.00",
            "vat_rate": "0%"
        }
    ]
}
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "message": "Import successful"
}
```

При ошибках формата — `422` с описанием проблемных строк в `errors`.

---

## Резервы товаров

Source: https://docs.gigma.ru/ERP/%D0%A0%D0%B5%D0%B7%D0%B5%D1%80%D0%B2%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5/

# Резервирование

Резерв — это блокировка количества номенклатуры на складе под клиента/заказ. В реальном коде ERP-админки используется только табличное представление и удаление; полный CRUD (создание/редактирование, история) пока не доступен через API.

### Таблица резервов

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/tables/reservations`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Параметры запроса (query string)

- `query` — поисковая строка
- `order_id` — фильтр по ID заказа
- `date_from` — «дата с…» (от даты бронирования)
- `date_to` — «дата по…»
- `page`, `per_page` — пагинация

#### Пример запроса

```
GET https://api.gigma.ru/api/tables/reservations?query=номенклатура&date_from=2025-02-20
```

#### Ответ

```json
{
    "columns": [
        { "id": 178, "table_id": 22, "order": 0, "key": "code", "has_icon": 0, "text": "Код" },
        { "id": 179, "table_id": 22, "order": 1, "key": "order", "has_icon": 0, "text": "Заказ" },
        { "id": 180, "table_id": 22, "order": 2, "key": "created_at", "has_icon": 0, "text": "Дата" },
        { "id": 181, "table_id": 22, "order": 3, "key": "name", "has_icon": 1, "text": "Наименование" },
        { "id": 182, "table_id": 22, "order": 4, "key": "counterparty", "has_icon": 1, "text": "Клиент" },
        { "id": 183, "table_id": 22, "order": 5, "key": "warehouse", "has_icon": 1, "text": "Склад" },
        { "id": 184, "table_id": 22, "order": 6, "key": "source", "has_icon": 1, "text": "Источник" },
        { "id": 185, "table_id": 22, "order": 7, "key": "quantity", "has_icon": 0, "text": "Кол-во" },
        { "id": 186, "table_id": 22, "order": 8, "key": "price", "has_icon": 0, "text": "Цена" },
        { "id": 187, "table_id": 22, "order": 9, "key": "expired_at", "has_icon": 0, "text": "Срок до" },
        { "id": 188, "table_id": 22, "order": 10, "key": "is_active", "has_icon": 0, "text": "Активный" },
        { "id": 189, "table_id": 22, "order": 11, "key": "creator", "has_icon": 1, "text": "Добавил" }
    ],
    "reservations": [
        {
            "id": { "icon": null, "value": 193, "url": "/inventories/list-inventories/57013" },
            "code": { "icon": null, "value": "1", "url": "/inventories/list-inventories/57013" },
            "created_at": "2025-03-07T11:08:52.000000Z",
            "name": {
                "icon": "https://api.gigma.ru/storage/uploads/FCusoYbrnJTaiN8C0bWmNt4HxZLru0ItXEBaH9UW.jpg",
                "value": "Line Repair Nutrient Bio Satin Serum Сыворотка «Био-Сатин», 30 мл",
                "link": "/inventories/list-inventories/57013"
            },
            "counterparty": {
                "icon": "https://api.gigma.ru/storage/uploads/default.svg",
                "value": "Крушанов Александр",
                "link": "/counterparty/list-counterparty/121"
            },
            "warehouse": {
                "icon": "https://api.gigma.ru/storage/uploads/tsLs3JTSLCTFgSyDsdtxFsweHEbTTvn0HeqUepNr.webp",
                "value": "Склад для приложения",
                "link": "/warehouses/list-warehouses/50"
            },
            "source": {
                "icon": "https://api.gigma.ru/storage/uploads/default.svg",
                "value": "Сей момент",
                "link": "/ecommerce/list-ecommerce/37"
            },
            "quantity": 1,
            "price": "2100.00",
            "expired_at": "2025-03-08 08:28:02",
            "is_active": "Да",
            "creator": "-"
        }
    ],
    "pagination": {
        "total": 1,
        "per_page": 10,
        "current_page": 1,
        "last_page": 1,
        "from": 1,
        "to": 1
    }
}
```

##### Описание полей ответа

- `columns[]` — определения колонок таблицы (см. формат в [Бизнесы](/ERP/Бизнесы/#branches-table))
- `reservations[]` — резервы с полями в формате `{ icon, value, link }` для ссылающихся объектов
- `pagination` — стандартный Laravel-пагинатор


### Удаление резерва ⚠ endpoint не существует на бэке

**Метод:** DELETE  
**URL:** `https://api.gigma.ru/api/reservations/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

⚠ **Этот endpoint описан исторически, но реально возвращает 404.** В `itecho-erp-backend` `ReservationController` имеет только метод `tableIndex` (`routes/api.php`: `Route::get('reservations', ...)`). Полного CRUD для резерваций НЕТ.

**Как удалять резерв:** через позицию заказа — `DELETE /api/orders/{order}/nomenclatures/{nomenclatureId}` (это удаляет запись `Reservation`, на которой биндится `{nomenclatureId}` — см. erp-rules §18.7).

#### Параметры запроса

Только `id` резерва в пути URL. **Не работает.**

#### Ответ

`HTTP 404` — `{"message": "The route api/reservations/{id} could not be found."}`

---

## Стратегии продаж

Source: https://docs.gigma.ru/ERP/%D0%A1%D1%82%D1%80%D0%B0%D1%82%D0%B5%D0%B3%D0%B8%D0%B8%20%D0%BF%D1%80%D0%BE%D0%B4%D0%B0%D0%B6/

# Стратегии продаж

Стратегия продаж — справочник вариантов реализации товара (например «Продать остатки», «Новинки»). Используется как фильтр и атрибут в карточках.

### Список стратегий продаж

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/sales_strategies`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Ответ

```json
{
    "salesStrategies": [
        {
            "id": 1,
            "name": "Продать остатки",
            "avatar": "https://api.gigma.ru/storage/uploads/default.svg",
            "created_at": "2024-06-20T10:01:33.000000Z"
        }
    ],
    "salesStrategiesCount": 1
}
```

##### Описание полей ответа

- `salesStrategies[]` — массив стратегий: `id`, `name`, `avatar`, `created_at`
- `salesStrategiesCount` — общее количество


### Стратегия продаж по ID

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/sales_strategies/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Параметры запроса

Только `id` стратегии в пути URL.

#### Ответ

```json
{
    "salesStrategy": {
        "id": 1,
        "name": "Продать остатки",
        "avatar": "https://api.gigma.ru/storage/uploads/default.svg",
        "created_at": "2024-06-20T10:01:33.000000Z"
    }
}
```

---

## Акции и скидки

Source: https://docs.gigma.ru/ERP/%D0%9F%D1%80%D0%BE%D0%BC%D0%BE%D0%B0%D0%BA%D1%86%D0%B8%D0%B8/

# Промоакции и скидки

## Промоакции

### Получение списка промоакций

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/promotions`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `query` — поисковая строка

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "promotions": [
        {
            "id": 1,
            "name": "Тестовая промоакция",
            "avatar": "https://api.gigma.ru/storage/uploads/default.svg",
            "created_at": "2024-07-27T18:13:40.000000Z"
        }
    ],
    "promotionsCount": 1
}
```

##### Описание полей ответа

- `id` — первичный ключ промоакции
- `name` — название промоакции
- `avatar` — URL изображения
- `created_at` — дата и время добавления в систему


## Скидки

### Получение списка скидок

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/discounts`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `query` — поисковая строка
- `status` — фильтр по статусу
- `application_id` — фильтр по приложению

#### Ответ

При успешном действии возвращается HTTP код `200` с массивом `discounts` и `discountsCount`.


### Создание скидки

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/discounts`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `name` *(string, обязательно)* — название скидки
- `application_id` *(int, обязательно)* — ID приложения
- `discount_type` *(string)* — тип: `"percent"` | `"fixed"`
- `discount_value` *(string)* — значение скидки, decimal-string
- `code` *(string, опционально)* — промокод
- `description` *(string, опционально)* — описание
- `min_order_amount` *(string, опционально)* — минимальная сумма заказа для применения
- `max_discount_amount` *(string, опционально)* — максимальная сумма скидки
- `total_usage_limit` *(int, опционально)* — лимит использований всего
- `per_client_usage_limit` *(int, опционально)* — лимит использований на одного клиента
- `audience` *(string, опционально)* — аудитория: `"all"` | `"new"` | `"returning"`
- `starts_at` *(string, опционально)* — дата начала ISO 8601
- `ends_at` *(string, опционально)* — дата окончания ISO 8601

#### Ответ

При успешном действии возвращается HTTP код `201` с созданной скидкой.


### Получение выбранной скидки

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/discounts/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "discount": {
        "id": 1,
        "project_id": 10,
        "application_id": 1,
        "branch_id": 5,
        "name": "Скидка 10% на первый заказ",
        "code": "FIRST10",
        "description": "Для новых покупателей",
        "status": "active",
        "effective_status": "active",
        "discount_type": "percent",
        "discount_value": "10.00",
        "min_order_amount": "500.00",
        "max_discount_amount": "1000.00",
        "total_usage_limit": 100,
        "total_used_count": 5,
        "per_client_usage_limit": 1,
        "usage_percent": 5,
        "audience": "new",
        "starts_at": "2026-01-01T00:00:00.000000Z",
        "ends_at": "2026-12-31T23:59:59.000000Z",
        "url": null,
        "paused_at": null,
        "archived_at": null,
        "share_path": "/share/discount/FIRST10",
        "magic_link": "https://api.gigma.ru/api/d/FIRST10",
        "created_by": { "id": 1, "name": "Артём" },
        "updated_by": null,
        "created_at": "2026-01-01T00:00:00.000000Z",
        "updated_at": "2026-01-01T00:00:00.000000Z",
        "latest_usages": []
    }
}
```

##### Описание полей ответа

- `status` — статус скидки (задан вручную): `"active"` | `"paused"` | `"archived"`
- `effective_status` — реальный статус с учётом дат и лимитов (может отличаться от `status`)
- `discount_type` — тип скидки: `"percent"` (процент) | `"fixed"` (фиксированная сумма)
- `discount_value` — значение скидки, decimal-string
- `total_used_count` — сколько раз скидка уже применялась
- `usage_percent` — процент использования от `total_usage_limit` (0–100)
- `audience` — кому доступна скидка: `"all"` | `"new"` | `"returning"`
- `share_path` — путь для шаринга промокода в E-Commerce приложении
- `magic_link` — прямая ссылка для активации скидки
- `paused_at` — время постановки на паузу (или `null`)
- `archived_at` — время архивирования (или `null`)
- `latest_usages` — последние применения скидки (массив объектов)


### Обновление скидки

**Метод:** PUT  
**URL:** `https://api.gigma.ru/api/discounts/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Те же параметры, что и при создании.

#### Ответ

При успешном действии возвращается HTTP код `200` с обновлённой скидкой.


### Удаление скидки

**Метод:** DELETE  
**URL:** `https://api.gigma.ru/api/discounts/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200`.


### Статистика скидок

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/discounts/stats`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200` со сводной статистикой по скидкам (количество активных, на паузе, архивных, итоговая экономия покупателей и т.п.).


### Поставить скидку на паузу

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/discounts/{id}/pause`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

Временно останавливает скидку. `effective_status` становится `"paused"`, поле `paused_at` заполняется.

#### Ответ

При успешном действии возвращается HTTP код `200` с обновлённым объектом скидки.


### Активировать скидку

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/discounts/{id}/activate`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

Снимает паузу и возобновляет скидку. `paused_at` сбрасывается в `null`.

#### Ответ

При успешном действии возвращается HTTP код `200` с обновлённым объектом скидки.


### Архивировать скидку

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/discounts/{id}/archive`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

Переводит скидку в архив. `archived_at` заполняется текущим временем.

#### Ответ

При успешном действии возвращается HTTP код `200` с обновлённым объектом скидки.


### Использования скидки

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/discounts/{id}/usages`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200` с историей применений скидки (кто, когда, в каком заказе).

---

## Магазины и пункты выдачи

Source: https://docs.gigma.ru/ERP/%D0%9C%D0%B0%D0%B3%D0%B0%D0%B7%D0%B8%D0%BD%D1%8B/

# Магазины

### Получение списка магазинов (табличное представление)

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/tables/shops`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `query` — поисковая строка
- `city_id` — ID города из справочника
- `branch_id` — ID бизнеса из справочника
- `is_shop` — флаг, указывающий на то, является ли значение магазином (true) или пунктом выдачи (false)

#### Пример запроса

```
https://api.gigma.ru/api/tables/shops?query=Сей
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "columns": [
        {"id": 124, "table_id": 16, "order": 0, "key": "id", "has_icon": 0, "text": "№"},
        {"id": 125, "table_id": 16, "order": 1, "key": "name", "has_icon": 1, "text": "Название"},
        {"id": 126, "table_id": 16, "order": 2, "key": "branch", "has_icon": 1, "text": "Направление бизнеса"},
        {"id": 127, "table_id": 16, "order": 3, "key": "city", "has_icon": 0, "text": "Город"},
        {"id": 128, "table_id": 16, "order": 4, "key": "address", "has_icon": 0, "text": "Адрес"},
        {"id": 129, "table_id": 16, "order": 5, "key": "creator", "has_icon": 1, "text": "Добавил"},
        {"id": 130, "table_id": 16, "order": 6, "key": "schedule", "has_icon": 0, "text": "График работы"}
    ],
    "shops": [
        {
            "id": 17,
            "name": {
                "icon": "http://localhost:8000//storage/uploads/yjohncMkjTSnvJ7FH4vksOtDYUy9pO2HDwmNU5Hc.svg",
                "value": "Сей Момент"
            },
            "branch": {
                "icon": "http://localhost:8000//storage/uploads/b9t9B4Y4Fq6dAKvgVW2vhzFJ12ZrgRgvVHdMnfjt.png",
                "value": "ИП Дерюгин Дмитрий Александрович"
            },
            "city": {
                "id": 1,
                "name": "Москва",
                "created_at": "2024-04-19T09:18:41.000000Z"
            },
            "address": "115477, г Москва, р-н Царицыно, ул Деловая, д 20",
            "creator": {
                "icon": "http://localhost:8000/storage/uploads/default.svg",
                "value": "Полищук Артём"
            },
            "schedule": "Ежедневно, с 10:00 до 18:00"
        }
    ],
    "pagination": {
        "total": 4,
        "per_page": 10,
        "current_page": 1,
        "last_page": 1,
        "from": 1,
        "to": 4
    }
}
```

##### Описание полей ответа

- `columns` — объект, содержащий информацию для генерации таблиц
- `id` — первичный ключ
- `name` — объект с информацией о названии магазина
- `branch` — объект с информацией о бизнесе (первый из массива)
- `city` — город, в котором расположен магазин
- `address` — полный адрес магазина
- `creator` — объект, содержащий информацию о пользователе, который добавил запись в БД
- `schedule` — график работы магазина
- `per_page` — кол-во элементов на странице
- `prev_page_url` — URL предыдущей страницы
- `from` — номер первого элемента на выбранной странице
- `to` — номер крайнего элемента на выбранной странице
- `total` — общее кол-во записей


### Получение списка магазинов

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/shops`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `query` — поисковая строка
- `city_id` — ID города из справочника
- `branch_id` — ID бизнеса из справочника
- `is_shop` — флаг, указывающий на то, является ли значение магазином (true) или пунктом выдачи (false)

#### Пример запроса

```
https://api.gigma.ru/api/shops?query=Сей
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "shops": [
        {
            "id": 3,
            "is_shop": true,
            "avatar": {
                "id": 3,
                "name": "Container.svg",
                "path": "http://localhost:8000/storage/uploads/J89936UEJYHmqaWyN8TA2JfTfFHWGvt2jequMsyd.svg",
                "created_at": "2024-04-18T13:37:45.000000Z",
                "updated_at": "2024-04-18T13:37:45.000000Z"
            },
            "code": "01",
            "name": "Столичный",
            "branches": [],
            "warehouses": [],
            "address": "г. Москва, ул. Красная Площадь, 1",
            "latitude": null,
            "longitude": null,
            "phone": "+79851234567"
        }
    ],
    "shopsCount": 1
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `is_shop` — флаг: магазин (`true`) или пункт выдачи (`false`)
- `avatar` — объект с информацией о фотографии магазина
- `code` — уникальный код магазина
- `name` — название магазина
- `branches` — массив объектов привязанных бизнесов
- `warehouses` — массив объектов привязанных складов
- `address` — полный адрес магазина
- `latitude` — широта (опционально)
- `longitude` — долгота (опционально)
- `phone` — телефон


### Добавление магазина

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/shops`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `avatar_id` — ID файла после его загрузки на сервер
- `code` — уникальный код магазина
- `name` — название магазина
- `address` — адрес магазина, полученный из Dadata
- `branches[]` — массив ID бизнесов
- `warehouses[]` — массив ID складов
- `phone` — номер телефона

#### Пример запроса

```json
{
    "avatar_id": 1,
    "is_shop": true,
    "code": "10",
    "name": "Сей Момент",
    "address": "115477, г Москва, р-н Царицыно, ул Деловая, д 20",
    "branches": [
        15
    ],
    "warehouses": [
        1,
        2,
        3
    ],
    "phone": "79999999999"
}
```

#### Ответ

При успешном действии возвращается HTTP код `201`.

```json
{
    "shop": {
        "id": 4,
        "is_shop": true,
        "avatar": {
            "id": 1,
            "name": "logo.svg",
            "type": {
                "id": 1,
                "name": "Трудовой договор",
                "avatar": "https://beta.back.erp.itecho.ru/storage/uploads/default.svg",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            "path": "https://beta.back.erp.itecho.ru/storage/uploads/yjohncMkjTSnvJ7FH4vksOtDYUy9pO2HDwmNU5Hc.svg",
            "created_at": "2024-04-14T20:04:32.000000Z",
            "updated_at": "2024-04-14T20:04:32.000000Z"
        },
        "code": "10",
        "name": "Сей Момент",
        "branches": [
            {
                "id": 15,
                "code": "1",
                "name": "ИП Дерюгин Дмитрий Александрович",
                "photo": null,
                "owned_by_us": false,
                "address": "283045, Донецкая Народная респ, г Донецк, ул Профессоров Богославских, д 5а",
                "storage_capacity": null,
                "storage_unit": null,
                "city": null,
                "counterparty": null
            }
        ],
        "warehouses": [
            {
                "id": 1,
                "code": null,
                "name": "Петухова",
                "photo": null,
                "owned_by_us": true,
                "address": "Петухова 155/1 к4",
                "storage_capacity": 100000,
                "storage_unit": {
                    "id": 2,
                    "name": "Кубический метр",
                    "abbreviation": "м³"
                },
                "city": {
                    "id": 2,
                    "name": "Новосибирск",
                    "avatar": "https://beta.back.erp.itecho.ru/storage/uploads/default.svg",
                    "created_at": "2024-04-19T09:18:41.000000Z"
                },
                "counterparty": null
            },
            {
                "id": 2,
                "code": null,
                "name": "Ленина",
                "photo": null,
                "owned_by_us": true,
                "address": "Ленина 25",
                "storage_capacity": 100000,
                "storage_unit": {
                    "id": 2,
                    "name": "Кубический метр",
                    "abbreviation": "м³"
                },
                "city": {
                    "id": 2,
                    "name": "Новосибирск",
                    "avatar": "https://beta.back.erp.itecho.ru/storage/uploads/default.svg",
                    "created_at": "2024-04-19T09:18:41.000000Z"
                },
                "counterparty": null
            },
            {
                "id": 3,
                "code": null,
                "name": "Коледино WB",
                "photo": null,
                "owned_by_us": false,
                "address": "Троицкая улица, 20, деревня Коледино, городской округ Подольск, Московская область",
                "storage_capacity": 5000000,
                "storage_unit": {
                    "id": 1,
                    "name": "Литр",
                    "abbreviation": "л"
                },
                "city": {
                    "id": 1,
                    "name": "Москва",
                    "avatar": "https://beta.back.erp.itecho.ru/storage/uploads/default.svg",
                    "created_at": "2024-04-19T09:18:41.000000Z"
                },
                "counterparty": null
            }
        ],
        "address": "115477, г Москва, р-н Царицыно, ул Деловая, д 20",
        "phone": "79999999999"
    }
}
```

##### Описание полей ответа

Описание полей ответа приведено в запросе получения выбранного магазина.


### Обновление выбранного магазина

**Метод:** PUT  
**URL:** `https://api.gigma.ru/api/shops/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `avatar_id` — ID файла после его загрузки на сервер
- `code` — уникальный код магазина
- `name` — название магазина
- `address` — адрес магазина, полученный из Dadata
- `branches[]` — массив ID бизнесов
- `warehouses[]` — массив ID складов
- `phone` — номер телефона

#### Пример запроса

```json
{
    "avatar_id": 1,
    "is_shop": true,
    "code": "10",
    "name": "Сей Момент",
    "address": "115477, г Москва, р-н Царицыно, ул Деловая, д 20",
    "branches": [
        15
    ],
    "warehouses": [
        1,
        2,
        3
    ],
    "phone": "79999999999"
}
```

#### Ответ

При успешном действии возвращается HTTP код `200`. Возвращаемый объект `shop` аналогичен ответу запроса добавления магазина.

##### Описание полей ответа

Описание полей ответа приведено в запросе получения выбранного магазина.


### Получение выбранного магазина

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/shops/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/shops/4
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "shop": {
        "id": 4,
        "is_shop": true,
        "avatar": {
            "id": 1,
            "name": "logo.svg",
            "type": {
                "id": 1,
                "name": "Трудовой договор",
                "avatar": "https://beta.back.erp.itecho.ru/storage/uploads/default.svg",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            "path": "https://beta.back.erp.itecho.ru/storage/uploads/yjohncMkjTSnvJ7FH4vksOtDYUy9pO2HDwmNU5Hc.svg",
            "created_at": "2024-04-14T20:04:32.000000Z",
            "updated_at": "2024-04-14T20:04:32.000000Z"
        },
        "code": "10",
        "name": "Сей Момент",
        "branches": [
            {
                "id": 15,
                "code": "1",
                "name": "ИП Дерюгин Дмитрий Александрович",
                "photo": null,
                "owned_by_us": false,
                "address": "283045, Донецкая Народная респ, г Донецк, ул Профессоров Богославских, д 5а",
                "storage_capacity": null,
                "storage_unit": null,
                "city": null,
                "counterparty": null
            }
        ],
        "warehouses": [
            {
                "id": 1,
                "code": null,
                "name": "Петухова",
                "photo": null,
                "owned_by_us": true,
                "address": "Петухова 155/1 к4",
                "storage_capacity": 100000,
                "storage_unit": {
                    "id": 2,
                    "name": "Кубический метр",
                    "abbreviation": "м³"
                },
                "city": {
                    "id": 2,
                    "name": "Новосибирск",
                    "avatar": "https://beta.back.erp.itecho.ru/storage/uploads/default.svg",
                    "created_at": "2024-04-19T09:18:41.000000Z"
                },
                "counterparty": null
            },
            {
                "id": 2,
                "code": null,
                "name": "Ленина",
                "photo": null,
                "owned_by_us": true,
                "address": "Ленина 25",
                "storage_capacity": 100000,
                "storage_unit": {
                    "id": 2,
                    "name": "Кубический метр",
                    "abbreviation": "м³"
                },
                "city": {
                    "id": 2,
                    "name": "Новосибирск",
                    "avatar": "https://beta.back.erp.itecho.ru/storage/uploads/default.svg",
                    "created_at": "2024-04-19T09:18:41.000000Z"
                },
                "counterparty": null
            },
            {
                "id": 3,
                "code": null,
                "name": "Коледино WB",
                "photo": null,
                "owned_by_us": false,
                "address": "Троицкая улица, 20, деревня Коледино, городской округ Подольск, Московская область",
                "storage_capacity": 5000000,
                "storage_unit": {
                    "id": 1,
                    "name": "Литр",
                    "abbreviation": "л"
                },
                "city": {
                    "id": 1,
                    "name": "Москва",
                    "avatar": "https://beta.back.erp.itecho.ru/storage/uploads/default.svg",
                    "created_at": "2024-04-19T09:18:41.000000Z"
                },
                "counterparty": null
            }
        ],
        "address": "115477, г Москва, р-н Царицыно, ул Деловая, д 20",
        "phone": "79999999999",
        "schedule": "Ежедневно, с 10:00 до 18:00"
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `code` — уникальный код магазина
- `name` — название магазина
- `is_shop` — флаг, указывающий на то, является ли значение магазином (true) или пунктом выдачи (false)
- `avatar` — объект с информацией о загруженном файле
- `branches` — массив объектов с информацией о бизнесе
- `warehouses` — массив объектов с информацией о складе
- `address` — адрес магазина
- `phone` — номер телефона магазина
- `schedule` — график работы


### Удаление выбранного магазина

**Метод:** DELETE  
**URL:** `https://api.gigma.ru/api/shops/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/shops/4
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "message": "Shop successfully deleted."
}
```


### Получение истории изменений по выбранному магазину

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/shops/{id}/history`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/shops/4/history
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "histories": [
        {
            "id": 170,
            "icon": "done",
            "color": "success",
            "title": "Редактирование",
            "description": "Редактирование: Полищук Артём",
            "datetime": "28.06.2024 06:09"
        }
    ],
    "historiesCount": 1
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `icon` — иконка
- `color` — цвет
- `title` — заголовок
- `description` — описание
- `datetime` — дата выполнения действия


## Режим работы

### Будние/выходные дни

### Получение списка дней и часов работы выбранного магазина

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/shops/{id}/hours`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/shops/17/hours
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "hours": [
        {
            "id": 1,
            "day_of_week": "ПН",
            "is_working_day": true,
            "work_start_time": "09:00:00",
            "work_end_time": "18:00:00",
            "break_start_time": null,
            "break_end_time": null
        }
    ],
    "hoursCount": 1
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `day_of_week` — день недели
- `is_working_day` — флаг, указывающий на то, является ли день рабочим (true) или выходным (false)
- `work_start_time` — время начала рабочего дня
- `work_end_time` — время завершения рабочего дня
- `break_start_time` — время начала перерыва
- `break_end_time` — время окончания перерыва


### Добавление дней и часов работы выбранного магазина

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/shops/{id}/hours`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `day_of_week` — день недели. Доступные значения: ПН, ВТ, СР, ЧТ, ПТ, СБ, ВС
- `is_working_day` — флаг, указывающий на то, является ли день рабочим (true) или выходным (false)
- `work_start_time` — время начала рабочего дня
- `work_end_time` — время завершения рабочего дня
- `break_start_time` — время начала перерыва
- `break_end_time` — время окончания перерыва

#### Пример запроса

```json
{
    "day_of_week": "ПН",
    "is_working_day": true,
    "work_start_time": "09:00",
    "work_end_time": "18:00",
    "break_start_time": "13:00",
    "break_end_time": "14:00"
}
```

#### Ответ

При успешном действии возвращается HTTP код `201`.

```json
{
    "hour": {
        "id": 4,
        "day_of_week": "ПН",
        "is_working_day": true,
        "work_start_time": "09:00",
        "work_end_time": "18:00",
        "break_start_time": "13:00",
        "break_end_time": "14:00"
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `day_of_week` — день недели
- `is_working_day` — флаг, указывающий на то, является ли день рабочим (true) или выходным (false)
- `work_start_time` — время начала рабочего дня
- `work_end_time` — время завершения рабочего дня
- `break_start_time` — время начала перерыва
- `break_end_time` — время окончания перерыва


### Обновление дней и часов работы выбранного магазина

**Метод:** PUT  
**URL:** `https://api.gigma.ru/api/shops/{id}/hours/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `day_of_week` — день недели. Доступные значения: ПН, ВТ, СР, ЧТ, ПТ, СБ, ВС
- `is_working_day` — флаг, указывающий на то, является ли день рабочим (true) или выходным (false)
- `work_start_time` — время начала рабочего дня
- `work_end_time` — время завершения рабочего дня
- `break_start_time` — время начала перерыва
- `break_end_time` — время окончания перерыва

#### Пример запроса

```json
{
    "day_of_week": "ПН",
    "is_working_day": true,
    "work_start_time": "09:00",
    "work_end_time": "18:00",
    "break_start_time": null,
    "break_end_time": null
}
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "hour": {
        "id": 4,
        "day_of_week": "ПН",
        "is_working_day": true,
        "work_start_time": "09:00",
        "work_end_time": "18:00",
        "break_start_time": null,
        "break_end_time": null
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `day_of_week` — день недели
- `is_working_day` — флаг, указывающий на то, является ли день рабочим (true) или выходным (false)
- `work_start_time` — время начала рабочего дня
- `work_end_time` — время завершения рабочего дня
- `break_start_time` — время начала перерыва
- `break_end_time` — время окончания перерыва


### Удаление выбранных дней и часов работы магазина

**Метод:** DELETE  
**URL:** `https://api.gigma.ru/api/shops/{id}/hours/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/shops/17/hours/1
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "message": "Shop hour deleted successfully."
}
```


### Праздничные дни

### Получение графика работы в праздничные дни выбранного магазина

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/shops/{id}/holidays`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/shops/17/holidays
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "holidays": {
        "work_start_time": "09:00:00",
        "work_end_time": "18:00:00",
        "break_start_time": null,
        "break_end_time": null
    }
}
```

##### Описание полей ответа

- `work_start_time` — время начала рабочего дня
- `work_end_time` — время завершения рабочего дня
- `break_start_time` — время начала перерыва
- `break_end_time` — время окончания перерыва


### Обновление графика работы в праздничные дни выбранного магазина

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/shops/{id}/holidays`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `work_start_time` — время начала рабочего дня
- `work_end_time` — время завершения рабочего дня
- `break_start_time` — время начала перерыва
- `break_end_time` — время окончания перерыва

#### Пример запроса

```json
{
    "work_start_time": "09:00",
    "work_end_time": "18:00",
    "break_start_time": "12:00",
    "break_end_time": "13:00"
}
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "holidays": {
        "work_start_time": "09:00",
        "work_end_time": "18:00",
        "break_start_time": "12:00",
        "break_end_time": "13:00"
    }
}
```

##### Описание полей ответа

- `work_start_time` — время начала рабочего дня
- `work_end_time` — время завершения рабочего дня
- `break_start_time` — время начала перерыва
- `break_end_time` — время окончания перерыва


### Исключения

### Получение списка дней-исключений в работе выбранного магазина

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/shops/{id}/exceptions`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/shops/17/exceptions
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "exceptions": [
        {
            "id": 1,
            "exception_start_date": "2024-08-10",
            "exception_end_date": "2024-08-12"
        }
    ],
    "exceptionsCount": 1
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `exception_start_date` — дата начала периода выходных дней
- `exception_end_date` — дата окончания периода выходных дней


### Добавление промежутка дней-исключений для выбранного магазина

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/shops/{id}/exceptions`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `exception_start_date` — дата начала периода выходных дней
- `exception_end_date` — дата окончания периода выходных дней

#### Пример запроса

```json
{
    "exception_start_date": "2024-08-10",
    "exception_end_date": "2024-08-12"
}
```

#### Ответ

При успешном действии возвращается HTTP код `201`.

```json
{
    "exception": {
        "id": 1,
        "exception_start_date": "2024-08-10",
        "exception_end_date": "2024-08-12"
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `exception_start_date` — дата начала периода выходных дней
- `exception_end_date` — дата окончания периода выходных дней


### Обновление промежутка дней-исключений для выбранного магазина

**Метод:** PUT  
**URL:** `https://api.gigma.ru/api/shops/{id}/exceptions/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `exception_start_date` — дата начала периода выходных дней
- `exception_end_date` — дата окончания периода выходных дней

#### Пример запроса

```json
{
    "exception_start_date": "2024-08-10",
    "exception_end_date": "2024-08-12"
}
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "exception": {
        "id": 1,
        "exception_start_date": "2024-08-10",
        "exception_end_date": "2024-08-12"
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `exception_start_date` — дата начала периода выходных дней
- `exception_end_date` — дата окончания периода выходных дней


### Удаление промежутка дней-исключения для выбранного магазина

**Метод:** DELETE  
**URL:** `https://api.gigma.ru/api/shops/{id}/exceptions/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/shops/17/exceptions/1
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "message": "Shop exception deleted successfully."
}
```

---

## Клиенты и контрагенты

Source: https://docs.gigma.ru/ERP/%D0%9A%D0%BE%D0%BD%D1%82%D1%80%D0%B0%D0%B3%D0%B5%D0%BD%D1%82%D1%8B/

# Контрагенты

Контрагент в ERP — это физическое лицо или компания, привязанная к менеджеру и типу. Поле `is_company` (boolean) разделяет две модели:

- **Физлицо** (`is_company: false`) — `first_name`, `last_name`, `middle_name`, `birthday`, `address`.
- **Компания** (`is_company: true`) — `name`, `inn`, `kpp`, `head`, `registered_at`, `legal_address`.

Общие поля для обоих: `avatar`, `type`, `manager`, `phone_1`, `phone_2`, `email`, `created_at`, `updated_at`.

## Список и таблица

### Список контрагентов

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparties`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Параметры запроса (query string)

- `query` — поисковая строка
- `is_company` — фильтр компании/физлица (boolean)
- `counterparty_type_id[]` — массив ID типов контрагентов
- `manager_id[]` — массив ID менеджеров
- `date_from`, `date_to` — диапазон по дате добавления
- `credit` — задолженность равна (int)
- `credit_gt` — задолженность больше
- `credit_lt` — задолженность меньше

#### Пример запроса

```
GET https://api.gigma.ru/api/counterparties?counterparty_type_id[]=2&query=иванов
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "counterparties": [
        {
            "id": 1,
            "is_company": true,
            "type": { "id": 2, "name": "Юр. лицо", "avatar": null, "created_at": "2024-03-22T14:01:37.000000Z" },
            "manager": { "id": 1, "first_name": "Артём", "last_name": "Полищук", "middle_name": "Николаевич", "name": "Полищук Артём" },
            "avatar": null,
            "name": "ООО \"АЙТЕКО\"",
            "inn": "5403057658",
            "kpp": "540301001",
            "head": "Снегирёв Алексей Игоревич",
            "registered_at": "2020-04-02",
            "phone_1": "79999999999",
            "phone_2": "78888888888",
            "email": "support@itecho.ru",
            "legal_address": "630073, г. Новосибирск, Новогодняя ул., д. 20/1, кв. 26",
            "created_at": "2024-03-22T14:01:37.000000Z",
            "updated_at": "2024-04-03T07:07:11.000000Z"
        }
    ]
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `is_company` — `true` для компании, `false` для физлица
- `type` — объект типа контрагента (`id`, `name`, `avatar`, `created_at`) или `null`
- `manager` — объект менеджера (`id`, `first_name`, `last_name`, `middle_name`, `name`) или `null`
- `avatar` — объект файла аватара (`id`, `url`, …) или `null`
- Поля компании: `name`, `inn`, `kpp`, `head`, `registered_at`, `legal_address`
- Поля физлица: `first_name`, `last_name`, `middle_name`, `birthday`, `address`
- Общие: `phone_1`, `phone_2`, `email`, `created_at`, `updated_at`


### Таблица контрагентов (для UI с колонками и пагинацией)

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/tables/counterparties`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

Возвращает данные в формате, пригодном для отрисовки таблицы: список колонок, упрощённое представление контрагентов и пагинацию. Поддерживает те же query-фильтры, что и `/api/counterparties`.

#### Параметры запроса (query string)

Те же, что у `/api/counterparties`, плюс пагинация: `page`, `per_page`.

#### Ответ

```json
{
    "columns": [
        { "id": 1, "table_id": 3, "order": 1, "key": "name", "has_icon": 1, "text": "Название" },
        { "id": 2, "table_id": 3, "order": 2, "key": "type", "has_icon": 1, "text": "Тип" },
        { "id": 3, "table_id": 3, "order": 3, "key": "manager", "has_icon": 1, "text": "Менеджер" },
        { "id": 4, "table_id": 3, "order": 4, "key": "inn", "has_icon": 0, "text": "ИНН" },
        { "id": 5, "table_id": 3, "order": 5, "key": "credit", "has_icon": 0, "text": "Задолженность" }
    ],
    "counterparties": [
        {
            "id": 1,
            "created_at": "2024-03-22T14:01:37.000000Z",
            "type":    { "icon": "/icons/company.svg", "value": "Юр. лицо" },
            "name":    { "icon": null, "value": "ООО \"АЙТЕКО\"" },
            "manager": { "icon": null, "value": "Полищук Артём" },
            "inn": "5403057658",
            "contact": null,
            "credit": 0
        }
    ],
    "pagination": {
        "total": 42,
        "per_page": 15,
        "current_page": 1,
        "last_page": 3,
        "from": 1,
        "to": 15
    }
}
```

##### Описание полей ответа

- `columns[]` — определения колонок:
  - `id`, `table_id`, `order` — служебные
  - `key` — ключ поля контрагента
  - `has_icon` — `1` если рядом со значением показывается иконка
  - `text` — заголовок колонки
- `counterparties[]` — упрощённые контрагенты, где `type`, `name`, `manager` и т.п. имеют форму `{ icon, value }`
- `pagination` — стандартный Laravel-пагинатор: `total`, `per_page`, `current_page`, `last_page`, `from`, `to`


## Карточка контрагента

### Получение контрагента по ID

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparties/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Параметры запроса

Только `id` контрагента в пути URL.

#### Ответ

```json
{
    "counterparty": {
        "id": 1,
        "is_company": false,
        "type": { "id": 2, "name": "Розница", "avatar": null, "created_at": "2024-03-22T14:01:37.000000Z" },
        "manager": { "id": 1, "first_name": "Артём", "last_name": "Полищук", "middle_name": "Николаевич", "name": "Полищук Артём" },
        "avatar": null,
        "first_name": "Алексей",
        "last_name": "Петров",
        "middle_name": "Викторович",
        "birthday": "1980-04-02",
        "address": "630073, г. Новосибирск, Новогодняя ул., д. 20/1, кв. 26",
        "phone_1": "79999999990",
        "phone_2": "78888888888",
        "email": "support@itecho.ru",
        "created_at": "2024-03-22T14:01:37.000000Z",
        "updated_at": "2024-04-03T07:07:11.000000Z"
    }
}
```


### Создание контрагента

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/counterparties`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Параметры запроса (тело)

Формат тела зависит от `is_company`.

**Физлицо** (`is_company: false`):

- `is_company` — `false`
- `counterparty_type_id` — ID типа контрагента (nullable)
- `avatar_id` — ID файла аватара (optional)
- `first_name`, `last_name`, `middle_name` — ФИО
- `birthday` — `YYYY-MM-DD`
- `phone_1`, `phone_2`, `email`, `address`

**Компания** (`is_company: true`):

- `is_company` — `true`
- `counterparty_type_id` — ID типа
- `avatar_id` — ID файла (optional)
- `name` — название
- `inn`, `kpp`
- `head` — ФИО директора
- `registered_at` — дата регистрации `YYYY-MM-DD`
- `phone_1`, `phone_2`, `email`, `legal_address`

#### Пример запроса (физлицо)

```json
{
    "is_company": false,
    "counterparty_type_id": 2,
    "first_name": "Алексей",
    "last_name": "Петров",
    "middle_name": "Викторович",
    "birthday": "1980-04-02",
    "phone_1": "79999999990",
    "phone_2": "78888888888",
    "email": "support@itecho.ru",
    "address": "630073, г. Новосибирск, Новогодняя ул., д. 20/1, кв. 26"
}
```

#### Ответ

```json
{
    "counterparty": { "id": 42, "is_company": false, "...": "поля как в GET" }
}
```


### Изменение контрагента

**Метод:** PUT  
**URL:** `https://api.gigma.ru/api/counterparties/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Параметры запроса (тело)

Те же поля, что и в `POST /api/counterparties` (соответствующий вариант `is_company`).

#### Ответ

```json
{
    "counterparty": { "id": 42, "...": "обновлённый объект" }
}
```


### Удаление контрагента

**Метод:** DELETE  
**URL:** `https://api.gigma.ru/api/counterparties/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Параметры запроса

Только `id` контрагента в пути URL.

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "message": "Counterparty deleted"
}
```


## Банковские реквизиты

### Список банковских реквизитов контрагента

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparties/{id}/bank_requisites`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Ответ

```json
{
    "bankRequisites": [
        {
            "id": 1,
            "name": "Расчётный счёт в Сбербанке",
            "bik": "045004641",
            "kpp": "540301001",
            "payment_account": "40702810844050003101",
            "address": "630007, Новосибирская область, г. Новосибирск, Красный проспект, д. 5",
            "created_at": "2024-03-22T14:01:37.000000Z",
            "updated_at": "2024-04-03T07:07:11.000000Z"
        }
    ],
    "bankRequisitesCount": 1
}
```

##### Описание полей ответа

- `bankRequisites[]` — массив реквизитов:
  - `id`, `name` — название счёта/банка
  - `bik` — БИК
  - `kpp` — КПП
  - `payment_account` — номер расчётного счёта
  - `address` — адрес банка
- `bankRequisitesCount` — общее количество


### Добавление банковского реквизита

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/counterparties/{id}/bank_requisites`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Параметры запроса (тело)

- `name` — название счёта/банка
- `bik` — БИК
- `kpp` — КПП
- `payment_account` — номер расчётного счёта
- `address` — адрес банка

#### Пример запроса

```json
{
    "name": "Расчётный счёт в Сбербанке",
    "bik": "045004641",
    "kpp": "540301001",
    "payment_account": "40702810844050003101",
    "address": "630007, г. Новосибирск, Красный проспект, д. 5"
}
```

#### Ответ

```json
{
    "bankRequisites": [
        { "id": 1, "name": "Расчётный счёт в Сбербанке", "bik": "045004641", "kpp": "540301001", "payment_account": "40702810844050003101", "address": "630007, г. Новосибирск, Красный проспект, д. 5" }
    ],
    "bankRequisitesCount": 1
}
```


### Изменение банковского реквизита

**Метод:** PUT  
**URL:** `https://api.gigma.ru/api/counterparties/{id}/bank_requisites/{requisiteId}`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Параметры запроса (тело)

Те же поля, что и в POST: `name`, `bik`, `kpp`, `payment_account`, `address`.

#### Ответ

Структура аналогична GET — массив `bankRequisites` и `bankRequisitesCount`.


## Контакты контрагента

### Список контактов контрагента

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparties/{id}/contacts`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Ответ

```json
{
    "contacts": [
        {
            "id": 1,
            "first_name": "Анна",
            "last_name": "Иванова",
            "middle_name": "Сергеевна",
            "birthday": "1985-07-15",
            "phone_1": "79991234567",
            "phone_2": "",
            "email": "anna@itecho.ru",
            "address": "г. Новосибирск, ул. Ленина, 1"
        }
    ],
    "contactsCount": 1
}
```

##### Описание полей ответа

- `contacts[]` — массив контактных лиц: `id`, `first_name`, `last_name`, `middle_name`, `birthday`, `phone_1`, `phone_2`, `email`, `address`
- `contactsCount` — общее количество


### Добавление контакта

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/counterparties/{id}/contacts`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Параметры запроса (тело)

- `first_name`, `last_name`, `middle_name` — ФИО
- `birthday` — `YYYY-MM-DD`
- `phone_1`, `phone_2`, `email`, `address`

#### Пример запроса

```json
{
    "first_name": "Анна",
    "last_name": "Иванова",
    "middle_name": "Сергеевна",
    "birthday": "1985-07-15",
    "phone_1": "79991234567",
    "phone_2": "",
    "email": "anna@itecho.ru",
    "address": "г. Новосибирск, ул. Ленина, 1"
}
```

#### Ответ

Структура аналогична GET — массив `contacts` и `contactsCount`.


### Изменение контакта

**Метод:** PUT  
**URL:** `https://api.gigma.ru/api/counterparties/{id}/contacts/{contactId}`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Параметры запроса (тело)

Те же поля, что и в POST.

#### Ответ

Структура аналогична GET.


## История изменений

### История изменений контрагента

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparties/{id}/history`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

Возвращает события по контрагенту в формате таймлайна с пагинацией.

#### Параметры запроса (query string)

- `page`, `per_page` — пагинация

#### Ответ

```json
{
    "counterparties": {
        "current_page": 1,
        "data": [
            {
                "id": 101,
                "icon": "edit",
                "color": "info",
                "title": "Изменён телефон",
                "description": "phone_1: 79999999990 → 79991112233",
                "dateTime": "2024-04-03T07:07:11.000000Z"
            }
        ],
        "first_page_url": "https://api.gigma.ru/api/counterparties/1/history?page=1",
        "from": 1,
        "last_page": 2,
        "last_page_url": "https://api.gigma.ru/api/counterparties/1/history?page=2",
        "next_page_url": "https://api.gigma.ru/api/counterparties/1/history?page=2",
        "path": "https://api.gigma.ru/api/counterparties/1/history",
        "per_page": 15,
        "prev_page_url": null,
        "to": 15,
        "total": 20,
        "links": [
            { "url": null, "label": "&laquo; Previous", "active": false },
            { "url": "https://api.gigma.ru/api/counterparties/1/history?page=1", "label": "1", "active": true },
            { "url": "https://api.gigma.ru/api/counterparties/1/history?page=2", "label": "2", "active": false }
        ]
    }
}
```

##### Описание полей ответа

- `counterparties.data[]` — события:
  - `id` — ID события
  - `icon` — имя иконки (`edit`, `add`, `delete`, …)
  - `color` — `primary | secondary | info | success | warning | error | dark | light`
  - `title` — короткий заголовок события
  - `description` — описание изменения
  - `dateTime` — ISO-8601
- Остальные поля — стандартный Laravel-пагинатор

---

## Заказы и исполнение

Source: https://docs.gigma.ru/ERP/%D0%97%D0%B0%D0%BA%D0%B0%D0%B7%D1%8B/

# Заказы

### Получение списка заказов

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/orders`  
**Авторизация:** Bearer сотрудника или агента с view-orders, create-orders или edit-orders  

"
	success="200"
>

#### Параметры запроса

- `hierarchy` *(string, необязательно)* — `all` для всех доступных заказов или `my` только для заказов текущего manager;
- `counterparty_id` *(integer, необязательно)* — ID контрагента;
- `department_id[]` *(integer[], необязательно)* — ID отделов менеджеров;
- `order_status_id[]` *(integer[], необязательно)* — ID статусов заказа;
- `application_id[]` *(integer[], необязательно)* — ID приложений-источников;
- `query` *(string, необязательно)* — поиск по объекту, номеру договора, номеру счёта или адресу, минимум 3 символа;
- `date_from` *(date, необязательно)* — дата создания от;
- `date_to` *(date, необязательно)* — дата создания по.

Backend всегда добавляет `project_id` текущего actor. Для пользователя без роли `owner`/`admin` и с назначенным `branch_id` список дополнительно ограничивается этим филиалом.

Endpoint возвращает всю отфильтрованную коллекцию. `page` и `per_page` здесь не поддерживаются; для UI-пагинации используйте `GET /api/tables/orders`.

#### Пример запроса

```http
GET /api/orders?hierarchy=my&order_status_id[]=1&department_id[]=7&date_from=2026-08-01
Authorization: Bearer <access_token>
Accept: application/json
```

#### Ответ

```json
{
	"orders": [
		{
			"id": 17,
			"avatar": null,
			"status": {
				"id": 1,
				"name": "В сборке",
				"avatar": "https://api.gigma.ru/storage/uploads/default.svg",
				"created_at": "2024-03-27T07:00:46.000000Z"
			},
			"price": "4500.00",
			"promo_code": null,
			"original_price": 5000,
			"product_discount_amount": 500,
			"promo_discount_amount": 0,
			"total_discount_amount": 500,
			"final_price": 4500,
			"invoice_number": null,
			"invoice_start_date": null,
			"invoice_end_date": null,
			"application": {
				"id": 14,
				"name": "Сей момент",
				"avatar": "https://api.gigma.ru/storage/uploads/default.svg",
				"created_at": "2024-08-01T09:20:01.000000Z"
			},
			"counterparty": {
				"id": 56,
				"name": "ООО \"РОГА И КОПЫТА\""
			},
			"delivery_type": {
				"id": 1,
				"name": "Самовывоз",
				"price": "0.00",
				"is_active": 1,
				"created_at": "2024-05-13T05:26:37.000000Z"
			},
			"address": "357100, Ставропольский край, г Невинномысск",
			"shop": null,
			"branch": {
				"id": 15,
				"name": "Торговля косметикой",
				"avatar": "https://api.gigma.ru/storage/uploads/default.svg",
				"created_at": "2024-08-01T07:50:59.000000Z"
			},
			"object": null,
			"source": {
				"id": 14,
				"name": "Сей момент",
				"avatar": "https://api.gigma.ru/storage/uploads/default.svg",
				"created_at": "2024-08-01T09:20:01.000000Z"
			},
			"sales_channel": {
				"id": 1,
				"name": "Канал продаж 1",
				"avatar": "https://api.gigma.ru/storage/uploads/default.svg",
				"created_at": "2024-03-27T07:00:46.000000Z"
			},
			"manager": {
				"id": 1,
				"first_name": "Артём",
				"last_name": "Полищук",
				"middle_name": "Николаевич",
				"name": "Полищук Артём"
			},
			"promotion": null,
			"contract": null,
			"contract_number": null,
			"contract_start_date": null,
			"contract_end_date": null,
			"name": null,
			"refund_request": {
				"requested_at": null,
				"requested_by_user_id": null,
				"comment": null,
				"email_sent_at": null
			},
			"ticket": {
				"redeem_token": null,
				"redeemed_count": 0,
				"total_tickets": 1,
				"last_redeemed_at": null,
				"last_redeemed_by": null
			}
		}
	],
	"ordersCount": 1
}
```

##### Описание полей ответа

- `orders` *(object[], обязательно)* — массив ресурсов заказа; структура элемента совпадает с `GET /api/orders/{id}`;
- `ordersCount` *(integer, обязательно)* — количество заказов после применения фильтров;
- `orders[].counterparty` *(object, необязательно)* — клиент заказа или `null`, если заказ создан без контрагента;
- `orders[].ticket` *(object, обязательно)* — данные гашения билета с дополнительной проверкой project/branch scope.


### Получение списка заказов (табличное представление)

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/tables/orders`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `order_status_id` — массив ID статусов заказа из справочника
- `application_id` — массив ID источников заказа
- `department_id` — массив ID отделов
- `hierarchy` — `all` для получения всех заказов, `my` — только своих
- `page` — текущая страница (для пагинации)
- `per_page` — кол-во элементов на странице
- `query` — поисковая строка
- `date_from` — "дата с..." (от даты добавления в систему)
- `date_to` — "дата по..." (от даты добавления в систему)

#### Пример запроса

```
https://api.gigma.ru/api/tables/orders?query=коледино&order_status_id[]=1&application_id[]=1&hierarchy=my&department_id[]=1
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "columns": [
        {"id": 26, "table_id": 4, "order": 0, "key": "id", "has_icon": 0, "text": "№"},
        {"id": 27, "table_id": 4, "order": 1, "key": "created_at", "has_icon": 0, "text": "Создан"},
        {"id": 28, "table_id": 4, "order": 2, "key": "branch", "has_icon": 1, "text": "Бизнес"},
        {"id": 29, "table_id": 4, "order": 3, "key": "counterparty", "has_icon": 1, "text": "Клиент"},
        {"id": 30, "table_id": 4, "order": 4, "key": "object", "has_icon": 1, "text": "Проект/Объект"},
        {"id": 31, "table_id": 4, "order": 5, "key": "source", "has_icon": 1, "text": "Источник"},
        {"id": 32, "table_id": 4, "order": 6, "key": "manager", "has_icon": 1, "text": "Менеджер"},
        {"id": 33, "table_id": 4, "order": 7, "key": "sales_channel", "has_icon": 1, "text": "Канал продаж"},
        {"id": 87, "table_id": 4, "order": 8, "key": "promo", "has_icon": 1, "text": "Промоакция"},
        {"id": 106, "table_id": 4, "order": 9, "key": "price", "has_icon": 0, "text": "Сумма"},
        {"id": 107, "table_id": 4, "order": 10, "key": "status", "has_icon": 0, "text": "Статус/Этап"}
    ],
    "orders": [
        {
            "id": 16,
            "created_at": "27.07.2024 12:43",
            "branch": {
                "icon": "http://localhost:8000//storage/uploads/9qzh2GCaYpRpaxXnql0JZYpIesu3qlvQLV2OBhcN.png",
                "value": "Продажа косметики"
            },
            "counterparty": {
                "icon": "http://localhost:8000/storage/uploads/default.svg",
                "value": " "
            },
            "object": null,
            "source": {
                "icon": "http://localhost:8000//storage/uploads/uPINajA2l2XPB44ojjTEd88wRKxRwsWXIlrgg2iX.jpg",
                "value": "Сей момент"
            },
            "manager": {
                "icon": "http://localhost:8000/storage/uploads/default.svg",
                "value": "Полищук Артём"
            },
            "sales_channel": {
                "icon": "http://localhost:8000//storage/uploads/uPINajA2l2XPB44ojjTEd88wRKxRwsWXIlrgg2iX.jpg",
                "value": "Сей момент"
            },
            "promotion": null,
            "price": null,
            "status": {
                "icon": "http://localhost:8000/storage/uploads/default.svg",
                "value": "В сборке"
            }
        }
    ],
    "pagination": {
        "total": 1,
        "per_page": 1,
        "current_page": 1,
        "last_page": 1,
        "from": 1,
        "to": 1
    }
}
```

##### Описание полей ответа

- `columns` — массив столбцов
- `pagination` — объект с информацией, необходимой для пагинации
- `id` — первичный ключ (номер заказа)
- `created_at` — дата/время создания заказа
- `branch` — объект с информацией о бизнесе
- `counterparty` — объект с информацией о клиенте (контрагенте)
- `object` — объект с информацией об объекте
- `source` — объект с информацией об источнике заказа
- `manager` — объект с информацией о менеджере
- `sales_channel` — объект с информацией о канале продаж
- `promotion` — объект с информацией о промоакции
- `price` — стоимость заказа
- `status` — объект с информацией о статусе заказа


### Получение выбранного заказа

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/orders/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/orders/17
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "order": {
        "id": 17,
        "avatar": {
            "id": 763,
            "name": "ai monsters.jpg",
            "type": {
                "id": 2,
                "name": "Аватар",
                "avatar": "http://localhost:8000/storage/uploads/default.svg",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            "path": "http://localhost:8000/storage/uploads/AsQsvs5VPbIo6YkYlnlQel39T7RS01zYD2NPlYYv.jpg",
            "created_at": "2024-08-01T15:55:09.000000Z",
            "updated_at": "2024-08-01T15:55:09.000000Z"
        },
        "status": {
            "id": 1,
            "name": "В сборке",
            "avatar": "http://localhost:8000/storage/uploads/default.svg",
            "created_at": "2024-03-27T07:00:46.000000Z"
        },
        "invoice_number": null,
        "invoice_start_date": null,
        "invoice_end_date": null,
        "application": {
            "id": 14,
            "name": "Сей момент",
            "avatar": "http://localhost:8000/storage/uploads/default.svg",
            "created_at": "2024-08-01T09:20:01.000000Z"
        },
        "counterparty": {
            "id": 56,
            "name": "ООО \"РОГА И КОПЫТА\""
        },
        "delivery_type": {
            "id": 1,
            "name": "Самовывоз",
            "price": "0.00",
            "is_active": 1,
            "created_at": "2024-05-13T05:26:37.000000Z"
        },
        "address": "357100, Ставропольский край, г Невинномысск",
        "branch": {
            "id": 15,
            "name": "Торговля косметикой",
            "avatar": "http://localhost:8000//storage/uploads/b9t9B4Y4Fq6dAKvgVW2vhzFJ12ZrgRgvVHdMnfjt.png",
            "created_at": "2024-08-01T07:50:59.000000Z"
        },
        "object": null,
        "source": {
            "id": 14,
            "name": "Сей момент",
            "avatar": "http://localhost:8000/storage/uploads/default.svg",
            "created_at": "2024-08-01T09:20:01.000000Z"
        },
        "sales_channel": {
            "id": 1,
            "name": "Канал продаж 1",
            "avatar": "http://localhost:8000/storage/uploads/default.svg",
            "created_at": "2024-03-27T07:00:46.000000Z"
        },
        "manager": {
            "id": 1,
            "first_name": "Артём",
            "last_name": "Полищук",
            "middle_name": "Николаевич",
            "name": "Полищук Артём"
        },
        "promotion": {
            "id": 1,
            "name": "Улётное лето",
            "avatar": "http://localhost:8000//storage/uploads/default_brand.png",
            "created_at": "2024-07-28T16:59:24.000000Z"
        },
        "contract": null,
        "contract_number": null,
        "contract_start_date": null,
        "contract_end_date": null,
        "name": null,
        "promo_code": null,
        "original_price": null,
        "product_discount_amount": null,
        "promo_discount_amount": null,
        "total_discount_amount": null,
        "final_price": null,
        "refund_request": {
            "requested_at": null,
            "requested_by_user_id": null,
            "comment": null,
            "email_sent_at": null
        },
        "ticket": {
            "redeem_token": null,
            "redeemed_count": null,
            "total_tickets": null,
            "last_redeemed_at": null,
            "last_redeemed_by": null
        }
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ (номер заказа)
- `avatar` — объект с информацией о фотографии заказа
- `status` — объект с информацией о статусе заказа
- `price` — итоговая цена заказа
- `promo_code` — применённый промокод
- `original_price` — исходная цена до скидок
- `product_discount_amount` — скидка по товарам
- `promo_discount_amount` — скидка по промокоду
- `total_discount_amount` — суммарная скидка
- `final_price` — итоговая цена после всех скидок
- `invoice_number` — номер счёта
- `application` — объект с информацией о приложении
- `invoice_start_date` — дата счёта (дата создания счёта)
- `invoice_end_date` — дата окончания срока действия счёта
- `counterparty` — объект с информацией о контрагенте
- `delivery_type` — объект с информацией о способе доставки заказа
- `address` — адрес
- `branch` — объект с информацией о бизнесе
- `object` — информация об объекте
- `source` — объект с информацией об источнике заказа
- `sales_channel` — объект с информацией о канале продаж
- `manager` — объект с информацией о менеджере
- `promotion` — объект с информацией о промоакции
- `contract` — объект с информацией о договоре
- `contract_number` — номер договора
- `contract_start_date` — дата начала договора
- `contract_end_date` — дата окончания договора
- `name` — произвольное название заказа
- `refund_request` — объект с информацией о запросе возврата: `requested_at`, `requested_by_user_id`, `comment`, `email_sent_at`
- `ticket` — поля гашения билета (только для авторизованных с доступом к заказу): `redeem_token`, `redeemed_count`, `total_tickets`, `last_redeemed_at`, `last_redeemed_by`


### Добавление заказа

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/orders`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

⚠ Реальный minimum (`Order/StoreRequest` в `itecho-erp-backend`): только `counterparty_id` + `manager_id`. Остальные поля опциональны на уровне валидатора.

- `counterparty_id` *(int, обязательно)* — ID контрагента (`GET /api/counterparties`)
- `manager_id` *(int, обязательно)* — ID менеджера (`GET /api/managers`)
- `avatar_id` *(int, опционально)* — ID фотографии (`GET /api/files`)
- `delivery_type_id` *(int, опционально)* — ID типа доставки (`GET /api/delivery_types`)
- `address` *(string, опционально)* — адрес заказа (min:3)
- `shop_id` *(int, опционально)* — ID магазина (`GET /api/shops`). Рекомендуется с `branch_id`
- `branch_id` *(int, опционально)* — ID бизнеса (`GET /api/branches`)
- `object_id` *(int, опционально)* — ID объекта
- `application_id` *(int, опционально)* — ID источника (E-Commerce application)
- `sales_channel_id` *(int, опционально)* — ID канала продаж
- `promotion_id` *(int, опционально)* — ID промоакции
- `contract_number` *(string, опционально)* — номер договора
- `contract_id` *(int, опционально)* — ID файла договора (`GET /api/files`)
- `contract_start_date` *(date, опционально)* — `YYYY-MM-DD`
- `contract_end_date` *(date, опционально)* — `YYYY-MM-DD`
- `invoice_number` *(string, опционально)* — номер счёта
- `invoice_start_date` *(date, опционально)* — `YYYY-MM-DD`
- `invoice_end_date` *(date, опционально)* — `YYYY-MM-DD`

#### Пример запроса

```json
{
    "avatar_id": 1,
    "counterparty_id": 3,
    "delivery_type_id": 1,
    "address": "г Москва, пл Комсомольская, д 20",
    "branch_id": 1,
    "shop_id": 1,
    "object_id": null,
    "application_id": 10,
    "sales_channel_id": 1,
    "manager_id": 1,
    "promotion_id": null,
    "contract_number": "А-35/2024",
    "contract_id": 1,
    "contract_start_date": "2024-01-11",
    "contract_end_date": "2024-01-11",
    "invoice_number": "123123",
    "invoice_start_date": "2024-01-11",
    "invoice_end_date": "2024-01-11"
}
```

#### Ответ

При успешном действии возвращается HTTP код `201`.

```json
{
    "order": {
        "id": 17,
        "avatar": {
            "id": 763,
            "name": "ai monsters.jpg",
            "type": {
                "id": 2,
                "name": "Аватар",
                "avatar": "http://localhost:8000/storage/uploads/default.svg",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            "path": "http://localhost:8000/storage/uploads/AsQsvs5VPbIo6YkYlnlQel39T7RS01zYD2NPlYYv.jpg",
            "created_at": "2024-08-01T15:55:09.000000Z",
            "updated_at": "2024-08-01T15:55:09.000000Z"
        },
        "status": {
            "id": 1,
            "name": "В сборке",
            "avatar": "http://localhost:8000/storage/uploads/default.svg",
            "created_at": "2024-03-27T07:00:46.000000Z"
        },
        "invoice_number": null,
        "invoice_start_date": null,
        "invoice_end_date": null,
        "application": {
            "id": 14,
            "name": "Сей момент",
            "avatar": "http://localhost:8000/storage/uploads/default.svg",
            "created_at": "2024-08-01T09:20:01.000000Z"
        },
        "counterparty": {
            "id": 56,
            "name": "ООО \"РОГА И КОПЫТА\""
        },
        "delivery_type": {
            "id": 1,
            "name": "Самовывоз",
            "price": "0.00",
            "is_active": 1,
            "created_at": "2024-05-13T05:26:37.000000Z"
        },
        "address": "357100, Ставропольский край, г Невинномысск",
        "shop": {
            "id": 1,
            "photo": {
                "id": 1,
                "name": "logo.svg",
                "type": {
                    "id": 1,
                    "name": "Трудовой договор",
                    "avatar": "http://localhost:8000/storage/uploads/default.svg",
                    "created_at": "2024-03-27T07:00:46.000000Z"
                },
                "path": "http://localhost:8000/storage/uploads/yjohncMkjTSnvJ7FH4vksOtDYUy9pO2HDwmNU5Hc.svg",
                "created_at": "2024-04-14T20:04:32.000000Z",
                "updated_at": "2024-04-14T20:04:32.000000Z"
            },
            "name": "Центральный",
            "address": "г. Ростов-на-Дону, ул. Ленина, 1",
            "phone": "+79851234567",
            "schedule": "ПН-ПТ, с 10:00 до 18:00"
        },
        "branch": {
            "id": 15,
            "name": "Торговля косметикой",
            "avatar": "http://localhost:8000//storage/uploads/b9t9B4Y4Fq6dAKvgVW2vhzFJ12ZrgRgvVHdMnfjt.png",
            "created_at": "2024-08-01T07:50:59.000000Z"
        },
        "object": null,
        "source": {
            "id": 14,
            "name": "Сей момент",
            "avatar": "http://localhost:8000/storage/uploads/default.svg",
            "created_at": "2024-08-01T09:20:01.000000Z"
        },
        "sales_channel": {
            "id": 1,
            "name": "Канал продаж 1",
            "avatar": "http://localhost:8000/storage/uploads/default.svg",
            "created_at": "2024-03-27T07:00:46.000000Z"
        },
        "manager": {
            "id": 1,
            "first_name": "Артём",
            "last_name": "Полищук",
            "middle_name": "Николаевич",
            "name": "Полищук Артём"
        },
        "promotion": {
            "id": 1,
            "name": "Улётное лето",
            "avatar": "http://localhost:8000//storage/uploads/default_brand.png",
            "created_at": "2024-07-28T16:59:24.000000Z"
        },
        "contract": null,
        "contract_number": null,
        "contract_start_date": null,
        "contract_end_date": null
    }
}
```

##### Описание полей ответа

Возвращаемые поля аналогичны запросу получения выбранного заказа.


### Редактирование заказа

**Метод:** PUT  
**URL:** `https://api.gigma.ru/api/orders/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `avatar_id` — ID фотографии склада
- `counterparty_id` — ID контрагента
- `delivery_type_id` — ID типа доставки
- `address` — адрес заказа
- `shop_id` — ID магазина. Рекомендуется использовать с параметром `branch_id`
- `branch_id` — ID бизнеса
- `object_id` — ID объекта
- `application_id` — ID источника
- `sales_channel_id` — ID канала продаж
- `manager_id` — ID менеджера
- `promotion_id` — ID промоакции
- `contract_number` — номер договора
- `contract_id` — ID договора
- `contract_start_date` — дата начала действия договора
- `contract_end_date` — дата окончания действия договора
- `invoice_number` — номер счёта
- `invoice_start_date` — дата счёта (дата создания счёта)
- `invoice_end_date` — дата окончания срока действия счёта

#### Пример запроса

```json
{
    "avatar_id": 1,
    "counterparty_id": 3,
    "delivery_type_id": 1,
    "address": "г Москва, пл Комсомольская, д 20",
    "branch_id": 1,
    "object_id": null,
    "application_id": 10,
    "sales_channel_id": 1,
    "manager_id": 1,
    "promotion_id": null,
    "contract_number": "А-35/2024",
    "contract_id": 1,
    "contract_start_date": "2024-01-11",
    "contract_end_date": "2024-01-11",
    "invoice_number": "123123",
    "invoice_start_date": "2024-01-11",
    "invoice_end_date": "2024-01-11"
}
```

#### Ответ

При успешном действии возвращается HTTP код `200`. Возвращаемый объект `order` аналогичен ответу запроса получения выбранного заказа.

##### Описание полей ответа

Возвращаемые поля аналогичны запросу получения выбранного заказа.


### Удаление заказа ⚠ backend bug

**Метод:** DELETE  
**URL:** `https://api.gigma.ru/api/orders/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

⚠ **Backend bug:** endpoint стабильно возвращает `500`. Удаление заказа через API сейчас не работает — используй смену статуса в `IS_CANCELED` (6) через `PUT /api/orders/{id}` с `{ "order_status_id": 6 }`.

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/orders/1
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "message": "Order deleted."
}
```

##### Описание полей ответа

- `message` — информационное поле


## Содержание заказа

### Получение содержимого заказа (табличное представление)

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/tables/orders/{id}/nomenclatures`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `query` — поисковая строка

#### Пример запроса

```
https://api.gigma.ru/api/tables/orders/16/nomenclatures?query=картридж
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "columns": [
        {"id": 108, "table_id": 14, "order": 0, "key": "code", "has_icon": 0, "text": "Код"},
        {"id": 109, "table_id": 14, "order": 1, "key": "name", "has_icon": 1, "text": "Наименование"},
        {"id": 110, "table_id": 14, "order": 2, "key": "warehouse", "has_icon": 1, "text": "Склад"},
        {"id": 111, "table_id": 14, "order": 3, "key": "city", "has_icon": 0, "text": "Город"},
        {"id": 112, "table_id": 14, "order": 4, "key": "brand", "has_icon": 1, "text": "Торговая марка"},
        {"id": 113, "table_id": 14, "order": 5, "key": "vat", "has_icon": 0, "text": "Ставка НДС"},
        {"id": 114, "table_id": 14, "order": 6, "key": "unit", "has_icon": 0, "text": "Ед. изм."},
        {"id": 115, "table_id": 14, "order": 7, "key": "price", "has_icon": 0, "text": "Цена"},
        {"id": 116, "table_id": 14, "order": 8, "key": "quantity", "has_icon": 0, "text": "Кол-во"},
        {"id": 117, "table_id": 14, "order": 9, "key": "amount", "has_icon": 0, "text": "Сумма"}
    ],
    "orderNomenclatures": [
        {
            "id": 19,
            "code": "1234",
            "name": {
                "icon": "http://localhost:8000/storage/uploads/default.svg",
                "value": "Tony Moly Soft Touch Air Puff 5P"
            },
            "warehouse": {
                "icon": "http://localhost:8000/storage/uploads/default.svg",
                "value": "Петухова"
            },
            "city": "Новосибирск",
            "brand": {
                "icon": "http://localhost:8000//storage/uploads/default_brand.png",
                "value": "Tony Moly"
            },
            "vat": "20.00",
            "unit": "ед",
            "quantity": 5,
            "price": "900.00",
            "amount": "4500.00"
        },
        {
            "id": 20,
            "code": "123",
            "name": {
                "icon": "http://localhost:8000//storage/uploads/lp9ypkHwfjK2bULPWbllznxFlGt71e3hUMnPFn2F.webp",
                "value": "BANILA CO Glow Fit Foundation Brush"
            },
            "warehouse": {
                "icon": "http://localhost:8000/storage/uploads/default.svg",
                "value": "Петухова"
            },
            "city": "Новосибирск",
            "brand": {
                "icon": "http://localhost:8000//storage/uploads/default_brand.png",
                "value": "Holika Holika"
            },
            "vat": "20.00",
            "unit": "ед",
            "quantity": 1,
            "price": "204500.00",
            "amount": "204500.00"
        }
    ],
    "pagination": {
        "total": 2,
        "per_page": 10,
        "current_page": 1,
        "last_page": 1,
        "from": 1,
        "to": 2
    }
}
```

##### Описание полей ответа

- `columns` — массив столбцов
- `pagination` — объект с информацией, необходимой для пагинации
- `id` — первичный ключ
- `name` — объект с номенклатурным наименованием товара
- `warehouse` — объект с наименованием склада
- `city` — город
- `brand` — объект с информацией о производителе
- `vat` — НДС
- `unit` — единицы измерения товара
- `quantity` — кол-во товара
- `price` — стоимость за 1 единицу
- `amount` — общая стоимость


### Добавление товаров в заказ (= создание Reservation) ⚠ backend bug

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/orders/{id}/nomenclatures`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

⚠ **Backend bug:** endpoint часто возвращает `500` на корректных входных данных. Bypass: дождаться фикса бэка либо использовать E-Commerce flow (`POST /api/counterparty/orders`), который создаёт резервации внутри транзакции.

**NB:** под капотом этот endpoint создаёт запись `Reservation` (см. erp-rules §18.7). `{id}` в `PUT`/`DELETE …/nomenclatures/{id}` — это id записи `Reservation`, не `nomenclature_id`.

#### Параметры запроса

⚠ Реальный minimum (`OrderNomenclature/StoreRequest`): только `quantity` (min:1). Остальные — опциональны.

- `quantity` *(int, обязательно)* — кол-во, ≥ 1
- `nomenclature_id` *(int, опционально)* — ID номенклатуры из `GET /api/nomenclatures`. Без него резерв создаётся без привязки к конкретному товару.
- `storage_unit_id` *(int, опционально)* — ID единицы измерения (`GET /api/storage_units`)
- `price` *(string, опционально)* — цена decimal-string (`"1000.00"`)
- `vat_id` *(int, опционально)* — ID ставки НДС (`GET /api/vats`)

#### Пример запроса

```json
{
    "nomenclature_id": 1,
    "quantity": 1,
    "storage_unit_id": 1,
    "price": 100,
    "vat_id": 1
}
```

#### Ответ

При успешном действии возвращается HTTP код `201`.

```json
{
    "id": 23,
    "orderNomenclature": {
        "warehouseNomenclature": {
            "id": 1,
            "avatar": "http://localhost:8000//storage/uploads/kcdDZKHha8HbujO4z80uYmOsayHHxTXZrM2q6GEN.webp",
            "name": "BANILA CO Glow Fit Foundation Brush / Склад Петухова / 5 ед / 204500.00 руб"
        },
        "quantity": 1,
        "unit": {
            "id": 1,
            "name": "Литр",
            "avatar": "http://localhost:8000/storage/uploads/default.svg",
            "created_at": "2024-06-24T09:57:10.000000Z"
        },
        "price": "1.00",
        "vat": {
            "id": 1,
            "name": "Без НДС",
            "avatar": "http://localhost:8000/storage/uploads/default.svg",
            "created_at": "2024-08-12T08:51:40.000000Z"
        },
        "amount": "1.00"
    }
}
```

##### Описание полей ответа

- `id` — ID (первичный ключ) товарной позиции в заказе
- `warehouseNomenclature` — объект с информацией о товаре, хранимом на складе
- `quantity` — кол-во товара
- `unit` — объект с информацией о единицах измерения
- `price` — цена товара
- `vat` — НДС
- `amount` — общая стоимость товарной позиции


### Обновление товаров в заказе

**Метод:** PUT  
**URL:** `https://api.gigma.ru/api/orders/{id}/nomenclatures/{nomenclatureId}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `nomenclature_id` — ID номенклатуры (`GET /api/nomenclatures`)
- `quantity` — кол-во товара
- `storage_unit_id` — ID единицы измерения
- `price` — стоимость товара
- `vat_id` — ID НДС

#### Пример запроса

```json
{
    "nomenclature_id": 1,
    "quantity": 1,
    "storage_unit_id": 1,
    "price": 100,
    "vat_id": 1
}
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "id": 23,
    "orderNomenclature": {
        "warehouseNomenclature": {
            "id": 1,
            "avatar": "http://localhost:8000//storage/uploads/kcdDZKHha8HbujO4z80uYmOsayHHxTXZrM2q6GEN.webp",
            "name": "BANILA CO Glow Fit Foundation Brush / Склад Петухова / 5 ед / 204500.00 руб"
        },
        "quantity": 1,
        "unit": {
            "id": 1,
            "name": "Литр",
            "avatar": "http://localhost:8000/storage/uploads/default.svg",
            "created_at": "2024-06-24T09:57:10.000000Z"
        },
        "price": "1.00",
        "vat": {
            "id": 1,
            "name": "Без НДС",
            "avatar": "http://localhost:8000/storage/uploads/default.svg",
            "created_at": "2024-08-12T08:51:40.000000Z"
        },
        "amount": "1.00"
    }
}
```

##### Описание полей ответа

- `id` — ID (первичный ключ) товарной позиции в заказе
- `warehouseNomenclature` — объект с информацией о товаре, хранимом на складе
- `quantity` — кол-во товара
- `unit` — объект с информацией о единицах измерения
- `price` — цена товара
- `vat` — НДС
- `amount` — общая стоимость товарной позиции


### Удаление товаров из заказа

**Метод:** DELETE  
**URL:** `https://api.gigma.ru/api/orders/{id}/nomenclatures/{nomenclatureId}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/orders/16/nomenclatures/28
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "message": "Order nomenclature deleted"
}
```

##### Описание полей ответа

- `message` — информационное поле


## Файлы

### Получение списка файлов (табличное представление)

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/tables/orders/{id}/files`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/tables/orders/18/files
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "columns": [
        {"id": 34, "table_id": 5, "order": 0, "key": "id", "has_icon": 0, "text": "№"},
        {"id": 35, "table_id": 5, "order": 1, "key": "created_at", "has_icon": 0, "text": "Дата"},
        {"id": 36, "table_id": 5, "order": 2, "key": "creator", "has_icon": 1, "text": "Создатель"},
        {"id": 37, "table_id": 5, "order": 3, "key": "name", "has_icon": 0, "text": "Название"},
        {"id": 38, "table_id": 5, "order": 3, "key": "path", "has_icon": 0, "text": "Ссылка"}
    ],
    "files": [
        {
            "id": 4,
            "creator": {
                "icon": "http://localhost:8000/storage/uploads/default.svg",
                "value": "Полищук Артём"
            },
            "name": "Rating container.svg",
            "path": "http://localhost:8000/storage/uploads/u7TY0sLEoWiFgeglUHHbWgchUIS41yhAPZ0uMuYX.svg",
            "created_at": "18.04.2024 13:50"
        }
    ],
    "pagination": {
        "total": 1,
        "per_page": 10,
        "current_page": 1,
        "last_page": 1,
        "from": 1,
        "to": 1
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — имя файла
- `creator` — создатель файла
- `path` — ссылка на загрузку файла
- `created_at` — дата/время загрузки файла


### Добавление файла

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/orders/{id}/files`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `file` — загружаемый документ

#### Пример запроса

```json
{
    "file": "FILE('path')"
}
```

#### Ответ

При успешном действии возвращается HTTP код `201`.

```json
{
    "file": {
        "id": 593,
        "name": "Инфо Агбис (2).txt",
        "type": {
            "id": 3,
            "name": "Документ к заказу",
            "avatar": "http://localhost:8000/storage/uploads/default.svg",
            "created_at": "2024-03-27T07:00:46.000000Z"
        },
        "path": "http://localhost:8000/storage/uploads/QWu9ghBy6kfsXsEQZBuIqhpEoY8ghrCIFZhBdpwj.txt",
        "created_at": "2024-07-31T07:06:37.000000Z",
        "updated_at": "2024-07-31T07:06:37.000000Z"
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — имя файла
- `type` — объект с информацией о типе загружаемого файла
- `path` — ссылка на загрузку файла
- `created_at` — дата/время загрузки файла
- `updated_at` — дата/время последнего обновления файла


### Удаление файла

Удаление файла из заказа полностью аналогично стандартному удалению файла. См. соответствующий запрос на странице "Файлы".

## История изменений

### Получение истории изменений по заказу

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/orders/{id}/history`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/orders/18/history
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "orders": {
        "current_page": 1,
        "data": [
            {
                "id": 1,
                "icon": "done",
                "color": "success",
                "title": "Создан заказ №18",
                "description": "Создал(-а) Артём Полищук",
                "dateTime": "31.07.2024"
            },
            {
                "id": 2,
                "icon": "done",
                "color": "success",
                "title": "Отредактирован заказ №18",
                "description": "Отредактировал(-а) Артём Полищук",
                "dateTime": "31.07.2024"
            }
        ],
        "first_page_url": "http://192.168.0.43:8000/api/orders/18/history?page=1",
        "from": 1,
        "last_page": 1,
        "last_page_url": "http://192.168.0.43:8000/api/orders/18/history?page=1",
        "links": [
            {
                "url": null,
                "label": "&laquo; Предыдущая",
                "active": false
            },
            {
                "url": "http://192.168.0.43:8000/api/orders/18/history?page=1",
                "label": "1",
                "active": true
            },
            {
                "url": null,
                "label": "Следующая &raquo;",
                "active": false
            }
        ],
        "next_page_url": null,
        "path": "http://192.168.0.43:8000/api/orders/18/history",
        "per_page": 10,
        "prev_page_url": null,
        "to": 2,
        "total": 2
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `icon` — иконка
- `color` — цвет
- `title` — заголовок
- `description` — описание


## Запрос возврата

### Запрос возврата по заказу

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/orders/{id}/request-refund`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

Создаёт запрос на возврат по заказу. Фиксирует время запроса, инициатора и комментарий.

#### Параметры запроса

- `comment` *(string, опционально)* — причина возврата

#### Пример запроса

```json
{
    "comment": "Товар не подошёл по размеру"
}
```

#### Ответ

При успешном действии возвращается HTTP код `200` с обновлённым объектом заказа (те же поля, что и в `GET /api/orders/{id}`).

---

## Задачи команды

Source: https://docs.gigma.ru/ERP/%D0%97%D0%B0%D0%B4%D0%B0%D1%87%D0%B8/

# Задачи

> ⚠ **DELETE не поддерживается.** `Route::resource('tasks', ...)->except(['destroy'])` — маршрут удаления не зарегистрирован. Запрос `DELETE /api/tasks/{id}` вернёт `405 Method Not Allowed`.

### Получение списка задач (табличное представление)

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/tables/tasks`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `query` — поисковая строка (min: 3 символа)
- `date_from` — фильтр по дате (от)
- `date_to` — фильтр по дате (до)
- `creator_id[]` — массив ID создателей задачи
- `executor_id[]` — массив ID исполнителей задачи
- `order_id[]` — массив ID заказов
- `task_status_id[]` — массив ID статусов (`GET /api/task_statuses`): 1=В работе, 2=Просрочена, 3=Выполнена
- `page` — текущая страница
- `per_page` — кол-во элементов на странице

#### Пример запроса

```
https://api.gigma.ru/api/tables/tasks?task_status_id[]=1&executor_id[]=5
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "columns": [
        {"id": 1, "table_id": 3, "order": 0, "key": "id", "has_icon": 0, "text": "№"},
        {"id": 2, "table_id": 3, "order": 1, "key": "name", "has_icon": 0, "text": "Название"},
        {"id": 3, "table_id": 3, "order": 2, "key": "executor", "has_icon": 1, "text": "Исполнитель"},
        {"id": 4, "table_id": 3, "order": 3, "key": "status", "has_icon": 0, "text": "Статус"},
        {"id": 5, "table_id": 3, "order": 4, "key": "started_at", "has_icon": 0, "text": "Начало"},
        {"id": 6, "table_id": 3, "order": 5, "key": "finished_at", "has_icon": 0, "text": "Срок"}
    ],
    "tasks": [
        {
            "id": 12,
            "name": "Позвонить клиенту",
            "executor": {
                "icon": "https://api.gigma.ru/storage/uploads/default.svg",
                "value": "Иванов Алексей"
            },
            "status": {
                "icon": "https://api.gigma.ru/storage/uploads/default.svg",
                "value": "В работе"
            },
            "started_at": "16.05.2026 09:00",
            "finished_at": "16.05.2026 18:00"
        }
    ],
    "pagination": {
        "total": 1,
        "per_page": 10,
        "current_page": 1,
        "last_page": 1,
        "from": 1,
        "to": 1
    }
}
```

##### Описание полей ответа

- `columns` — массив столбцов таблицы
- `tasks` — массив задач
- `pagination` — объект пагинации


### Получение списка задач (JSON)

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/tasks`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Те же фильтры, что и в табличном представлении.

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "tasks": [
        {
            "id": 12,
            "name": "Позвонить клиенту",
            "started_at": "2026-05-16T09:00:00.000000Z",
            "finished_at": "2026-05-16T18:00:00.000000Z",
            "create_everyday": false,
            "duration": "9 ч",
            "executor": {
                "id": 5,
                "name": "Иванов Алексей"
            },
            "creator": {
                "id": 1,
                "name": "Полищук Артём"
            },
            "status": {
                "id": 1,
                "name": "В работе"
            },
            "order": {
                "id": 42,
                "name": "Заказ №42"
            },
            "object": null,
            "notifications": [],
            "stage": null,
            "progress": null
        }
    ],
    "tasksCount": 1
}
```


### Получение выбранной задачи

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/tasks/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/tasks/12
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "task": {
        "id": 12,
        "name": "Позвонить клиенту",
        "started_at": "2026-05-16T09:00:00.000000Z",
        "finished_at": "2026-05-16T18:00:00.000000Z",
        "created_at": "2026-05-16T08:00:00.000000Z",
        "create_everyday": false,
        "duration": "9 ч",
        "executor": {
            "id": 5,
            "name": "Иванов Алексей"
        },
        "creator": {
            "id": 1,
            "name": "Полищук Артём"
        },
        "status": {
            "id": 1,
            "name": "В работе"
        },
        "order": {
            "id": 42,
            "name": "Заказ №42"
        },
        "object": null,
        "notifications": [],
        "stage": null,
        "progress": null
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — название задачи
- `started_at` — дата/время начала
- `finished_at` — дата/время срока выполнения
- `created_at` — дата/время создания записи
- `create_everyday` — повторять каждый день (boolean)
- `duration` — строка длительности (`"9 ч"`)
- `executor` — объект исполнителя
- `creator` — объект создателя задачи
- `status` — объект статуса (`GET /api/task_statuses`)
- `order` — объект связанного заказа
- `object` — произвольная строка-метка объекта
- `notifications` — массив отделов, получающих уведомление (`GET /api/departments`)
- `stage` / `progress` — этап и прогресс (опционально)


### Создание задачи

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/tasks`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `name` *(string, обязательно)* — название задачи
- `started_at` *(datetime, обязательно)* — дата/время начала, ISO 8601
- `finished_at` *(datetime, обязательно)* — дата/время срока, ISO 8601, должна быть позже `started_at`
- `executor_id` *(int, обязательно)* — ID исполнителя (`GET /api/users`)
- `order_id` *(int, обязательно)* — ID заказа (`GET /api/orders`)
- `object` *(string, опционально)* — произвольная метка объекта
- `create_everyday` *(boolean, опционально)* — повторять задачу ежедневно
- `notifications` *(int[], опционально)* — массив ID отделов для уведомлений (`GET /api/departments`)

#### Пример запроса

```json
{
    "name": "Позвонить клиенту",
    "started_at": "2026-05-17 09:00:00",
    "finished_at": "2026-05-17 18:00:00",
    "executor_id": 5,
    "order_id": 42,
    "create_everyday": false,
    "notifications": [1, 2]
}
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "task": {
        "id": 13,
        "name": "Позвонить клиенту",
        "started_at": "2026-05-17T09:00:00.000000Z",
        "finished_at": "2026-05-17T18:00:00.000000Z",
        "created_at": "2026-05-17T08:30:00.000000Z",
        "create_everyday": false,
        "duration": "9 ч",
        "executor": { "id": 5, "name": "Иванов Алексей" },
        "creator": { "id": 1, "name": "Полищук Артём" },
        "status": { "id": 1, "name": "В работе" },
        "order": { "id": 42, "name": "Заказ №42" },
        "object": null,
        "notifications": [
            { "id": 1, "name": "Технический" },
            { "id": 2, "name": "Коммерческий" }
        ],
        "stage": null,
        "progress": null
    }
}
```


### Редактирование задачи

**Метод:** PUT  
**URL:** `https://api.gigma.ru/api/tasks/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Все поля опциональны. Можно обновить любое из них.

- `task_status_id` *(int)* — ID нового статуса: 1=В работе, 2=Просрочена, 3=Выполнена
- `name` *(string)* — название задачи
- `started_at` *(datetime)* — дата/время начала, ISO 8601
- `finished_at` *(datetime)* — дата/время срока, ISO 8601, после `started_at`
- `executor_id` *(int)* — ID исполнителя
- `order_id` *(int)* — ID заказа
- `object` *(string)* — метка объекта
- `create_everyday` *(boolean)* — ежедневное повторение
- `notifications` *(int[])* — массив ID отделов

#### Пример запроса (смена статуса)

```json
{
    "task_status_id": 3
}
```

#### Ответ

При успешном действии возвращается HTTP код `200`. Возвращаемый объект `task` аналогичен ответу `GET /api/tasks/{id}`.

---

## Контентные блоки

Source: https://docs.gigma.ru/ERP/%D0%91%D0%BB%D0%BE%D0%BA%D0%B8/

# Блоки

### Получение списка блоков (табличное представление)

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/tables/applications/{id}/blocks`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `applications/{id}` — ID приложения из списка приложений
- `query` — поисковая строка

#### Пример запроса

```
https://api.gigma.ru/api/tables/applications/30/blocks
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "columns": [
        {
            "id": 149,
            "table_id": 19,
            "order": 0,
            "key": "code",
            "has_icon": 0,
            "text": "Код"
        },
        {
            "id": 150,
            "table_id": 19,
            "order": 1,
            "key": "date",
            "has_icon": 0,
            "text": "Дата"
        },
        {
            "id": 151,
            "table_id": 19,
            "order": 2,
            "key": "name",
            "has_icon": 1,
            "text": "Название"
        },
        {
            "id": 152,
            "table_id": 19,
            "order": 3,
            "key": "path",
            "has_icon": 0,
            "text": "Путь"
        },
        {
            "id": 153,
            "table_id": 19,
            "order": 4,
            "key": "block_type",
            "has_icon": 1,
            "text": "Тип блока"
        },
        {
            "id": 154,
            "table_id": 19,
            "order": 5,
            "key": "creator",
            "has_icon": 1,
            "text": "Создал"
        }
    ],
    "blocks": [
        {
            "id": {
                "icon": null,
                "value": 7,
                "url": ""
            },
            "date": "25 янв 2025",
            "name": {
                "icon": "https://api.gigma.ru/storage/uploads/default.svg",
                "value": "Видео на главной странице"
            },
            "path": "> Главная > Видео на главной странице",
            "block_type": {
                "icon": "https://api.gigma.ru/api//storage/uploads/image-profile-2.svg",
                "value": "Картинка"
            },
            "creator": {
                "icon": "https://api.gigma.ru/api//storage/uploads/cdO1uLpgY29TgnFLhaJWQkjK8VDxMg2fk3dp0ihW.png",
                "value": "Воронова София",
                "link": "https://beta.gigma.ru/users/list-users/66"
            }
        }
    ],
    "pagination": {
        "total": 1,
        "per_page": 10,
        "current_page": 1,
        "last_page": 1,
        "from": 1,
        "to": 1
    }
}
```

##### Описание полей ответа

- `columns` — массив столбцов
- `pagination` — объект с информацией, необходимой для пагинации
- `id` — первичный ключ (номер заказа)
- `name` — название блока
- `block_type` — объект с информацией о типе блока


### Получение списка блоков

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/applications/{id}/blocks`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `applications/{id}` — ID приложения из списка приложений
- `query` — поисковая строка

#### Пример запроса

```
https://api.gigma.ru/api/applications/30/blocks
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
[
    {
        "id": 8,
        "code": 1,
        "name": "Первый блок (текстовый)",
        "avatar": null,
        "block_type": {
            "id": 1,
            "name": "Обычный текст",
            "avatar": "https://api.gigma.ru/api//storage/uploads/image-profile-1.svg",
            "created_at": "2025-01-23T09:47:38.000000Z"
        },
        "link": null,
        "file": null,
        "text": "Текст",
        "parent": null,
        "children": [
            {
                "id": 9,
                "code": 2,
                "name": "Второй блок",
                "avatar": null,
                "block_type": {
                    "id": 5,
                    "name": "URL ссылка",
                    "avatar": "https://api.gigma.ru/api//storage/uploads/image-profile-4.svg",
                    "created_at": "2025-01-23T09:47:38.000000Z"
                },
                "link": "https://yandex.ru",
                "file": null,
                "text": null,
                "parent": {
                    "id": 8,
                    "name": "Первый блок (текстовый)"
                },
                "children": [
                    {
                        "id": 10,
                        "code": 3,
                        "name": "Третий блок",
                        "avatar": null,
                        "block_type": {
                            "id": 3,
                            "name": "Картинка",
                            "avatar": "https://api.gigma.ru/api//storage/uploads/image-profile-2.svg",
                            "created_at": "2025-01-23T09:47:38.000000Z"
                        },
                        "link": null,
                        "file": {
                            "id": 2827,
                            "name": "Da Chirillo - Колбасы и деликатесы премиум качества.png",
                            "type": {
                                "id": 1,
                                "name": "Трудовой договор",
                                "avatar": "https://api.gigma.ru/storage/uploads/default.svg",
                                "created_at": "2024-03-27T07:00:46.000000Z"
                            },
                            "path": "https://api.gigma.ru/storage/uploads/IcnkXX2tyYQcFtuNOYEsbrgRX13T1IVkeyTTHxqH.png",
                            "link": null,
                            "created_at": "2025-01-27T14:17:14.000000Z",
                            "updated_at": "2025-01-27T14:17:14.000000Z"
                        },
                        "text": null,
                        "parent": {
                            "id": 9,
                            "name": "Второй блок"
                        },
                        "children": [],
                        "created_at": "2025-01-27T14:17:14.000000Z"
                    }
                ],
                "created_at": "2025-01-27T14:12:38.000000Z"
            },
            {
                "id": 11,
                "code": 4,
                "name": "Четвертый блок",
                "avatar": null,
                "block_type": {
                    "id": 2,
                    "name": "Длинный текст",
                    "avatar": "https://api.gigma.ru/api//storage/uploads/image-profile-1.svg",
                    "created_at": "2025-01-23T09:47:38.000000Z"
                },
                "link": null,
                "file": null,
                "text": "<p>Привет!</p>",
                "parent": {
                    "id": 8,
                    "name": "Первый блок (текстовый)"
                },
                "children": [],
                "created_at": "2025-01-27T14:23:07.000000Z"
            }
        ],
        "created_at": "2025-01-27T13:03:19.000000Z"
    }
]
```

##### Описание полей ответа

Возвращаемые поля аналогичны запросу получения выбранного блока.


### Получение выбранного блока

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/applications/{id}/blocks/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `applications/{id}` — ID приложения из списка приложений

#### Пример запроса

```
https://api.gigma.ru/api/applications/30/blocks/9
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "block": {
        "id": 10,
        "code": 3,
        "name": "Третий блок",
        "avatar": {
            "id": 2827,
            "name": "Da Chirillo - Колбасы и деликатесы премиум качества.png",
            "type": {
                "id": 1,
                "name": "Трудовой договор",
                "avatar": "https://api.gigma.ru/storage/uploads/default.svg",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            "path": "https://api.gigma.ru/storage/uploads/IcnkXX2tyYQcFtuNOYEsbrgRX13T1IVkeyTTHxqH.png",
            "link": null,
            "created_at": "2025-01-27T14:17:14.000000Z",
            "updated_at": "2025-01-27T14:17:14.000000Z"
        },
        "block_type": {
            "id": 3,
            "name": "Картинка",
            "avatar": "https://api.gigma.ru/api//storage/uploads/image-profile-2.svg",
            "created_at": "2025-01-23T09:47:38.000000Z"
        },
        "link": null,
        "file": {
            "id": 2827,
            "name": "Da Chirillo - Колбасы и деликатесы премиум качества.png",
            "type": {
                "id": 1,
                "name": "Трудовой договор",
                "avatar": "https://api.gigma.ru/storage/uploads/default.svg",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            "path": "https://api.gigma.ru/storage/uploads/IcnkXX2tyYQcFtuNOYEsbrgRX13T1IVkeyTTHxqH.png",
            "link": null,
            "created_at": "2025-01-27T14:17:14.000000Z",
            "updated_at": "2025-01-27T14:17:14.000000Z"
        },
        "text": null,
        "parent": {
            "id": 9,
            "name": "Второй блок"
        },
        "children": [],
        "created_at": "2025-01-27T14:17:14.000000Z"
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ (номер блока)
- `code` — код блока
- `name` — название блока
- `avatar` — объект с информацией об аватаре
- `block_type` — объект с информацией о типе блока
- `link` — URL ссылка
- `file` — объект с информацией о прикреплённом файле
- `text` — текстовый контент блока
- `children` — массив объектов типа "Блок", которые являются подчиненными сущностями выбранного элемента
- `created_at` — дата добавления в систему


### Добавление блока

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/applications/{id}/blocks`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `applications/{id}` — ID приложения из списка приложений
- `block_type_id` — ID типа блока из справочника
- `name` — имя блока
- `link` — URL ссылка. Обязателен, если `block_type_id` = 4 или `block_type_id` = 5
- `avatar_id` — ID аватара, загруженного при помощи запроса добавления файла
- `file_id` — ID прикрепляемого файла, загруженного при помощи запроса добавления файла. Обязателен, если `block_type_id` = 3
- `text` — текстовый контент блока. Обязателен, если `block_type_id` = 1 или `block_type_id` = 2
- `parent_id` — ID родительского блока из запроса получения списка блоков

#### Пример запроса

```json
{
    "block_type_id": 3,
    "name": "Параметр 1",
    "link": null,
    "avatar_id": 1,
    "file_id": 1,
    "text": null,
    "parent_id": 1
}
```

#### Ответ

При успешном действии возвращается HTTP код `201`.

```json
{
    "block": {
        "id": 5,
        "code": 5,
        "name": "Параметр 1",
        "avatar": {
            "id": 1,
            "name": "logo.svg",
            "type": {
                "id": 1,
                "name": "Трудовой договор",
                "avatar": "https://api.gigma.ru/storage/uploads/default.svg",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            "path": "https://api.gigma.ru/storage/uploads/yjohncMkjTSnvJ7FH4vksOtDYUy9pO2HDwmNU5Hc.svg",
            "link": null,
            "created_at": "2024-04-14T20:04:32.000000Z",
            "updated_at": "2024-04-14T20:04:32.000000Z"
        },
        "block_type": {
            "id": 3,
            "name": "Картинка",
            "avatar": "https://api.gigma.ru/api//storage/uploads/image-profile-2.svg",
            "created_at": "2025-01-23T09:47:38.000000Z"
        },
        "link": null,
        "file": {
            "id": 1,
            "name": "logo.svg",
            "type": {
                "id": 1,
                "name": "Трудовой договор",
                "avatar": "https://api.gigma.ru/storage/uploads/default.svg",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            "path": "https://api.gigma.ru/storage/uploads/yjohncMkjTSnvJ7FH4vksOtDYUy9pO2HDwmNU5Hc.svg",
            "link": null,
            "created_at": "2024-04-14T20:04:32.000000Z",
            "updated_at": "2024-04-14T20:04:32.000000Z"
        },
        "text": null,
        "parent": {
            "id": 1,
            "name": "Видео рекламного слайдера"
        },
        "children": [],
        "created_at": "2025-01-23T17:59:03.000000Z"
    }
}
```

##### Описание полей ответа

Возвращаемые поля аналогичны запросу получения выбранного блока.


### Редактирование блока

**Метод:** PUT  
**URL:** `https://api.gigma.ru/api/applications/{id}/blocks/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `applications/{id}` — ID приложения из списка приложений
- `block_type_id` — ID типа блока из справочника
- `name` — имя блока
- `code` — код блока
- `link` — URL ссылка. Обязателен, если `block_type_id` = 4 или `block_type_id` = 5
- `avatar_id` — ID аватара, загруженного при помощи запроса добавления файла. Обязателен, если `block_type_id` = 3
- `file_id` — ID прикрепляемого файла, загруженного при помощи запроса добавления файла. Обязателен, если `block_type_id` = 3
- `text` — текстовый контент блока. Обязателен, если `block_type_id` = 1 или `block_type_id` = 2
- `parent_id` — ID родительского блока из запроса получения списка блоков

#### Пример запроса

```json
{
    "block_type_id": 3,
    "name": "Видео рекламного слайдера",
    "avatar_id": 2,
    "file_id": 2,
    "parent_id": 1,
    "code": 10
}
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "block": {
        "id": 2,
        "code": 10,
        "name": "Видео рекламного слайдера",
        "avatar": {
            "id": 2,
            "name": "logo.png",
            "type": {
                "id": 1,
                "name": "Трудовой договор",
                "avatar": "https://api.gigma.ru/storage/uploads/default.svg",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            "path": "https://api.gigma.ru/storage/uploads/igbcW8dPebcrVfnbC2A2Zptf1nruFcF8Nmf8sVTG.png",
            "link": null,
            "created_at": "2024-04-14T20:11:00.000000Z",
            "updated_at": "2024-04-14T20:11:00.000000Z"
        },
        "block_type": {
            "id": 3,
            "name": "Картинка",
            "avatar": "https://api.gigma.ru/api//storage/uploads/image-profile-2.svg",
            "created_at": "2025-01-23T09:47:38.000000Z"
        },
        "link": null,
        "file": {
            "id": 2,
            "name": "logo.png",
            "type": {
                "id": 1,
                "name": "Трудовой договор",
                "avatar": "https://api.gigma.ru/storage/uploads/default.svg",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            "path": "https://api.gigma.ru/storage/uploads/igbcW8dPebcrVfnbC2A2Zptf1nruFcF8Nmf8sVTG.png",
            "link": null,
            "created_at": "2024-04-14T20:11:00.000000Z",
            "updated_at": "2024-04-14T20:11:00.000000Z"
        },
        "text": null,
        "parent": {
            "id": 1,
            "name": "Видео рекламного слайдера"
        },
        "children": [],
        "created_at": "2025-01-23T17:44:00.000000Z"
    }
}
```

##### Описание полей ответа

Возвращаемые поля аналогичны запросу получения выбранного блока.


### Удаление блока

**Метод:** DELETE  
**URL:** `https://api.gigma.ru/api/applications/{id}/blocks/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `applications/{id}` — ID приложения из списка приложений

#### Пример запроса

```
https://api.gigma.ru/api/applications/30/blocks/1
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "message": "Block successfully deleted"
}
```

##### Описание полей ответа

- `message` — информационное поле


### Получение истории изменений по блоку

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/applications/{id}/blocks/{id}/history`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `applications/{id}` — ID приложения из списка приложений

#### Пример запроса

```
https://api.gigma.ru/api/applications/30/blocks/18/history
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "histories": [
        {
            "id": 2174,
            "icon": "check",
            "color": "primary",
            "title": "Создание",
            "description": "Создание: Воронова София",
            "datetime": "23.01.2025 15:57"
        }
    ],
    "historiesCount": 1
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `icon` — иконка
- `color` — цвет
- `title` — заголовок
- `description` — описание
- `datetime` — дата выполнения действия

---

## Страницы и публикации

Source: https://docs.gigma.ru/ERP/%D0%A1%D1%82%D1%80%D0%B0%D0%BD%D0%B8%D1%86%D1%8B/

# Страницы (контент)

### Получение списка страниц (табличное представление)

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/tables/pages`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `application_id` [required] — ID приложения
- `page_type_id` [nullable] — ID типа страницы
- `order_by` [nullable] — сортировка: `date_asc`, `date_desc`, `popularity_asc`, `popularity_desc`
- `query` [nullable] — поисковая строка
- `page` [nullable] — номер страницы для пагинации
- `per_page` [nullable] — элементов на странице

#### Пример запроса

```
https://api.gigma.ru/api/tables/pages?query=новость&application_id=23&page_type_id=1
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "columns": [
        {"id": 135, "table_id": 17, "order": 0, "key": "code", "has_icon": 0, "text": "Код"},
        {"id": 136, "table_id": 17, "order": 1, "key": "date", "has_icon": 0, "text": "Дата"},
        {"id": 137, "table_id": 17, "order": 2, "key": "title", "has_icon": 1, "text": "Название"},
        {"id": 138, "table_id": 17, "order": 3, "key": "type", "has_icon": 1, "text": "Тип контента"},
        {"id": 139, "table_id": 17, "order": 4, "key": "slug", "has_icon": 0, "text": "Slug"},
        {"id": 140, "table_id": 17, "order": 5, "key": "creator", "has_icon": 1, "text": "Создал"},
        {"id": 141, "table_id": 17, "order": 6, "key": "status", "has_icon": 0, "text": "Статус"}
    ],
    "contents": [
        {
            "id": 12,
            "code": null,
            "date": "13.05.2024",
            "title": {"icon": "https://beta.back.erp.itecho.ru/storage/uploads/default.svg", "value": "Создание идивидуальго проекта"},
            "type": {"icon": "https://beta.back.erp.itecho.ru/storage/uploads/default.svg", "value": "Страница"},
            "slug": "proektnye-raboty",
            "creator": {"icon": "https://beta.back.erp.itecho.ru/storage/uploads/hJsFVET0jAcRiqK3Zu2mdkFVFL4LktdrT6kB7la8.jpg", "value": "Иванов Василий", "link": "https://beta.gigma.ru/users/list-users/39"},
            "status": "Черновик"
        }
    ],
    "pagination": {
        "total": 9,
        "per_page": 1,
        "current_page": 1,
        "last_page": 9,
        "from": 1,
        "to": 1
    }
}
```

##### Описание полей ответа

- `columns` — массив столбцов таблицы
- `contents` — массив данных страниц (в табличном формате)
- `pagination` — информация для пагинации
- `id` — ID страницы
- `code` — код страницы
- `date` — дата создания (только в табличном представлении)
- `title` — название с иконкой
- `type` — тип страницы с иконкой
- `slug` — идентификатор URL
- `creator` — создатель с ссылкой
- `status` — статус публикации (только в табличном представлении; в ресурсе `GET /api/pages/{id}` этого поля нет)


### Получение выбранной страницы (контента)

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/pages/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/pages/12
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "page": {
        "id": 12,
        "code": null,
        "avatar": null,
        "is_page": true,
        "views_count": 27,
        "type": {
            "id": 1,
            "name": "Страница",
            "avatar": "https://beta.back.erp.itecho.ru/storage/uploads/default.svg",
            "created_at": "2024-10-31T11:14:22.000000Z"
        },
        "creator": {
            "id": 39,
            "avatar": "https://beta.back.erp.itecho.ru/storage/uploads/hJsFVET0jAcRiqK3Zu2mdkFVFL4LktdrT6kB7la8.jpg",
            "first_name": "Василий",
            "last_name": "Иванов",
            "middle_name": "Батькович",
            "name": "Иванов Василий"
        },
        "slug": "proektnye-raboty",
        "title": "Создание идивидуальго проекта",
        "meta_title": null,
        "preview": {
            "id": 2066,
            "name": "image1.png",
            "type": {
                "id": 1,
                "name": "Трудовой договор",
                "avatar": "https://beta.back.erp.itecho.ru/storage/uploads/default.svg",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            "path": "https://beta.back.erp.itecho.ru/storage/uploads/iT6Bvuu2DQrFIAF9SMkqnVtyh8uXvECkpIt4OkgR.png",
            "link": null,
            "created_at": "2024-11-13T09:51:36.000000Z",
            "updated_at": "2024-11-13T09:51:36.000000Z"
        },
        "description": "Создание идивидуальго проекта",
        "meta_description": null,
        "content": "<p>В нашем интернет-магазине вы можете недорого купить скрабы для очищения и отшелушивания кожи. У нас представлена корейская косметика самых известных брендов, с подробным описанием, составами и отзывами покупателей. Мы предлагаем вам отшелушивающие скрабы по выгодной цене с доставкой по всей России, как в пункты выдачи заказов, так и по вашему персональному адресу. Возможен наложенный платеж. </p>",
        "application": {
            "id": 23,
            "name": "https://nsksm.ru",
            "avatar": "https://beta.back.erp.itecho.ru/storage/uploads/default.svg",
            "created_at": "2024-10-08T08:46:23.000000Z"
        },
        "created_at": "2024-05-13T05:29:39.000000Z"
    }
}
```

##### Описание полей ответа

- `id` — ID страницы
- `code` — код страницы
- `avatar` — аватар страницы
- `is_page` — флаг (true=страница, false=блок)
- `views_count` — кол-во просмотров
- `type` — информация о типе
- `creator` — данные создателя
- `slug` — URL-идентификатор
- `title` — название
- `meta_title` — meta-заголовок
- `preview` — превью-изображение
- `description` — описание
- `meta_description` — meta-описание
- `content` — контент в формате HTML
- `application` — привязанное приложение
- `created_at` — дата создания


### Добавление страницы

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/pages`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `code` [nullable, unique] — код страницы
- `application_id` [required] — ID приложения
- `avatar_id` [nullable] — ID аватара
- `is_page` [required] — флаг типа (true/false)
- `page_type_id` [required] — ID типа страницы
- `slug` [required, unique] — slug
- `title` [required, min:3, max:255] — название
- `meta_title` [nullable, min:3, max:255] — meta-заголовок
- `preview_id` [nullable] — ID превью
- `description` [nullable] — описание
- `meta_description` [nullable] — meta-описание
- `content` [nullable] — HTML-контент
- `tags` [array, nullable] — массив ID тегов

#### Пример запроса

```
https://api.gigma.ru/api/pages
```

```json
{
    "code": "1235",
    "application_id": 23,
    "avatar_id": 1,
    "is_page": true,
    "page_type_id": 1,
    "slug": "news-3",
    "title": "Скоро запуск веб-сайта!",
    "meta_title": "Запуск веб-сайта на платформе gigma.ru",
    "preview_id": 1,
    "description": "Описание текстовом формате",
    "meta_description": "Meta описание",
    "content": "HTML content",
    "tags": [1, 2]
}
```

#### Ответ

При успешном действии возвращается HTTP код `201`.

```json
{
    "page": {
        "id": 36,
        "code": "1235",
        "avatar": {
            "id": 1,
            "name": "logo.svg",
            "type": {
                "id": 1,
                "name": "Трудовой договор",
                "avatar": "https://beta.back.erp.itecho.ru/storage/uploads/default.svg",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            "path": "https://beta.back.erp.itecho.ru/storage/uploads/yjohncMkjTSnvJ7FH4vksOtDYUy9pO2HDwmNU5Hc.svg",
            "link": null,
            "created_at": "2024-04-14T20:04:32.000000Z",
            "updated_at": "2024-04-14T20:04:32.000000Z"
        },
        "is_page": true,
        "views_count": null,
        "type": {
            "id": 1,
            "name": "Страница",
            "avatar": "https://beta.back.erp.itecho.ru/storage/uploads/default.svg",
            "created_at": "2024-10-31T11:14:22.000000Z"
        },
        "creator": {
            "id": 39,
            "avatar": "https://beta.back.erp.itecho.ru/storage/uploads/hJsFVET0jAcRiqK3Zu2mdkFVFL4LktdrT6kB7la8.jpg",
            "first_name": "Василий",
            "last_name": "Иванов",
            "middle_name": "Батькович",
            "name": "Иванов Василий"
        },
        "slug": "news-3",
        "title": "Скоро запуск веб-сайта!",
        "meta_title": "Запуск веб-сайта на платформе gigma.ru",
        "preview": {
            "id": 1,
            "name": "logo.svg",
            "type": {
                "id": 1,
                "name": "Трудовой договор",
                "avatar": "https://beta.back.erp.itecho.ru/storage/uploads/default.svg",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            "path": "https://beta.back.erp.itecho.ru/storage/uploads/yjohncMkjTSnvJ7FH4vksOtDYUy9pO2HDwmNU5Hc.svg",
            "link": null,
            "created_at": "2024-04-14T20:04:32.000000Z",
            "updated_at": "2024-04-14T20:04:32.000000Z"
        },
        "description": "Описание текстовом формате",
        "meta_description": "Meta описание",
        "content": "HTML content",
        "application": {
            "id": 23,
            "name": "https://nsksm.ru",
            "avatar": "https://beta.back.erp.itecho.ru/storage/uploads/default.svg",
            "created_at": "2024-10-08T08:46:23.000000Z"
        },
        "tags": [
            {
                "id": 1,
                "name": "Важное",
                "avatar": "http://localhost:8000/storage/uploads/default.svg",
                "created_at": "2024-11-14T14:01:51.000000Z"
            },
            {
                "id": 2,
                "name": "Продукция",
                "avatar": "http://localhost:8000/storage/uploads/default.svg",
                "created_at": "2024-11-14T14:01:51.000000Z"
            }
        ],
        "created_at": "2024-11-27T09:34:29.000000Z"
    }
}
```

##### Описание полей ответа

Поля соответствуют запросу получения выбранной страницы.


### Редактирование страницы (контента)

**Метод:** PUT  
**URL:** `https://api.gigma.ru/api/pages/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `code` [nullable, unique] — код страницы
- `application_id` [required] — ID приложения
- `avatar_id` [nullable] — ID аватара
- `is_page` [required] — флаг (true/false)
- `page_type_id` [required] — ID типа страницы
- `slug` [required, unique] — slug
- `title` [required, min:3, max:255] — название
- `meta_title` [nullable, min:3, max:255] — meta-заголовок
- `preview_id` [nullable] — ID превью
- `description` [nullable] — описание
- `meta_description` [nullable] — meta-описание
- `content` [nullable] — HTML-контент
- `tags` [array, nullable] — массив ID тегов

#### Пример запроса

```
https://api.gigma.ru/api/pages/36
```

```json
{
    "code": "1235",
    "application_id": 23,
    "avatar_id": 1,
    "is_page": true,
    "page_type_id": 1,
    "slug": "news-3",
    "title": "Скоро запуск веб-сайта!",
    "meta_title": "Запуск веб-сайта на платформе gigma.ru",
    "preview_id": 1,
    "description": "Описание текстовом формате",
    "meta_description": "Meta описание",
    "content": "HTML content",
    "tags": [1]
}
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "page": {
        "id": 36,
        "code": "1235",
        "avatar": {
            "id": 1,
            "name": "logo.svg",
            "type": {
                "id": 1,
                "name": "Трудовой договор",
                "avatar": "https://beta.back.erp.itecho.ru/storage/uploads/default.svg",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            "path": "https://beta.back.erp.itecho.ru/storage/uploads/yjohncMkjTSnvJ7FH4vksOtDYUy9pO2HDwmNU5Hc.svg",
            "link": null,
            "created_at": "2024-04-14T20:04:32.000000Z",
            "updated_at": "2024-04-14T20:04:32.000000Z"
        },
        "is_page": true,
        "views_count": 0,
        "type": {
            "id": 1,
            "name": "Страница",
            "avatar": "https://beta.back.erp.itecho.ru/storage/uploads/default.svg",
            "created_at": "2024-10-31T11:14:22.000000Z"
        },
        "creator": {
            "id": 39,
            "avatar": "https://beta.back.erp.itecho.ru/storage/uploads/hJsFVET0jAcRiqK3Zu2mdkFVFL4LktdrT6kB7la8.jpg",
            "first_name": "Василий",
            "last_name": "Иванов",
            "middle_name": "Батькович",
            "name": "Иванов Василий"
        },
        "slug": "news-3",
        "title": "Скоро запуск веб-сайта!",
        "meta_title": "Запуск веб-сайта на платформе gigma.ru",
        "preview": {
            "id": 1,
            "name": "logo.svg",
            "type": {
                "id": 1,
                "name": "Трудовой договор",
                "avatar": "https://beta.back.erp.itecho.ru/storage/uploads/default.svg",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            "path": "https://beta.back.erp.itecho.ru/storage/uploads/yjohncMkjTSnvJ7FH4vksOtDYUy9pO2HDwmNU5Hc.svg",
            "link": null,
            "created_at": "2024-04-14T20:04:32.000000Z",
            "updated_at": "2024-04-14T20:04:32.000000Z"
        },
        "description": "Описание текстовом формате",
        "meta_description": "Meta описание",
        "content": "HTML content",
        "application": {
            "id": 23,
            "name": "https://nsksm.ru",
            "avatar": "https://beta.back.erp.itecho.ru/storage/uploads/default.svg",
            "created_at": "2024-10-08T08:46:23.000000Z"
        },
        "tags": [
            {
                "id": 1,
                "name": "Важное",
                "avatar": "http://localhost:8000/storage/uploads/default.svg",
                "created_at": "2024-11-14T14:01:51.000000Z"
            }
        ],
        "created_at": "2024-11-27T09:34:29.000000Z"
    }
}
```

##### Описание полей ответа

Поля соответствуют запросу получения выбранной страницы.


### Удаление страницы (контента)

**Метод:** DELETE  
**URL:** `https://api.gigma.ru/api/pages/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/pages/41
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "message": "Page successfully destroyed"
}
```

##### Описание полей ответа

- `message` — информационное сообщение о результате операции


### Получение истории изменений страницы

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/pages/{page}/history`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200` с записями истории: `id`, `icon`, `color`, `title`, `description`, `datetime`.


### Получение списка тегов

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/page_tags`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/page_tags
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "pageTags": [
        {
            "id": 1,
            "name": "Важное",
            "avatar": "http://localhost:8000/storage/uploads/default.svg",
            "created_at": "2024-11-14T14:01:51.000000Z"
        },
        {
            "id": 2,
            "name": "Продукция",
            "avatar": "http://localhost:8000/storage/uploads/default.svg",
            "created_at": "2024-11-14T14:01:51.000000Z"
        }
    ],
    "pageTagsCount": 2
}
```

##### Описание полей ответа

- `id` — первичный ключ тега
- `name` — название тега
- `avatar` — URL аватара
- `created_at` — дата добавления в систему
- `pageTagsCount` — общее количество тегов

---

## Меню сотрудников

Source: https://docs.gigma.ru/ERP/%D0%9C%D0%B5%D0%BD%D1%8E/

# Меню

Меню — это иерархическое дерево пунктов навигации, привязанное к пользователю. Группа endpoint'ов делится на чтение (отрисовать sidebar) и шаблонные операции (скопировать меню между пользователями/проектами, сохранить как шаблон).

## Чтение текущего меню

### Меню текущего пользователя

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/menus`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

Возвращает корневое меню текущего авторизованного пользователя (определяется по Bearer токену).

#### Ответ

```json
{
    "menus": [
        {
            "id": 1,
            "name": "Главное меню",
            "is_default": true,
            "created_at": "2024-03-27T07:00:46.000000Z"
        }
    ]
}
```


### Пункты меню по умолчанию

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/menus/default/items`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

Возвращает дерево пунктов меню по умолчанию (то, что показывается в sidebar админки).

#### Ответ

```json
{
    "menuItems": [
        {
            "id": 1,
            "menu_id": 1,
            "parent_id": null,
            "avatar": "https://api.gigma.ru/storage/uploads/dashboard.svg",
            "name": "Дашборд",
            "url": "/dashboard",
            "children": []
        },
        {
            "id": 2,
            "menu_id": 1,
            "parent_id": null,
            "avatar": "https://api.gigma.ru/storage/uploads/orders.svg",
            "name": "Заказы",
            "url": "/orders",
            "children": [
                {
                    "id": 3,
                    "menu_id": 1,
                    "parent_id": 2,
                    "avatar": "https://api.gigma.ru/storage/uploads/orders-list.svg",
                    "name": "Список заказов",
                    "url": "/orders/list",
                    "children": []
                }
            ]
        }
    ],
    "menuItemsCount": 3
}
```

##### Описание полей ответа

- `menuItems[]` — пункты меню в виде дерева:
  - `id` — ID пункта
  - `menu_id` — ID меню-владельца
  - `parent_id` — ID родителя (`null` для корневых)
  - `avatar` — URL иконки
  - `name` — отображаемое название
  - `url` — путь, на который ведёт пункт (опционально, у группирующих пунктов отсутствует)
  - `children[]` — массив дочерних пунктов (рекурсивно)
- `menuItemsCount` — общее количество пунктов


## Шаблонные операции

### Скопировать меню текущего пользователя указанному

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/users/{id}/attach_menu`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

Берёт меню текущего (авторизованного) пользователя и привязывает его к пользователю с указанным `id`. Тело запроса пустое — оба меню определяются из контекста: текущий пользователь по токену, целевой по URL.

#### Параметры запроса

Только `id` целевого пользователя в пути URL. Тело пустое.

#### Пример запроса

```
POST https://api.gigma.ru/api/users/51/attach_menu
```

#### Ответ

```json
{
    "message": "Menu has been attached."
}
```


### Скопировать меню текущего пользователя всем пользователям проекта

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/attach_menu_to_project`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

Берёт меню текущего пользователя и применяет его ко всем пользователям его текущего проекта (бизнеса).

#### Параметры запроса

Тело пустое.

#### Ответ

```json
{
    "message": "Menu has been attached."
}
```


### Сохранить меню пользователя как шаблон

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/users/{id}/create_menu_from_user_items`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

Создаёт новое именованное меню (шаблон) на основе текущего меню указанного пользователя.

#### Параметры запроса (тело)

- `name` — название нового меню

#### Пример запроса

```
POST https://api.gigma.ru/api/users/51/create_menu_from_user_items
```

```json
{
    "name": "Главное меню (Retail)"
}
```

#### Ответ

```json
{
    "message": "Menu has been created."
}
```

---

## Файлы и медиа

Source: https://docs.gigma.ru/ERP/%D0%A4%D0%B0%D0%B9%D0%BB%D1%8B/

# Файлы

Файлы загружаются как `multipart/form-data` через `POST /api/files`. Каждый файл привязан к типу из справочника `file_types` (трудовой договор, аватар, и т.п.).

## Файлы

### Загрузка файла

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/files`  
**Авторизация:** Bearer token  
**Headers:** `Content-Type: multipart/form-data; Accept: application/json`  

#### Параметры запроса (form-data)

- `file` — содержимое файла (обязательно)
- `file_type_id` — ID типа файла из `/api/file_types` (обязательно)
- `link` — произвольная URL ссылка (опционально, например на видео)

#### Пример запроса

```
POST https://api.gigma.ru/api/files
Content-Type: multipart/form-data

file: <binary>
file_type_id: 1
link: https://google.ru
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "file": {
        "id": 2201,
        "name": "downloader.py",
        "type": {
            "id": 1,
            "name": "Трудовой договор",
            "avatar": "https://api.gigma.ru/storage/uploads/default.svg",
            "created_at": "2024-03-27T07:00:46.000000Z"
        },
        "path": "https://api.gigma.ru/storage/uploads/7NYkKhv2Tm9CGlpcDzzLcsrKtrce8K39M4uU9pDw",
        "link": "https://google.ru",
        "created_at": "2024-12-03T10:42:18.000000Z",
        "updated_at": "2024-12-03T10:42:18.000000Z"
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — имя загруженного файла
- `type` — объект типа файла
- `path` — публичный URL файла
- `link` — произвольная URL ссылка (если передана)
- `created_at`, `updated_at` — таймстампы


### Получение файла по ID

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/files/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Пример запроса

```
GET https://api.gigma.ru/api/files/1
```

#### Ответ

```json
{
    "file": {
        "id": 1,
        "name": "logo.svg",
        "type": {
            "id": 1,
            "name": "Трудовой договор",
            "avatar": "https://api.gigma.ru/storage/uploads/default.svg",
            "created_at": "2024-03-27T07:00:46.000000Z"
        },
        "path": "https://api.gigma.ru/storage/uploads/yjohncMkjTSnvJ7FH4vksOtDYUy9pO2HDwmNU5Hc.svg",
        "created_at": "2024-04-14T20:04:32.000000Z",
        "updated_at": "2024-04-14T20:04:32.000000Z"
    }
}
```


### Удаление файла

**Метод:** DELETE  
**URL:** `https://api.gigma.ru/api/files/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Ответ

```json
{
    "message": "File successfully deleted"
}
```


## Типы файлов (справочник)

### Список типов файлов

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/file_types`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

Используется при загрузке файла, чтобы выбрать `file_type_id`.

#### Ответ

```json
{
    "fileTypes": [
        { "id": 1, "name": "Трудовой договор", "avatar": "https://api.gigma.ru/storage/uploads/default.svg", "created_at": "2024-03-27T07:00:46.000000Z" },
        { "id": 2, "name": "Аватар", "avatar": "https://api.gigma.ru/storage/uploads/default.svg", "created_at": "2024-03-27T07:00:46.000000Z" }
    ],
    "fileTypesCount": 2
}
```

##### Описание полей ответа

- `fileTypes[]` — массив типов: `id`, `name`, `avatar`, `created_at`
- `fileTypesCount` — общее количество


### Тип файла по ID

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/file_types/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Ответ

```json
{
    "fileType": {
        "id": 1,
        "name": "Трудовой договор",
        "avatar": "https://api.gigma.ru/storage/uploads/default.svg",
        "created_at": "2024-03-27T07:00:46.000000Z"
    }
}
```

---

## Справочники и права

Source: https://docs.gigma.ru/ERP/%D0%A1%D0%BF%D1%80%D0%B0%D0%B2%D0%BE%D1%87%D0%BD%D0%B8%D0%BA%D0%B8/

# Справочники

## Экраны

### Получение списка экранов, к которым применяется проверка права на доступ

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/screens`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/screens
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "screens": [
        {
            "id": 1,
            "name": "Контрагенты",
            "permissions": [
                {
                    "id": 9,
                    "screen": {
                        "id": 1,
                        "name": "Контрагенты",
                        "created_at": "2024-03-27T07:00:46.000000Z"
                    },
                    "name": "view-counterparties",
                    "description": "Просмотр контрагентов",
                    "created_at": "2024-03-27T07:00:46.000000Z"
                },
                {
                    "id": 10,
                    "screen": {
                        "id": 1,
                        "name": "Контрагенты",
                        "created_at": "2024-03-27T07:00:46.000000Z"
                    },
                    "name": "edit-counterparties",
                    "description": "Редактирование контрагентов",
                    "created_at": "2024-03-27T07:00:46.000000Z"
                }
            ]
        },
        {
            "id": 2,
            "name": "Заказы",
            "permissions": [
                {
                    "id": 13,
                    "screen": {
                        "id": 2,
                        "name": "Заказы",
                        "created_at": "2024-03-27T07:00:46.000000Z"
                    },
                    "name": "view-orders",
                    "description": "Просмотр заказов",
                    "created_at": "2024-03-27T07:00:46.000000Z"
                },
                {
                    "id": 14,
                    "screen": {
                        "id": 2,
                        "name": "Заказы",
                        "created_at": "2024-03-27T07:00:46.000000Z"
                    },
                    "name": "edit-orders",
                    "description": "Редактирование заказов",
                    "created_at": "2024-03-27T07:00:46.000000Z"
                }
            ]
        },
        {
            "id": 3,
            "name": "Задачи",
            "permissions": [
                {
                    "id": 15,
                    "screen": {
                        "id": 3,
                        "name": "Задачи",
                        "created_at": "2024-03-27T07:00:46.000000Z"
                    },
                    "name": "view-tasks",
                    "description": "Просмотр задач",
                    "created_at": "2024-03-27T07:00:46.000000Z"
                },
                {
                    "id": 16,
                    "screen": {
                        "id": 3,
                        "name": "Задачи",
                        "created_at": "2024-03-27T07:00:46.000000Z"
                    },
                    "name": "edit-tasks",
                    "description": "Редактирование задач",
                    "created_at": "2024-03-27T07:00:46.000000Z"
                }
            ]
        }
    ],
    "screensCount": 3
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — название экрана
- `permissions` — массив объектов, содержащих права доступа пользователя


### Получение выбранного экрана со списком прав доступа

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/screens/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/screens/1
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "screen": {
        "id": 1,
        "name": "Контрагенты",
        "permissions": [
            {
                "id": 9,
                "screen": {
                    "id": 1,
                    "name": "Контрагенты",
                    "created_at": "2024-03-27T07:00:46.000000Z"
                },
                "name": "view-counterparties",
                "description": "Просмотр контрагентов",
                "created_at": "2024-03-27T07:00:46.000000Z"
            },
            {
                "id": 10,
                "screen": {
                    "id": 1,
                    "name": "Контрагенты",
                    "created_at": "2024-03-27T07:00:46.000000Z"
                },
                "name": "edit-counterparties",
                "description": "Редактирование контрагентов",
                "created_at": "2024-03-27T07:00:46.000000Z"
            }
        ]
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — название экрана
- `permissions` — массив объектов, содержащих права доступа пользователя


## Типы контрагентов

### Получение списка с типами контрагентов

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty_types`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/counterparty_types
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "counterpartyTypes": [
        {
            "id": 1,
            "name": "Клиент",
            "created_at": "2024-03-27T07:00:46.000000Z"
        },
        {
            "id": 2,
            "name": "Поставщик",
            "created_at": "2024-03-27T07:00:46.000000Z"
        },
        {
            "id": 3,
            "name": "Агент",
            "created_at": "2024-03-27T07:00:46.000000Z"
        }
    ],
    "counterpartyTypesCount": 3
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — тип контрагента
- `created_at` — дата и время добавления в систему


### Получение выбранного типа контрагента

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/counterparty_types/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/counterparty_types/1
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "counterpartyType": {
        "id": 1,
        "name": "Клиент",
        "created_at": "2024-03-27T07:00:46.000000Z"
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — тип контрагента
- `created_at` — дата и время добавления в систему


## Отделы

### Получение списка отделов

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/departments`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/departments
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "departments": [
        {
            "id": 1,
            "name": "Технический",
            "created_at": "2023-11-13T13:20:36.000000Z"
        },
        {
            "id": 2,
            "name": "Коммерческий",
            "created_at": "2023-11-13T13:20:36.000000Z"
        },
        {
            "id": 3,
            "name": "Конструкторский",
            "created_at": "2023-11-13T13:20:36.000000Z"
        },
        {
            "id": 4,
            "name": "СМО",
            "created_at": "2023-11-13T13:20:36.000000Z"
        },
        {
            "id": 5,
            "name": "Логистика/склад",
            "created_at": "2023-11-13T13:20:36.000000Z"
        }
    ],
    "departmentsCount": 5
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — название отдела
- `created_at` — дата и время добавления в систему


### Получение выбранного отдела

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/departments/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/departments/1
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "department": {
        "id": 1,
        "name": "Технический",
        "created_at": "2023-11-13T13:20:36.000000Z"
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — название отдела
- `created_at` — дата и время добавления в систему


### Добавление отдела

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/departments`  
**Авторизация:** Bearer token (permission: edit-departments)  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `name` — название отдела

#### Пример запроса

```
https://api.gigma.ru/api/departments
```

```json
{
    "name": "IT"
}
```

#### Ответ

При успешном действии возвращается HTTP код `201`.

```json
{
    "department": {
        "id": 6,
        "name": "IT",
        "created_at": "2023-11-13T13:22:07.000000Z"
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — название отдела
- `created_at` — дата и время добавления в систему


### Редактирование отдела

**Метод:** PUT  
**URL:** `https://api.gigma.ru/api/departments/{id}`  
**Авторизация:** Bearer token (permission: edit-departments)  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `name` — название отдела

#### Пример запроса

```
https://api.gigma.ru/api/departments/1
```

```json
{
    "name": "IT"
}
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "department": {
        "id": 6,
        "name": "IT",
        "created_at": "2023-11-13T13:22:07.000000Z"
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — название отдела
- `created_at` — дата и время добавления в систему


### Удаление выбранного отдела

**Метод:** DELETE  
**URL:** `https://api.gigma.ru/api/departments/{id}`  
**Авторизация:** Bearer token (permission: edit-departments)  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/departments/1
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "message": "Department successfully destroyed"
}
```

##### Описание полей ответа

- `message` — информационное поле


## Роли пользователей

### Получение списка ролей пользователей

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/roles`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/roles
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "roles": [
        {
            "id": 1,
            "name": "owner",
            "description": "Собственник",
            "created_at": "2024-03-27T07:00:46.000000Z"
        },
        {
            "id": 2,
            "name": "admin",
            "description": "Администратор",
            "created_at": "2024-03-27T07:00:46.000000Z"
        },
        {
            "id": 3,
            "name": "manager",
            "description": "Руководитель отдела",
            "created_at": "2024-03-27T07:00:46.000000Z"
        },
        {
            "id": 4,
            "name": "employee",
            "description": "Сотрудник",
            "created_at": "2024-03-27T07:00:46.000000Z"
        }
    ],
    "rolesCount": 4
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — значение роли
- `description` — описание роли (на русском языке)
- `created_at` — дата и время добавления


### Получение выбранной роли пользователя

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/roles/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/roles/1
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "role": {
        "id": 1,
        "name": "owner",
        "description": "Собственник",
        "created_at": "2024-03-27T07:00:46.000000Z"
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — значение роли
- `description` — описание роли (на русском языке)
- `created_at` — дата и время добавления


### Добавление роли пользователя

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/roles`  
**Авторизация:** Bearer token (permission: edit-roles)  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `name` — код роли
- `description` — описание роли (на русском языке)

#### Пример запроса

```
https://api.gigma.ru/api/roles
```

```json
{
    "name": "accountant",
    "description": "Бухгалтер"
}
```

#### Ответ

При успешном действии возвращается HTTP код `201`.

```json
{
    "role": {
        "id": 4,
        "name": "accountant",
        "description": "Бухгалтер",
        "created_at": "2023-11-13T13:24:23.000000Z"
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — значение роли
- `description` — описание роли (на русском языке)
- `created_at` — дата и время добавления


### Редактирование роли пользователя

**Метод:** PUT  
**URL:** `https://api.gigma.ru/api/roles/{id}`  
**Авторизация:** Bearer token (permission: edit-roles)  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `name` — код роли
- `description` — описание роли (на русском языке)

#### Пример запроса

```
https://api.gigma.ru/api/roles/1
```

```json
{
    "name": "accountant",
    "description": "Бухгалтер"
}
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "role": {
        "id": 4,
        "name": "accountant",
        "description": "Бухгалтер",
        "created_at": "2023-11-13T13:24:23.000000Z"
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — значение роли
- `description` — описание роли (на русском языке)
- `created_at` — дата и время добавления


### Удаление выбранной роли пользователя

**Метод:** DELETE  
**URL:** `https://api.gigma.ru/api/roles/{id}`  
**Авторизация:** Bearer token (permission: edit-roles)  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/roles/1
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "message": "Role successfully deleted"
}
```

##### Описание полей ответа

- `message` — информационное поле


## Типы файлов

### Получение списка типов файлов

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/file_types`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/file_types
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "fileTypes": [
        {
            "id": 1,
            "name": "Трудовой договор",
            "created_at": "2023-11-23T11:50:48.000000Z"
        },
        {
            "id": 2,
            "name": "Аватар",
            "created_at": "2023-11-23T11:50:48.000000Z"
        },
        {
            "id": 3,
            "name": "Документ к заказу",
            "created_at": "2024-01-12T11:55:55.000000Z"
        }
    ],
    "fileTypesCount": 3
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — тип файла
- `created_at` — дата и время добавления


### Получение выбранного типа файла

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/file_types/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/file_types/1
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "fileType": {
        "id": 1,
        "name": "Трудовой договор",
        "created_at": "2023-11-17T06:22:25.000000Z"
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — тип файла
- `created_at` — дата и время добавления


## Права доступа

### Получение списка прав доступа

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/permissions`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/permissions
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "permissions": [
        {
            "id": 1,
            "screen": null,
            "name": "view-admins",
            "description": "Просмотр администраторов",
            "created_at": "2023-11-16T09:07:19.000000Z"
        },
        {
            "id": 2,
            "screen": null,
            "name": "edit-admins",
            "description": "Редактирование администраторов",
            "created_at": "2023-11-16T09:07:19.000000Z"
        },
        {
            "id": 3,
            "screen": null,
            "name": "view-users",
            "description": "Просмотр пользователей",
            "created_at": "2023-11-16T09:07:19.000000Z"
        },
        {
            "id": 4,
            "screen": null,
            "name": "edit-users",
            "description": "Редактирование пользователей",
            "created_at": "2023-11-16T09:07:19.000000Z"
        },
        {
            "id": 5,
            "screen": null,
            "name": "edit-roles",
            "description": "Редактирование ролей",
            "created_at": "2023-11-16T09:07:19.000000Z"
        },
        {
            "id": 6,
            "screen": null,
            "name": "edit-permissions",
            "description": "Редактирование прав доступа",
            "created_at": "2023-11-16T09:07:19.000000Z"
        },
        {
            "id": 7,
            "screen": null,
            "name": "edit-branches",
            "description": "Редактирование филиалов",
            "created_at": "2023-11-16T09:07:19.000000Z"
        },
        {
            "id": 8,
            "screen": null,
            "name": "edit-departments",
            "description": "Редактирование отделов",
            "created_at": "2023-11-16T09:07:19.000000Z"
        },
        {
            "id": 9,
            "screen": {
                "id": 1,
                "name": "контрагенты",
                "created_at": null
            },
            "name": "view-counterparties",
            "description": "Просмотр контрагентов",
            "created_at": "2023-11-16T09:07:19.000000Z"
        },
        {
            "id": 10,
            "screen": {
                "id": 1,
                "name": "контрагенты",
                "created_at": null
            },
            "name": "edit-counterparties",
            "description": "Редактирование контрагентов",
            "created_at": "2023-11-16T09:07:19.000000Z"
        },
        {
            "id": 11,
            "screen": null,
            "name": "view-communications",
            "description": "Просмотр коммуникаций",
            "created_at": "2023-11-16T09:07:19.000000Z"
        },
        {
            "id": 12,
            "screen": null,
            "name": "edit-communications",
            "description": "Редактирование коммуникаций",
            "created_at": "2023-11-16T09:07:19.000000Z"
        },
        {
            "id": 13,
            "screen": {
                "id": 2,
                "name": "Заказы",
                "created_at": null
            },
            "name": "view-orders",
            "description": "Просмотр заказов",
            "created_at": "2023-11-16T09:07:19.000000Z"
        },
        {
            "id": 14,
            "screen": {
                "id": 2,
                "name": "Заказы",
                "created_at": null
            },
            "name": "edit-orders",
            "description": "Редактирование заказов",
            "created_at": "2023-11-16T09:07:19.000000Z"
        },
        {
            "id": 15,
            "screen": {
                "id": 3,
                "name": "Задачи",
                "created_at": null
            },
            "name": "view-tasks",
            "description": "Просмотр задач",
            "created_at": "2023-11-16T09:07:19.000000Z"
        },
        {
            "id": 16,
            "screen": {
                "id": 3,
                "name": "Задачи",
                "created_at": null
            },
            "name": "edit-tasks",
            "description": "Редактирование задач",
            "created_at": "2023-11-16T09:07:19.000000Z"
        }
    ],
    "permissionsCount": 16
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — значение права доступа
- `description` — описание права доступа (на русском языке)
- `created_at` — дата и время добавления


### Получение выбранного права доступа

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/permissions/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/permissions/1
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "permission": {
        "id": 1,
        "name": "edit-roles",
        "description": "Редактирование ролей",
        "created_at": "2023-11-13T13:20:36.000000Z"
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — значение права доступа
- `description` — описание права доступа (на русском языке)
- `created_at` — дата и время добавления


### Добавление права доступа

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/permissions`  
**Авторизация:** Bearer token (permission: edit-permissions)  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `name` — значение права доступа
- `description` — описание роли (на русском языке)

#### Пример запроса

```
https://api.gigma.ru/api/permissions
```

```json
{
    "name": "edit-admins",
    "description": "Редактирование списка администраторов"
}
```

#### Ответ

При успешном действии возвращается HTTP код `201`.

```json
{
    "permission": {
        "id": 13,
        "name": "edit-admins",
        "description": "Редактирование списка администраторов",
        "created_at": "2023-11-13T13:31:38.000000Z"
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — значение права доступа
- `description` — описание роли (на русском языке)
- `created_at` — дата и время добавления


### Редактирование права доступа

**Метод:** PUT  
**URL:** `https://api.gigma.ru/api/permissions/{id}`  
**Авторизация:** Bearer token (permission: edit-permissions)  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `name` — значение права доступа
- `description` — описание роли (на русском языке)

#### Пример запроса

```
https://api.gigma.ru/api/permissions/1
```

```json
{
    "name": "edit-admins",
    "description": "Редактирование списка администраторов"
}
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "permission": {
        "id": 13,
        "name": "edit-admins",
        "description": "Редактирование списка администраторов",
        "created_at": "2023-11-13T13:31:38.000000Z"
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — значение права доступа
- `description` — описание роли (на русском языке)
- `created_at` — дата и время добавления


### Удаление выбранного права доступа

**Метод:** DELETE  
**URL:** `https://api.gigma.ru/api/permissions/{id}`  
**Авторизация:** Bearer token (permission: edit-permissions)  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/permissions/1
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "message": "Permission successfully deleted"
}
```

##### Описание полей ответа

- `message` — информационное поле


## Статусы звонков

### Получение списка статусов звонков

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/call_statuses`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/call_statuses
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "callStatuses": [
        {
            "id": 1,
            "name": "Создан",
            "created_at": "2023-12-27T22:53:33.000000Z"
        },
        {
            "id": 2,
            "name": "Обработан",
            "created_at": "2023-12-27T22:53:33.000000Z"
        },
        {
            "id": 3,
            "name": "Пропущен",
            "created_at": "2023-12-27T22:53:33.000000Z"
        }
    ],
    "callStatusesCount": 3
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — статус звонка
- `created_at` — дата и время добавления


### Получение выбранного статуса звонка

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/call_statuses/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/call_statuses/1
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "callStatus": {
        "id": 1,
        "name": "Создан",
        "created_at": "2023-12-27T22:53:33.000000Z"
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — статус звонка
- `created_at` — дата и время добавления


## Статусы заказов

### Получение списка статусов заказов

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/order_statuses`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/order_statuses
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "orderStatuses": [
        {
            "id": 1,
            "name": "Новый",
            "created_at": "2024-01-08T05:21:59.000000Z"
        },
        {
            "id": 2,
            "name": "Ожидание оплаты",
            "created_at": "2024-01-08T05:21:59.000000Z"
        },
        {
            "id": 3,
            "name": "В сборке",
            "created_at": "2024-01-08T05:21:59.000000Z"
        },
        {
            "id": 4,
            "name": "Можно забирать",
            "created_at": "2024-01-08T05:21:59.000000Z"
        },
        {
            "id": 5,
            "name": "Выдан",
            "created_at": "2024-01-08T05:21:59.000000Z"
        },
        {
            "id": 6,
            "name": "Отменён",
            "created_at": "2024-01-08T05:21:59.000000Z"
        },
        {
            "id": 22,
            "name": "Оплачен",
            "created_at": "2024-01-08T05:21:59.000000Z"
        },
        {
            "id": 23,
            "name": "Доставка",
            "created_at": "2024-01-08T05:21:59.000000Z"
        }
    ],
    "orderStatusesCount": 8
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — статус заказа
- `created_at` — дата и время добавления


### Получение выбранного статуса заказа

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/order_statuses/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/order_statuses/1
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "orderStatus": {
        "id": 1,
        "name": "Новый",
        "created_at": "2024-01-08T05:21:59.000000Z"
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — статус заказа
- `created_at` — дата и время добавления


## Статусы задач

### Получение списка статусов задач

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/task_statuses`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/task_statuses
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "taskStatuses": [
        {
            "id": 1,
            "name": "В работе",
            "created_at": "2024-01-22T21:52:32.000000Z"
        },
        {
            "id": 2,
            "name": "Просрочена",
            "created_at": "2024-01-22T21:52:32.000000Z"
        },
        {
            "id": 3,
            "name": "Выполнена",
            "created_at": "2024-01-22T21:52:32.000000Z"
        }
    ],
    "taskStatusesCount": 3
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — статус задачи
- `created_at` — дата и время добавления


### Получение выбранного статуса задачи

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/task_statuses/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/task_statuses/1
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "taskStatus": {
        "id": 1,
        "name": "В работе",
        "created_at": "2024-01-22T21:52:32.000000Z"
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — статус задачи
- `created_at` — дата и время добавления


## Города

### Получение списка городов

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/cities`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `query` — поисковая строка

#### Пример запроса

```
https://api.gigma.ru/api/cities?query=Москва
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "cities": [
        {
            "id": 1,
            "name": "Москва",
            "avatar": "http://localhost:8000/storage/uploads/default.svg",
            "created_at": "2024-04-19T09:18:41.000000Z"
        },
        {
            "id": 2,
            "name": "Новосибирск",
            "avatar": "http://localhost:8000/storage/uploads/default.svg",
            "created_at": "2024-04-19T09:18:41.000000Z"
        },
        {
            "id": 3,
            "name": "Ростов-на-Дону",
            "avatar": "http://localhost:8000/storage/uploads/default.svg",
            "created_at": "2024-04-19T09:18:41.000000Z"
        }
    ],
    "citiesCount": 3
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — город
- `created_at` — дата и время добавления


### Получение выбранного города

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/cities/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/cities/1
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "city": {
        "id": 1,
        "name": "Москва",
        "avatar": "http://localhost:8000/storage/uploads/default.svg",
        "created_at": "2024-04-19T09:18:41.000000Z"
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — город
- `created_at` — дата и время добавления


## Страны

### Получение списка стран

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/countries`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/countries
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "countries": [
        {
            "id": 1,
            "name": "Россия",
            "avatar": "http://localhost:8000/storage/uploads/default.svg",
            "created_at": "2024-04-10T06:59:28.000000Z"
        }
    ],
    "countriesCount": 1
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — страна
- `avatar` — URL-адрес фотографии
- `created_at` — дата и время добавления


## Единицы измерения

### Получение списка единиц измерения

**Метод:** GET  
**URL:** `https://api.gigma.ru/storage_units`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/storage_units
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "units": [
        {
            "id": 1,
            "name": "Литр",
            "abbreviation": "л"
        },
        {
            "id": 2,
            "name": "Кубический метр",
            "abbreviation": "м³"
        },
        {
            "id": 3,
            "name": "Галлон",
            "abbreviation": "гал"
        },
        {
            "id": 4,
            "name": "Пинта",
            "abbreviation": "пт"
        },
        {
            "id": 5,
            "name": "Кварта",
            "abbreviation": "кв"
        },
        {
            "id": 6,
            "name": "Баррель",
            "abbreviation": "б"
        },
        {
            "id": 7,
            "name": "Кубический дюйм",
            "abbreviation": "in³"
        },
        {
            "id": 8,
            "name": "Кубический фут",
            "abbreviation": "ft³"
        },
        {
            "id": 9,
            "name": "Миллилитр",
            "abbreviation": "мл"
        },
        {
            "id": 10,
            "name": "Цистерна",
            "abbreviation": "цист"
        }
    ],
    "unitsCount": 10
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — полное название
- `abbreviation` — аббревиатура


### Получение выбранной единицы измерения

**Метод:** GET  
**URL:** `https://api.gigma.ru/storage_units/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/storage_units/1
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "unit": {
        "id": 1,
        "name": "Литр",
        "abbreviation": "л"
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — полное название
- `abbreviation` — аббревиатура


## Торговые марки (бренды)

### Получение списка брендов

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/brands`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `query` — поисковая строка

#### Пример запроса

```
https://api.gigma.ru/api/brands
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "brands": [
        {
            "id": 45,
            "name": "COCODOR",
            "avatar": "http://localhost:8000/storage/uploads/8M3PQIpdd3n4cQqM7cXUBILlMMTpZPyv8DdRYmAV.webp",
            "branch": {
                "id": 37,
                "title": "Торговля косметикой"
            },
            "created_at": "2024-12-11T12:28:57.000000Z"
        }
    ],
    "brandsCount": 1
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — производитель
- `avatar` — URL фотографии производителя
- `branch` — объект с информацией о направлении бизнеса
- `created_at` — дата и время добавления


### Получение выбранного бренда

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/brands/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Передаваемые параметры отсутствуют.

#### Пример запроса

```
https://api.gigma.ru/api/brands/45
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "brand": {
        "id": 45,
        "name": "COCODOR",
        "avatar": "http://localhost:8000/storage/uploads/8M3PQIpdd3n4cQqM7cXUBILlMMTpZPyv8DdRYmAV.webp",
        "branch": {
            "id": 37,
            "title": "Торговля косметикой"
        },
        "created_at": "2024-12-11T12:28:57.000000Z"
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — производитель
- `avatar` — URL фотографии производителя
- `branch` — объект с информацией о направлении бизнеса
- `created_at` — дата и время добавления


### Добавление бренда

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/brands`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `name` [обязательно] — название торговой марки
- `avatar_id` — ID фотографии торговой марки
- `branch_id` — ID бизнеса

#### Пример запроса

```
https://api.gigma.ru/api/brands
```

```json
{
    "name": "TEST",
    "avatar_id": 1,
    "branch_id": 15
}
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "brand": {
        "id": 44,
        "name": "TEST",
        "avatar": "http://localhost:8000/storage/uploads/default.svg",
        "branch": {
            "id": 15,
            "title": "Торговля косметикой"
        },
        "created_at": "2024-12-10T15:45:05.000000Z"
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — производитель
- `avatar` — URL фотографии производителя
- `branch` — объект с информацией о направлении бизнеса
- `created_at` — дата и время добавления


### Обновление бренда

**Метод:** PUT  
**URL:** `https://api.gigma.ru/api/brands/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `name` [обязательно] — название торговой марки
- `avatar_id` — ID фотографии торговой марки
- `branch_id` — ID бизнеса

#### Пример запроса

```
https://api.gigma.ru/api/brands/44
```

```json
{
    "name": "TEST",
    "avatar_id": 1,
    "branch_id": 14
}
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "brand": {
        "id": 44,
        "name": "TEST",
        "avatar": "http://localhost:8000/storage/uploads/default.svg",
        "branch": {
            "id": 14,
            "title": "Торговля одеждой"
        },
        "created_at": "2024-12-10T15:45:05.000000Z"
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — производитель
- `avatar` — URL фотографии производителя
- `branch` — объект с информацией о направлении бизнеса
- `created_at` — дата и время добавления


## Способы доставки

Клиентский список способов доставки описан в каноническом разделе [E-Commerce / Справочники](/E-Commerce/Справочники/#delivery-types).

## Магазины

Клиентский список магазинов и пунктов выдачи описан в каноническом разделе [E-Commerce / Справочники](/E-Commerce/Справочники/#shops).

## Объекты

### Получение списка объектов

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/objects`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `query` — поисковая строка

#### Пример запроса

```
https://api.gigma.ru/api/objects
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "objects": [
        {
            "id": 1,
            "name": "Wildberries",
            "avatar": "http://localhost:8000/storage/uploads/ypPdC9qVA2MZLbQ0l9nfS5LRlcMAVPiTBZhV31UY.svg",
            "created_at": "2024-07-27T18:15:28.000000Z"
        }
    ],
    "objectsCount": 1
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — название объекта
- `avatar` — URL на фотографию
- `created_at` — дата/время добавления в систему


## Каналы продаж

### Получение списка каналов продаж

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/sales_channels`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

- `query` — поисковая строка

#### Пример запроса

```
https://api.gigma.ru/api/sales_channels
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "salesChannels": [
        {
            "id": 1,
            "name": "Авито",
            "avatar": "https://api.gigma.ru/storage/uploads/default.svg",
            "created_at": "2024-03-27T07:00:46.000000Z"
        },
        {
            "id": 2,
            "name": "Яндекс директ",
            "avatar": "https://api.gigma.ru/storage/uploads/default.svg",
            "created_at": "2024-03-27T07:00:46.000000Z"
        },
        {
            "id": 3,
            "name": "Вк реклама",
            "avatar": "https://api.gigma.ru/storage/uploads/default.svg",
            "created_at": "2024-03-27T07:00:46.000000Z"
        },
        {
            "id": 4,
            "name": "Другое",
            "avatar": "https://api.gigma.ru/storage/uploads/default.svg",
            "created_at": "2024-03-27T07:00:46.000000Z"
        }
    ],
    "salesChannelsCount": 4
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — название канала продаж
- `avatar` — URL фотографии
- `created_at` — дата и время добавления


## НДС

### Получение списка НДС

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/vats`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/vats
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "vats": [
        {
            "id": 1,
            "name": "Без НДС",
            "value": "0.00"
        },
        {
            "id": 2,
            "name": "НДС 10%",
            "value": "10.00"
        },
        {
            "id": 5,
            "name": "НДС 22%",
            "value": "22.00"
        },
        {
            "id": 6,
            "name": "НДС 20%",
            "value": "20.00"
        }
    ],
    "vatsCount": 4
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — название значения НДС
- `value` — значение НДС в процентах


### Получение выбранного значения НДС

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/vats/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/vats/1
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "vat": {
        "id": 1,
        "name": "Без НДС",
        "value": "0.00"
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — название значения НДС
- `value` — значение НДС в процентах


## Типы страниц

### Получение списка типов страниц

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/page_types`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/page_types
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "pageTypes": [
        {
            "id": 1,
            "name": "Главная"
        },
        {
            "id": 2,
            "name": "Категория"
        },
        {
            "id": 3,
            "name": "Товар"
        }
    ],
    "pageTypesCount": 3
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — тип страницы


### Получение выбранного типа страницы

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/page_types/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/page_types/1
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "pageType": {
        "id": 1,
        "name": "Главная"
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — тип страницы


## Типы интеграций

### Получение списка типов интеграций

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/integration_types`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200` с массивом `integrationTypes` и `integrationTypesCount`.


### Получение выбранного типа интеграции

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/integration_types/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200`.


## Интеграции

### Получение списка интеграций

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/integrations`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200` с массивом `integrations` и `integrationsCount`.


### Получение выбранной интеграции

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/integrations/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200`.


## Настройки

### Получение настроек

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/settings`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200` с массивом `settings`.


### Получение выбранной настройки

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/settings/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200`.


## Типы доставки

### Получение списка типов доставки

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/delivery_types`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Ответ

При успешном действии возвращается HTTP код `200` с массивом `deliveryTypes` и `deliveryTypesCount`.


## Типы блоков

### Получение списка типов блоков

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/block_types`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/block_types
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "blockTypes": [
        {
            "id": 1,
            "name": "Слайдер"
        },
        {
            "id": 2,
            "name": "Текст"
        },
        {
            "id": 3,
            "name": "Сетка товаров"
        }
    ],
    "blockTypesCount": 3
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — тип блока


### Получение выбранного типа блока

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/block_types/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Authorization: Bearer {token}`  

#### Параметры запроса

Параметры не передаются.

#### Пример запроса

```
https://api.gigma.ru/api/block_types/1
```

#### Ответ

При успешном действии возвращается HTTP код `200`.

```json
{
    "blockType": {
        "id": 1,
        "name": "Слайдер"
    }
}
```

##### Описание полей ответа

- `id` — первичный ключ
- `name` — тип блока

---

## Калькулятор и подсказки

Source: https://docs.gigma.ru/ERP/%D0%92%D1%81%D0%BF%D0%BE%D0%BC%D0%BE%D0%B3%D0%B0%D1%82%D0%B5%D0%BB%D1%8C%D0%BD%D1%8B%D0%B5%20%D0%B7%D0%B0%D0%BF%D1%80%D0%BE%D1%81%D1%8B/

# Вспомогательные запросы

Утилитарные endpoint'ы, не привязанные к конкретному ресурсу: расчёт стоимости и набор autocomplete-поисков по справочникам (адрес, банк, город, компания).

## Калькулятор

### Расчёт стоимости товара

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/orders/calculator`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

Считает итоговую цену с учётом наценки и скидки. Не сохраняет ничего в базе.

#### Параметры запроса (тело)

- `price` — себестоимость товара (обязательно)
- `markup` — наценка в процентах (обязательно, `0` если без наценки)
- `discount` — скидка в процентах (обязательно, `0` если без скидки)

#### Пример запроса

```json
{
    "price": 1000,
    "markup": 40,
    "discount": 1
}
```

#### Ответ

```json
{
    "price": 1414
}
```

##### Описание полей ответа

- `price` — итоговая стоимость с учётом наценки и скидки


## Поиск адреса

### Поиск адреса

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/search_address`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

Подсказки адресов для autocomplete (как DaData). Возвращает список вариантов, сопоставимых с введённой строкой.

#### Параметры запроса (тело)

- `query` — поисковая строка

#### Пример запроса

```json
{
    "query": "Новогодняя 20"
}
```

#### Ответ

```json
{
    "addresses": [
        { "name": "г. Новосибирск, ул. Новогодняя, д. 20", "value": "630073, г. Новосибирск, Новогодняя ул., д. 20" },
        { "name": "г. Новосибирск, ул. Новогодняя, д. 20/1", "value": "630073, г. Новосибирск, Новогодняя ул., д. 20/1" }
    ],
    "addressesCount": 2
}
```

##### Описание полей ответа

- `addresses[]` — варианты: `name` (короткое представление), `value` (полный адрес)
- `addressesCount` — количество результатов


## Поиск банка

### Поиск банка

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/search_bank`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

Подсказки банковских реквизитов по БИК или названию. Возвращает шаблонные `IBankRequisite` для авто-заполнения формы.

#### Параметры запроса (тело)

- `query` — поисковая строка (БИК или название банка)

#### Пример запроса

```json
{
    "query": "Сбер"
}
```

#### Ответ

```json
{
    "banks": [
        {
            "name": "ПАО Сбербанк",
            "bik": "044525225",
            "kpp": "773601001",
            "payment_account": "",
            "address": "117997, г. Москва, ул. Вавилова, д. 19"
        }
    ],
    "banksCount": 1
}
```

##### Описание полей ответа

- `banks[]` — варианты по форме `IBankRequisite`: `name`, `bik`, `kpp`, `address`, и т.п.
- `banksCount` — количество результатов


## Поиск компании

### Поиск компании

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/search_company`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

Подсказки юрлиц по названию, ИНН или ОГРН. Используется в формах создания компании-контрагента и компании-бизнеса.

#### Параметры запроса (тело)

- `field` — по какому полю искать: `"name"` | `"inn"` | `"ogrn"`
- `query` — поисковая строка

#### Пример запроса

```json
{
    "field": "inn",
    "query": "5403057658"
}
```

#### Ответ

```json
{
    "companies": [
        {
            "name": "ООО \"АЙТЕКО\"",
            "inn": "5403057658",
            "orgn": "1185476049158",
            "legal_address": "630073, г. Новосибирск, Новогодняя ул., д. 20/1, кв. 26",
            "kpp": "540301001",
            "head": "Снегирёв Алексей Игоревич",
            "registration_date": "2020-04-02"
        }
    ],
    "companiesCount": 1
}
```

##### Описание полей ответа

- `companies[]` — варианты компаний: `name`, `inn`, `orgn` (опц.), `legal_address`, `kpp`, `head`, `registration_date` (опц.)
- `companiesCount` — количество результатов


## Города

### Список городов

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/cities`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Ответ

```json
{
    "cities": [
        { "id": 1, "name": "Новосибирск", "avatar": "https://api.gigma.ru/storage/uploads/default.svg", "created_at": "2024-03-27T07:00:46.000000Z" },
        { "id": 2, "name": "Москва", "avatar": "https://api.gigma.ru/storage/uploads/default.svg", "created_at": "2024-03-27T07:00:46.000000Z" }
    ],
    "citiesCount": 2
}
```

##### Описание полей ответа

- `cities[]` — массив: `id`, `name`, `avatar`, `created_at`
- `citiesCount` — общее количество


### Город по ID

**Метод:** GET  
**URL:** `https://api.gigma.ru/api/cities/{id}`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

#### Ответ

```json
{
    "city": {
        "id": 1,
        "name": "Новосибирск",
        "avatar": "https://api.gigma.ru/storage/uploads/default.svg",
        "created_at": "2024-03-27T07:00:46.000000Z"
    }
}
```


## Поиск номенклатуры

### Поиск номенклатуры

**Метод:** POST  
**URL:** `https://api.gigma.ru/api/search_nomenclature`  
**Авторизация:** Bearer token  
**Headers:** `Accept: application/json; Content-Type: application/json`  

Полнотекстовый поиск по номенклатуре через DaData. Возвращает список совпадений по названию.

#### Параметры запроса (тело)

- `query` — поисковая строка

#### Пример запроса

```json
{
    "query": "крем"
}
```

#### Ответ

При успешном действии возвращается HTTP код `200` с массивом совпадений.