AMAGU MARKET · API v1 · Только чтение

Выгрузка товаров
и остатков

Подключите каталог AMAGU MARKET к своему магазину или учётной системе. Карточки товаров и остатки доступны раздельно в JSON по HTTPS. Карточки содержат цену продажи, фотографии, описания и характеристики товаров.

OpenAPI JSON для разработчиков · Скачать документацию

Быстрый старт

Базовый адрес: https://amagu-market.ru/api/v1. Используйте GET. Тело запроса не требуется.

curl 'https://amagu-market.ru/api/v1/products?limit=100'
curl 'https://amagu-market.ru/api/v1/stocks?limit=100'

Если администратор включил доступ по ключу, получите ключ у AMAGU MARKET и передавайте его в заголовке. Ключи предназначены для серверных интеграций: не размещайте их в адресах страниц или публичном JavaScript.

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

Также поддерживается Authorization: Bearer ВАШ_API_КЛЮЧ. В открытом режиме ключ необязателен. Переданный недействительный ключ всё равно возвращает 401.

Доступ и лимиты

Эндпоинт	Текущий доступ	Запросов/мин с IP	Максимум товаров
`/v1/products`	Требуется API-ключ	30	100
`/v1/stocks`	Требуется API-ключ	60	100

Общий текущий предел API: 600 запросов в минуту для всех клиентов вместе. Значения показаны на момент открытия страницы.

Администратор может независимо открыть, закрыть или ограничить ключом каждый эндпоинт. Лимиты IP, ключа и общий предел действуют совместно. Счётчики общие для всех процессов сервера. Окно минуты начинается с первого запроса, суточное окно ключа — с первого запроса на 24 часа.

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

1. Карточки товаров

GET /api/v1/products

Возвращает активные товары, включая товары с нулевым остатком. Каждый вариант имеет собственный id. Правила скрытия витрины по нулевому остатку, цене или фото не исключают активные товары из выгрузки. Цена продажи указана в поле price. Остатки получайте отдельным запросом к /stocks.

Параметры обоих эндпоинтов

Параметр	Формат и назначение
`limit`	1–200, но не выше максимума из настроек. По умолчанию 100. Если максимум снижен, передавайте limit явно.
`after_id`	Неотрицательный ID последнего товара предыдущей страницы. По умолчанию 0. Сортировка всегда по id по возрастанию.
`ids`	До 100 положительных ID через запятую без пробелов, например 12,34. Неизвестные и неактивные ID пропускаются.
`sku`	Точный артикул, до 80 символов. Закодируйте специальные символы URL. Фильтры можно сочетать, они работают одновременно.

Поля карточки

Поле	Описание
`id, sku, barcode`	ID товара, артикул и штрихкод. Сопоставляйте карточки и остатки по id.
`name, slug, url`	Название, адресный идентификатор и абсолютная ссылка на карточку.
`short_description, description`	Краткое и полное описание. Может содержать HTML; при встраивании используйте безопасную обработку HTML.
`price, compare_at_price, currency`	Публичная цена продажи, цена до скидки или null, валюта 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, dimensions, unit`	Вес (строка или null), габариты и единица измерения в формате карточки товара.
`video_url`	Абсолютная ссылка на видео или null.
`meta_title, meta_keywords, meta_description`	SEO-поля карточки или null.
`average_rating, review_count, created_at`	Средняя оценка (строка или null), число отзывов, время создания в ISO 8601.

Точная схема всех полей и допустимых null опубликована в OpenAPI. Пример структуры страницы (карточка сокращена):

{
  "items": [
    {
      "id": 12,
      "sku": "AM-001",
      "name": "Пример товара",
      "price": "1250.00",
      "currency": "RUB",
      "images": [],
      "attributes": []
    }
  ],
  "next_cursor": 12,
  "has_more": true,
  "generated_at": "2026-10-28T10:00:00Z"
}

2. Остатки товаров

GET /api/v1/stocks. Параметры и пагинация совпадают с карточками.

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

stock_quantity — текущее общее количество из каталога AMAGU MARKET; in_stock равно true, когда количество больше нуля. Данные не резервируют товар и не гарантируют наличие к моменту оформления заказа. Нулевые остатки передаются, чтобы ваша система могла выключать продажи.

Как выгрузить весь каталог

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

Это последовательное чтение текущего состояния, без фиксации общего снимка и без фильтра изменений. Для полной сверки начинайте с after_id=0. При успешной полной выгрузке считайте отсутствующие id снятыми с публикации. При ошибке или незавершённой выгрузке не удаляйте товары на своей стороне.

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

Ошибки и повторные запросы

Код	Действие клиента
401	Нужен ключ, ключ недействителен, истёк или отозван. Проверьте заголовок, обратитесь за новым ключом.
403	Эндпоинт закрыт или ключу не выдано разрешение. Обратитесь к AMAGU MARKET.
422	Проверьте параметры, размер страницы, ids и диапазоны значений.
429	Достигнут один из лимитов. Подождите не меньше Retry-After секунд и добавьте случайную небольшую задержку.
503	Временная недоступность или занятость. Соблюдайте Retry-After; при повторении увеличивайте задержку.

Ошибки возвращаются в JSON с полем detail. Не повторяйте запросы в бесконечном цикле без задержки. Не передавайте ключ в query-параметрах. Изменяющие товар методы API не поддерживаются.

Выгрузка товарови остатков