# AMAGU MARKET — API выгрузки v1

Документация: https://amagu-market.ru/api-docs
OpenAPI: https://amagu-market.ru/api/v1/openapi.json
Базовый адрес: https://amagu-market.ru/api/v1

## Доступ

Только HTTPS, GET, JSON. Эндпоинты управляются независимо: открытый,
по API-ключу либо закрытый. Текущие режимы и ограничения указаны на странице
документации и в x-current-policy файла OpenAPI.
Ключ выдаёт администратор AMAGU MARKET. Передавайте X-API-Key: ВАШ_КЛЮЧ
или Authorization: Bearer ВАШ_КЛЮЧ. Не передавайте ключ в URL и публичном JS.
Переданный недействительный ключ отклоняется и в открытом режиме.

## 1. GET /products

Активные товары, включая товары с нулевым остатком. Один вариант — один товар.
Карточки содержат цену продажи, фотографии, описания и характеристики товаров.
Остатки получайте отдельным запросом к /stocks. Правила скрытия витрины по фото,
цене или остатку не исключают активные товары из API.

Поля:
- id (число), sku, barcode, name, slug, url;
- short_description, description (может содержать HTML);
- price, compare_at_price (цены строками, например "1250.00"), currency="RUB";
- image_url, images[{url, sort_order, is_primary}] — абсолютные ссылки;
- categories[{id,name,slug,parent_id}] — активные категории без дубликатов;
- tags[{id,name,slug}];
- attributes[{slug,name,value,data_type}] — только публичные характеристики;
- variant: {group_id,label,attribute_label} или null;
- weight (строка или null), dimensions, unit, video_url;
- meta_title, meta_keywords, meta_description;
- average_rating (строка или null), review_count, created_at (ISO 8601).

Необязательные значения могут быть null. Точная схема — в OpenAPI.
price — публичная цена продажи без индивидуальных скидок клиента.
При встраивании description безопасно обрабатывайте HTML на своей стороне.

## 2. GET /stocks

Активные товары, включая нулевые остатки.
Поля каждого элемента: id, sku, stock_quantity (целое >=0), in_stock (boolean).
stock_quantity — общее количество из каталога AMAGU MARKET. Это не резерв
и не гарантия наличия при будущем оформлении заказа.
Сопоставляйте с карточками по id.

## Общие параметры

- limit: 1–200, не выше текущего максимума; по умолчанию 100.
  Если администратор уменьшил максимум, передавайте limit явно.
- after_id: ID последнего товара прошлой страницы, по умолчанию 0.
- ids: до 100 положительных ID через запятую без пробелов, например 12,34.
- sku: точный артикул до 80 символов; кодируйте специальные символы URL.

Фильтры сочетаются через AND. Неактивные и неизвестные id пропускаются.

Примеры:

```sh
curl 'https://amagu-market.ru/api/v1/products?limit=100'
curl 'https://amagu-market.ru/api/v1/stocks?ids=12,34'
curl 'https://amagu-market.ru/api/v1/products?limit=100' \
  -H 'X-API-Key: ВАШ_API_КЛЮЧ'
```

Ответ страницы:

```json
{
  "items": [{"id":12,"sku":"AM-001","stock_quantity":0,"in_stock":false}],
  "next_cursor":null,
  "has_more":false,
  "generated_at":"2026-10-28T10:00:00Z"
}
```

Сортировка по id по возрастанию. Если has_more=true, подставьте next_cursor
в after_id следующего запроса и сохраните остальные параметры. Завершайте
цикл при has_more=false. Пустой результат — корректный ответ 200.
Общего фиксированного снимка и фильтра изменений нет.
Для полной сверки начинайте с after_id=0. Считайте отсутствующие товары
снятыми с публикации только после успешной полной выгрузки.
При ошибке или незавершённом обходе не удаляйте товары у себя.

## Кеш и ограничения

Карточки кешируются до 60 секунд, остатки до 15 секунд. generated_at — время
формирования страницы, в том числе при ответе из кеша. Доступ и ключ
проверяются на каждом запросе. Рекомендуем последовательные запросы:
карточки раз в час, остатки раз в 5 минут.

Применяются одновременно общий лимит API, лимит IP и ограничения ключа
за минуту и 24 часа. Общие счётчики работают для всех серверных процессов.
Окно начинается с первого запроса; 24 часа — не календарные сутки.
X-RateLimit-Limit и X-RateLimit-Remaining отражают минутный бюджет IP/ключа,
X-RateLimit-Reset — Unix-время сброса. Общий или суточный бюджет может
исчерпаться раньше. При превышении ориентируйтесь на Retry-After.

## Ошибки

JSON с полем detail:
- 401 — нужен ключ, ключ недействителен, истёк или отозван;
- 403 — эндпоинт закрыт либо нет разрешения ключа;
- 422 — неверные параметры или превышен размер страницы;
- 429 — превышен лимит, подождите Retry-After секунд;
- 503 — временная занятость/недоступность, подождите Retry-After секунд.

Добавляйте к ожиданию небольшую случайную задержку. При повторяющихся 503
увеличивайте интервал. Не запускайте бесконечные повторы без задержки.
Изменение товаров через этот API не поддерживается.