# RetailCRM API v5: Сменить статус заказа и отметить оплату

Сценарий из mcp-everything. Актуально на 2026-10-24.

Оплата пришла в платёжной системе — заказ в CRM переходит в нужный статус, оплата отмечается.

1. Измени заказ: POST /api/v5/orders/{externalId}/edit с by = externalId и order — JSON-строкой только с изменяемыми полями, например status. Коды статусов видны в настройках RetailCRM.
2. Добавь оплату: POST /api/v5/orders/payments/create с payment — JSON-строкой: order (externalId или id заказа), type (код типа оплаты из справочника), amount, status и paidAt.
3. Если оплата уже создана и нужно поменять её статус, используй /api/v5/orders/payments/{id}/edit.
4. Ошибки валидации приходят с кодом 400 и списком errors — по нему видно, какое поле не прошло.

```bash
curl -X POST "https://<поддомен>.retailcrm.ru/api/v5/orders/1042/edit" \
  --data-urlencode "apiKey=$RCRM_KEY" \
  --data-urlencode 'by=externalId' \
  --data-urlencode 'site=my-shop' \
  --data-urlencode 'order={"status": "assembling"}'

curl -X POST "https://<поддомен>.retailcrm.ru/api/v5/orders/payments/create" \
  --data-urlencode "apiKey=$RCRM_KEY" \
  --data-urlencode 'site=my-shop' \
  --data-urlencode 'payment={"order": {"externalId": "1042"}, "type": "bank-card", "amount": 2280, "status": "paid", "paidAt": "2026-10-24 18:30:00"}'
```

## Базовые URL

- Боевой: `https://{your-subdomain}.retailcrm.ru/api/v5/`

## Авторизация

Тип: API-ключ

API-ключ создаётся в аккаунте RetailCRM и передаётся в параметре `apiKey` (GET или POST). Если ключ даёт доступ к нескольким магазинам, части методов нужен параметр `site` — символьный код магазина. Запросы — только по HTTPS, кодировка UTF-8.

## Методы сценария

### POST /api/v5/orders/{externalId}/edit — Изменить заказ

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `externalId` | path | string | да | Внешний или внутренний ID заказа |
| `by` | body | string | нет | externalId или id |
| `site` | body | string | нет | Код магазина |
| `order` | body | string (JSON) | да | Изменяемые поля заказа |

### POST /api/v5/orders/payments/create — Создать оплату заказа

Добавляет оплату к заказу. Изменение — `POST /api/v5/orders/payments/{id}/edit`, удаление — `POST /api/v5/orders/payments/{id}/delete`.

## Нюансы

- POST-запросы отправляются как `application/x-www-form-urlencoded`, а вложенные структуры (`order`, `customer`, `offers`) — JSON-строкой внутри поля формы.
- Для ключа с доступом к нескольким магазинам часть методов требует `site`.
- Ответы списков содержат метаданные пагинации: `limit`, `totalCount`, `currentPage`, `totalPageCount`.
- Для синхронизации изменений используйте `/orders/history` и `/customers/history`, а не полную перевыгрузку списков.
- Код `460` при пакетной загрузке означает, что часть заказов загружена с ошибками; загруженные перечислены в `uploadedOrders`.

## Другие сценарии

- [Передать заказ с сайта в RetailCRM](https://mcp-everything.ru/integrations/retailcrm/scenarios/peredat-zakaz-s-sayta-v-retailcrm.md)
- [Забирать изменения заказов без полной перевыгрузки](https://mcp-everything.ru/integrations/retailcrm/scenarios/zabirat-izmeneniya-zakazov-bez-polnoy.md)
- [Загрузить остатки товаров](https://mcp-everything.ru/integrations/retailcrm/scenarios/zagruzit-ostatki-tovarov.md)

---

Если этого недостаточно — официальная документация: https://rest-api-docs.retailcrm.ru/v5/
Вся интеграция одним документом: https://mcp-everything.ru/integrations/retailcrm.md