AMAGU MARKET · API v1

API товаров, остатков
и партнёрских заказов

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

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

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

Базовый адрес: https://amagu-market.ru/api/v1. Для выгрузки используйте GET без тела. Для приёма продаж и отмен используйте POST из раздела «Заказы партнёров».

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.

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

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

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

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

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

GET /api/v1/products

Возвращает активные товары с идентификатором МойСклад или поставщика Ресанта, включая товары с нулевым остатком. Каждый вариант имеет собственный id. Для товаров МойСклад это UUID соответствующего товара или модификации; для Ресанта — идентификатор поставщика с префиксом resanta:. Правила скрытия витрины по нулевому остатку, цене или фото не исключают активные товары из выгрузки. Цена продажи указана в поле price. Остатки получайте отдельным запросом к /stocks.

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

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

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

{
  "items": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "source": "moysklad",
      "moysklad_id": "11111111-1111-4111-8111-111111111111",
      "supplier_id": null,
      "sku": "AM-001",
      "name": "Пример товара",
      "price": "1250.00",
      "currency": "RUB",
      "images": [],
      "attributes": []
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "generated_at": "2026-10-28T10:00:00Z"
}

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

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

{
  "items": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "source": "moysklad",
      "moysklad_id": "11111111-1111-4111-8111-111111111111",
      "supplier_id": null,
      "sku": "AM-001",
      "stock_quantity": 25,
      "in_stock": true
    },
    {
      "id": "resanta:12345",
      "source": "resanta",
      "moysklad_id": null,
      "supplier_id": "12345",
      "sku": "AM-002",
      "stock_quantity": 0,
      "in_stock": false
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "generated_at": "2026-10-28T10:00:00Z"
}

stock_quantity — общий свободный остаток для новых заказов. Для товаров МойСклад он уже учитывает резервы покупателей, включая принятые через API продажи вашего клиента. Все API-ключи получают остаток из одного общего пула. in_stock равно true, когда количество больше нуля.

После успешного приёма продажи с status=reserved и stock_reservation=committed её количество уже вычтено на сайте. Повторно вычитать свои подтверждённые резервы из stock_quantity не нужно. Например, из 22 шт. зарезервированы 10 шт.; API отдаёт 12 шт. При вашем дополнительном страховом запасе 3 шт. остаётся 9 шт. для новых продаж.

Этот остаток общий и для всех ваших кабинетов Ozon/WB. При распределении между кабинетами учитывайте единый доступный пул. Кеш остатков — до 15 секунд; generated_at показывает время формирования ответа. Синхронизация внешних изменений МойСклад выполняется в фоне. Запрос остатков сам по себе не резервирует товар; наличие повторно проверяется при приёме заказа. Нулевые остатки передаются, чтобы ваша система могла выключать продажи.

curl 'https://amagu-market.ru/api/v1/orders' \
  -X POST \
  -H 'X-API-Key: ВАШ_API_КЛЮЧ' \
  -H 'Idempotency-Key: sale-ozon-100001-v1' \
  -H 'Content-Type: application/json' \
  --data '{"items":[{"marketplace":"ozon","external_order_id":"100001","external_line_id":"1","product_id":"11111111-1111-4111-8111-111111111111","quantity":1}]}'

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

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

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

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

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