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

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

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

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

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://apidoc.cdek.ru/ Вся интеграция одним документом: https://mcp-everything.ru/integrations/cdek.md