Соглашения

Базовые правила, общие для всех endpoint’ов. Если в конкретном методе что-то не описано — значит работает по этому документу.

💡 Для значений ID, передаваемых в *_id-поля (order_status_id, delivery_type_id, role_id, file_type_id, …), см. отдельный справочник Энумы.

Базовый URL

https://api.gigma.ru/api

Все пути в документации указаны полностью (например https://api.gigma.ru/api/login), но в реальном клиенте обычно используется база https://api.gigma.ru/api + относительный путь endpoint’а.

Заголовки запроса

Минимальный набор для любого запроса с телом:

Accept: application/json
Content-Type: application/json

Для авторизованных запросов добавляется:

Authorization: Bearer <access_token.value>

Для загрузки файлов (POST /api/files, POST /api/orders/{id}/files, …) Content-Type меняется на multipart/form-data.

Авторизация

1. Получить токен: POST /api/login (ERP) или POST /api/counterparty/login (E-Commerce).

2. Сохранить access_token.value (например в localStorage).

3. Слать в каждом последующем запросе:

   Authorization: Bearer <access_token.value>

4. Окончание действия токена — access_token.expires_at (ISO 8601). По истечению или после 401 Unauthenticated нужно повторить шаг 1.

Подробности — ERP/Авторизация и E-Commerce/Авторизация.

Формат Bearer-токена

Бэкенд — Laravel Sanctum. Каждый токен имеет вид:

<id>|<secret>

Например: 28|dCWBGIqC9algoNXr6NVVg9D2fKWBaq7BJkRFyxq009cd040b

• <id> — целое число переменной длины (1, 28, 1024, …). Это первичный ключ записи токена в БД.
• | — обязательный разделитель. Без него токен невалиден.
• <secret> — секретная часть, alphanumeric.

⚠ При хранении токена в файлах/таблицах/env-переменных следите за тем, чтобы | не потерялся. CSV, INI-парсеры и некоторые шеллы могут его съесть. Корректное хранение: целиком в quoted-строке или в переменной.

Справочники: концепт → endpoint

Имена справочных endpoint’ов не всегда предсказуемы (например, единицы измерения это /api/storage_units, а не /api/units). Полная карта:

Карта живая — список справочников может расти. Если нужного концепта нет в таблице, не угадывайте plural/singular — спросите бэк.

Форматы данных

Пагинация

Используется стандартный Laravel-пагинатор. Endpoint’ы вида GET /api/tables/... и GET /api/.../history возвращают пагинацию.

Query-параметры

• page (int, опционально) — номер страницы (с 1)
• per_page (int, опционально) — размер страницы (по умолчанию 15)

Структура ответа

{
    "items": [ /* массив записей */ ],
    "pagination": {
        "total": 42,
        "per_page": 15,
        "current_page": 1,
        "last_page": 3,
        "from": 1,
        "to": 15
    }
}

Для history-endpoint’ов пагинатор может приходить в развёрнутом виде с links[], first_page_url, next_page_url и т.п. — см. ERP/Контрагенты → история.

Фильтры

Передаются как query-параметры. Соглашения:

Кириллица в query должна быть URL-encoded.

Коды ответа

⚠ Не делайте жёсткой проверки status === 200 на write-запросах — POST /api/<resource> обычно возвращает 201, а DELETE — 204. Используйте диапазон 2xx.

Пример 422

{
    "errors": {
        "password": ["The password field is required."],
        "phone_1": ["The phone 1 must be at least 11 characters."],
        "products.0.id": ["The selected products.0.id is invalid."]
    },
    "message": "The given data was invalid."
}

Ключи могут быть вложенными через точку (products.0.id) — для массивов в теле. Per-method примеры реальных ключей — в соответствующих endpoint’ах.

Обработка на стороне клиента

В event_ai (admin-фронт) принят такой паттерн (src/Redux/api/index.ts):

• На 401 Unauthenticated — очистить localStorage, редирект на /authentication/sign-in.
• На 403 — редирект на /profile через 3 секунды.
• На 422 — показать пользователю по полям из errors.
• На остальные 4xx/5xx с { message } — показать toast.

Rate limits

Бэкенд использует стандартный Laravel-throttle (throttle:api middleware). Дефолт фреймворка — 60 запросов в минуту на пользователя/IP. Точное значение в проде не подтверждено; для надёжности закладывайте backoff:

• При 429 ждать минимум 60 секунд (или значение из Retry-After если придёт).
• Для массовых импортов — не более 1 запроса в секунду на токен.

Идемпотентность

Стандартной поддержки Idempotency-Key нет. POST-запросы создания объектов не идемпотентны: повторный вызов создаст дубль.

Безопасно повторять:

• GET — всегда
• DELETE — да (вторая попытка вернёт 404, но состояние корректно)
• PUT — да, заменяет объект целиком

Требует осторожности:

• POST на коллекцию — НЕ повторять без проверки, что прошлый запрос провалился до создания объекта

Webhooks

Не поддерживаются. Бэкенд не отправляет push-уведомления о смене состояния заказов / контрагентов / номенклатуры.

Для отслеживания изменений — polling через GET-endpoint раз в N секунд. Адекватный интервал — 30–60 секунд (учитывая rate limit).

Версионирование URL

URL не версионируется. Префикса вида /api/v1/… или /api/v2/… нет — все endpoint’ы живут под единым корнем https://api.gigma.ru/api.

Изменения API накатываются прямо на этот корень; следить за breaking changes можно через release notes на docs.gigma.ru (когда появятся) или эмпирически — мониторингом 4xx/5xx на ключевых endpoint’ах.