Быстрый старт / Справочник

Справочник методов

Все пути версии v1. Тело запроса и ответа - JSON в UTF-8, время - UTC в формате ISO 8601, деньги - целое число копеек.

Общие правила

Неизвестное поле в запросе игнорируется, а не отвергается: так старый клиент переживает появление нового поля.
Пустая строка и null - разные вещи. Пустая строка стирает значение, null означает «не трогать».
Все списки отдаются курсором, максимум 200 записей за раз.
У каждого ответа есть заголовок X-Request-Id. Его стоит писать в свои журналы: по нему мы находим запрос за 30 дней.

Товары

Метод	Что делает
`GET /v1/products`	Список с фильтрами `updated_since`, `active`, `category`
`GET /v1/products/{sku}`	Одна позиция целиком, включая резервы
`POST /v1/products`	Создать или обновить позицию
`DELETE /v1/products/{sku}`	Убрать позицию из каталога (история заказов сохраняется)

Остатки и цены

Метод	Что делает
`POST /v1/stock/batch`	Пакет до 1000 позиций, применяется целиком
`GET /v1/stock/{sku}`	Остаток, резерв и доступное к заказу
`GET /v1/stock/history`	Изменения остатка за период, до 90 дней назад

Заказы

Метод	Что делает
`GET /v1/orders`	Список с фильтрами по статусу и периоду
`GET /v1/orders/{id}`	Заказ с позициями, оплатой и доставкой
`POST /v1/orders/{id}/status`	Перевод статуса, см. таблицу переходов
`POST /v1/orders/{id}/cancel`	Отмена целиком или части позиций

Вебхуки

Метод	Что делает
`GET /v1/hooks`	Подписки контура и их состояние
`POST /v1/hooks`	Создать подписку: адрес и список событий
`GET /v1/hooks/deliveries`	Журнал доставок за 30 дней
`POST /v1/hooks/deliveries/{id}/retry`	Повторить доставку вручную

Пагинация

bash

GET /v1/orders?limit=100
# в ответе: "cursor": "b3M6MTIwNA", "has_more": true
GET /v1/orders?limit=100&cursor=b3M6MTIwNA

Курсор живёт 15 минут и привязан к фильтрам запроса: менять их на ходу нельзя, перебор придётся начать заново.

Лимиты

Контур	Запросов в минуту	Пакет
Рабочий	120	1000 позиций
Песочница	60	200 позиций

При превышении приходит 429 и заголовок Retry-After в секундах. Считать ответы самому не нужно: достаточно уважать этот заголовок и не повторять запрос раньше.

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

Любой изменяющий запрос принимает Idempotency-Key, а переводы статуса его требуют. Ключ живёт 24 часа: повтор с тем же ключом возвращает первый ответ, включая его код. Ключ должен быть уникальным для операции, а не для минуты - хорошая привычка составлять его из действия и идентификатора.