# СДЭК API v2: Получать статусы заказов вебхуком

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

Узнавать о движении посылки сразу, без постоянного опроса заказов.

1. Подпишись на смену статусов: POST /v2/webhooks с type = ORDER_STATUS и url своего обработчика. Для изменений заказа есть ORDER_MODIFIED, для готовых квитанций — PRINT_FORM.
2. Обработчик должен отвечать быстро: СДЭК ждёт подключения 15 секунд, при ошибках повторяет до 12 раз за 75 минут и потом перестаёт присылать событие.
3. По uuid из события найди заказ у себя и обнови статус. Если нужна полная информация, запроси GET /v2/orders/{uuid}.
4. Отвечай 200 сразу, а тяжёлую обработку делай в фоне, иначе повторы будут дублировать события.

```bash
curl -X POST https://api.cdek.ru/v2/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"type": "ORDER_STATUS", "url": "https://example.ru/cdek/webhook"}'
```

## Базовые URL

- Боевой: `https://api.cdek.ru`
- Тестовый: `https://api.edu.cdek.ru`

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

Тип: OAuth 2.0

OAuth 2.0 (client credentials). Токен получают запросом `POST /v2/oauth/token` с `grant_type=client_credentials`, `client_id` (Account) и `client_secret` (Secure password) из личного кабинета СДЭК (раздел интеграции) и передают в заголовке `Authorization: Bearer <token>` (JWT). Для интеграции нужен договор со СДЭК.

Тестовая учётная запись для `api.edu.cdek.ru` (из документации):

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

### GET /v2/orders/{uuid} — Информация о заказе по UUID

Детальная информация о заказе: статусы, доставка, получатель. По номеру СДЭК или номеру ИМ — `GET /v2/orders` с параметрами `cdek_number` или `im_number`.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `uuid` | path | string | да | Идентификатор заказа в ИС СДЭК |

### POST /v2/webhooks — Подписка на вебхуки

Список подписок — `GET /v2/webhooks`, удаление — `DELETE /v2/webhooks/{uuid}`.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `type` | body | string | да | ORDER_STATUS, ORDER_MODIFIED, PRINT_FORM, RECEIPT, DOWNLOAD_PHOTO, PREALERT_CLOSED, ACCOMPANYING_WAYBILL, OFFICE_AVAILABILITY, DELIV_PROBLEM, DELIV_AGREEMENT |
| `url` | body | string | да | URL для событий |

## Нюансы

- Создание сущностей асинхронное: статус запроса `ACCEPTED` означает только первичную валидацию, итог — `SUCCESSFUL` или `INVALID`. Обычно 200–500 мс, при пиковой нагрузке до 30–60 секунд; опрашивайте с паузой 2–3 секунды.
- В `POST /v2/orders` нельзя одновременно передавать `shipment_point` и `from_location`, а также `delivery_point` и `to_location`.
- Вес в граммах, габариты в сантиметрах.
- Изменять заказ можно только в статусах `CREATED` и `ACCEPTED`.
- Вебхуки: таймаут подключения 15 секунд, при ошибках — до 12 повторов за 75 минут, потом доставка прекращается.
- Данные о сущностях, созданных через API, хранятся 1 год.
- Сообщения — в UTF-8; обязательные поля не могут быть пустыми.

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

- [Рассчитать стоимость и сроки доставки](https://mcp-everything.ru/integrations/cdek/scenarios/rasschitat-stoimost-i-sroki-dostavki.md)
- [Показать пункты выдачи в городе покупателя](https://mcp-everything.ru/integrations/cdek/scenarios/pokazat-punkty-vydachi-v-gorode.md)
- [Создать заказ и дождаться его регистрации](https://mcp-everything.ru/integrations/cdek/scenarios/sozdat-zakaz-i-dozhdatsya-ego.md)
- [Напечатать квитанцию и вызвать курьера](https://mcp-everything.ru/integrations/cdek/scenarios/napechatat-kvitantsiyu-i-vyzvat-kurera.md)

---

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