REST API MiniShop3: корзина и заказ из Postman

Это статья из цикла материалов про MiniShop3 на modx.pro. В цикле уже есть скидка от суммы корзины на msOnGetCartCost и чеклист готовности сайта к MiniShop3.

Нужно прогнать корзину и оформление заказа MiniShop3 без вёрстки: headless-клиент, мобильное приложение или просто проверка API. Из Postman это несколько запросов к Web API.

В miniShop2 всё шло через единый action.php. В MiniShop3 точка входа отдельная: api.php, маршруты вида /api/v1/..., клиентский токен.

Документация: REST API.

Это Web API сайта (api.php + токен). Manager API админки (connector.php + сессия MODX) сюда не относится.

Что нужно до запросов

MODX 3 и установленный MiniShop3
Опубликованный товар — ID ресурса в дереве ресурсов менеджера
Активные доставка и оплата — ID в разделе MiniShop3 (Доставки и Оплаты)
Postman (или аналог) с коллекцией под ваш домен

Логин покупателя для гостевого checkout не обязателен. Достаточно токена сессии магазина.

В коллекции Postman удобно завести переменные baseUrl (домен сайта) и ms3_token. После token/get в скрипте Tests можно сохранить токен: pm.collectionVariables.set(«ms3_token», pm.response.json().data.token). В заголовках коллекции укажите MS3TOKEN = {{ms3_token}}.

Базовый URL

Все запросы идут на один скрипт. Маршрут передаёте параметром route. HTTP-метод задаёте в Postman (GET или POST).

{{baseUrl}}/assets/components/minishop3/api.php?route=/api/v1/...

Для тел с JSON добавьте заголовок Content-Type: application/json.

Без route получите 400 и сообщение Route parameter is required.

Токен

Сначала получите токен клиента.

GET {{baseUrl}}/assets/components/minishop3/api.php?route=/api/v1/customer/token/get

Ответ (сокращённо):

{
  "success": true,
  "message": "",
  "data": {
    "token": "a1b2c3...",
    "lifetime": 604800000
  }
}

Сервер также ставит cookie ms3_token. Браузер подхватит её сам. В Postman на httpOnly cookie лучше не опираться: скопируйте data.token в заголовок MS3TOKEN (или в переменную коллекции, как выше). Допустимо и Authorization: Bearer ….

Дальше заголовок нужен на каждом запросе к корзине и заказу. Без токена контроллеры отвечают 401.

Сценарий из Postman

Подставьте свой baseUrl и реальные ID. В примерах 123 — товар, 1 — доставка и оплата (заглушки).

Проверка живости (по желанию)
```
GET {{baseUrl}}/assets/components/minishop3/api.php?route=/api/v1/health
```
Токен не нужен. Ожидаете success: true.

Токен

GET {{baseUrl}}/assets/components/minishop3/api.php?route=/api/v1/customer/token/get

Сохраните data.token в MS3TOKEN / {{ms3_token}}.

Добавить товар
```
POST {{baseUrl}}/assets/components/minishop3/api.php?route=/api/v1/cart/add
```
Тело:
```
{
  "id": 123,
  "count": 1
}
```
Опции товара (если есть) передаёте объектом options.
В ответе смотрите data.last_key — это product_key позиции в корзине. Сохраните его для следующих шагов.
Прочитать корзину
```
GET {{baseUrl}}/assets/components/minishop3/api.php?route=/api/v1/cart/get
```
В data.status — total_count, total_cost, total_positions.
Изменить количество
```
POST {{baseUrl}}/assets/components/minishop3/api.php?route=/api/v1/cart/change
```
```
{
  "product_key": "сюда last_key из cart/add",
  "count": 2
}
```
Здесь нужен product_key, не ID ресурса. Удаление — POST …/cart/remove с тем же ключом.
Поля черновика заказа
Доставка и оплата — обычные поля заказа через order/add (отдельных URL под них нет).
```
POST {{baseUrl}}/assets/components/minishop3/api.php?route=/api/v1/order/add
```
```
{
  "key": "delivery_id",
  "value": 1
}
```
Так же задайте payment_id. Имена полей — delivery_id и payment_id (как во фронте и в БД).
Несколько полей сразу
POST {{baseUrl}}/assets/components/minishop3/api.php?route=/api/v1/order/set
```
{
  "fields": {
    "delivery_id": 1,
    "payment_id": 1,
    "email": "user@example.com",
    "phone": "+79001234567",
    "first_name": "Иван",
    "last_name": "Иванов",
    "city": "Москва",
    "street": "Тверская",
    "building": "1"
  }
}
```
Какие поля обязательны для выбранной доставки, смотрите так:
```
GET {{baseUrl}}/assets/components/minishop3/api.php?route=/api/v1/order/delivery/required-fields
```
В Query Params Postman добавьте delivery_id со значением ID доставки. Список из ответа подставьте в order/set или отдельными order/add.

Стоимость

GET {{baseUrl}}/assets/components/minishop3/api.php?route=/api/v1/order/cost

В data: cost, cart_cost, delivery_cost, payment_cost.

Оформить
```
POST {{baseUrl}}/assets/components/minishop3/api.php?route=/api/v1/order/submit
```
Тело можно пустым или {«data»: { }} .
При успехе в ответе обычно есть data.redirect (страница оплаты или «спасибо» с параметром msorder). Заказ появляется в админке MiniShop3.

Нажмите Send на каждом шаге. Если submit ругается на валидацию — допишите недостающие поля через order/add или order/set и повторите.

Корзина: эндпоинты

POST /api/v1/cart/add — добавить (id, count, опционально options)
POST /api/v1/cart/change — количество (product_key, count)
POST /api/v1/cart/remove — удалить (product_key)
GET /api/v1/cart/get — содержимое и status
POST /api/v1/cart/clean — очистить

Заказ: эндпоинты

GET /api/v1/order/get — черновик
POST /api/v1/order/add — одно поле (key, value)
POST /api/v1/order/set — пачка полей (fields)
POST /api/v1/order/remove — убрать поле
POST /api/v1/order/submit — оформить
POST /api/v1/order/clean — сбросить черновик
GET /api/v1/order/cost — итоговая стоимость
GET /api/v1/order/cost/cart, …/delivery, …/payment — части суммы
GET /api/v1/order/delivery/required-fields — обязательные поля доставки

Формат ответа

Успех:

{
  "success": true,
  "message": "ms3_cart_add_success",
  "data": { }
}

Ошибка:

{
  "success": false,
  "message": "Token is required",
  "code": 401
}

Поле message часто содержит ключ лексикона, не готовую фразу для покупателя.

Лимит запросов

Группа /api/v1 ограничена rate limit (по умолчанию 60 запросов в минуту, настройки ms3_rate_limit_max_attempts и ms3_rate_limit_decay_seconds). При превышении ответ 429. В скриптах коллекции не долбите API пачкой без паузы.

Три частые ошибки

Нет route. URL без ?route=/api/v1/... всегда даёт 400.
Нет MS3TOKEN. Cookie ms3_token httpOnly. В Postman она сама надёжно не появится. Берите токен из тела token/get и кладите в заголовок (или в {{ms3_token}}).
Путаете id и product_key. В корзину кладёте по ID ресурса. Меняете и удаляете по product_key из ответа. На submit без delivery_id, payment_id и полей из required-fields заказ не пройдёт.

Дальше по циклу и docs

Скидка от суммы корзины — плагин на msOnGetCartCost, сумма в API тоже меняется
Чеклист готовности сайта к MiniShop3 — окружение до установки
REST API
Frontend JavaScript — тот же контракт на сайте
GitHub MiniShop3 — баг или идея в Issues