# СДЭК API v2: Создать заказ и дождаться его регистрации

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

Передать заказ интернет-магазина в СДЭК и получить номер отправления.

1. Отправь заказ: POST /v2/orders с tariff_code, number (номер заказа у тебя), recipient (name и phones), packages с товарами в items и адресом: delivery_point для доставки до пункта выдачи или to_location для курьерской доставки — не оба сразу. Точно так же shipment_point и from_location взаимоисключающие.
2. Сервер ответит 202 Accepted с uuid заказа и статусом запроса ACCEPTED — это только первичная проверка, заказ ещё не создан.
3. Проверь результат: GET /v2/orders/{uuid} с паузой 2–3 секунды. Обычно ответ готов за полсекунды, в пиковые часы — до минуты. Статус запроса SUCCESSFUL означает, что заказ создан, INVALID — что нет, причина в errors.
4. Когда заказ создан, сохрани cdek_number: по нему покупатель отслеживает посылку.
5. Поменять заказ можно через PATCH /v2/orders, пока он в статусе CREATED или ACCEPTED. Если заказ уже принят к перевозке, придёт ошибка v2_update_forbidden.

```bash
# Тариф 136 — «Посылка склад-склад»: сдаёшь в ПВЗ, покупатель забирает в ПВЗ
curl -X POST https://api.cdek.ru/v2/orders \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
        "type": 1,
        "number": "ORDER-1042",
        "tariff_code": 136,
        "shipment_point": "<код ПВЗ, куда сдашь посылку>",
        "delivery_point": "<код ПВЗ покупателя>",
        "recipient": {"name": "Иван Петров", "phones": [{"number": "+79990001122"}]},
        "packages": [{
          "number": "1",
          "weight": 1500, "length": 20, "width": 15, "height": 10,
          "items": [{"name": "Кружка", "ware_key": "SKU-17", "payment": {"value": 0}, "cost": 990, "weight": 1500, "amount": 1}]
        }]
      }'

# Через 2–3 секунды — проверить, создан ли заказ
curl https://api.cdek.ru/v2/orders/<uuid> -H "Authorization: Bearer $TOKEN"
```

## Базовые 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` (из документации):

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

### POST /v2/orders — Регистрация заказа

Создаёт заказ на доставку. Возвращает `202 Accepted` с UUID заказа и статусом запроса; статус `ACCEPTED` не гарантирует создание заказа.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `type` | body | integer | нет | 1 — интернет-магазин, 2 — доставка |
| `number` | body | string | нет | Номер заказа в системе клиента (для ИМ), до 40 символов |
| `tariff_code` | body | integer | да | Код тарифа |
| `comment` | body | string | нет | Комментарий |
| `shipment_point` | body | string | нет | ПВЗ, куда клиент привезёт посылку; не вместе с from_location |
| `delivery_point` | body | string | нет | ПВЗ доставки; обязателен для тарифов «до склада» |
| `sender` | body | object | нет | Отправитель; обязателен для типа «доставка» |
| `recipient` | body | object | да | Получатель |
| `recipient.name` | body | string | да | ФИО контактного лица |
| `recipient.phones` | body | array | да | Телефоны (до 10): number, additional |
| `recipient.email` | body | string | нет | Email |
| `from_location` | body | object | нет | Адрес отправления; не вместе с shipment_point |
| `to_location` | body | object | нет | Адрес получения; не вместе с delivery_point |
| `to_location.address` | body | string | нет | Строка адреса |
| `to_location.code` | body | integer | нет | Код населённого пункта СДЭК |
| `delivery_recipient_cost` | body | object | нет | Доп. сбор за доставку с получателя (для ИМ) |
| `services` | body | array | нет | Дополнительные услуги |
| `packages` | body | array | да | Места, от 1 до 255 |
| `packages[].number` | body | string | да | Номер упаковки |
| `packages[].weight` | body | integer | да | Вес, граммы |
| `packages[].length` | body | integer | нет | Длина, см |
| `packages[].width` | body | integer | нет | Ширина, см |
| `packages[].height` | body | integer | нет | Высота, см |
| `packages[].items` | body | array | нет | Товары; обязательно для заказов «интернет-магазин» |
| `packages[].items[].name` | body | string | да | Наименование товара |
| `packages[].items[].ware_key` | body | string | да | Артикул |
| `packages[].items[].payment` | body | object | да | Оплата при получении за единицу (value ≥ 0) |
| `packages[].items[].cost` | body | number | да | Объявленная стоимость за единицу |
| `packages[].items[].weight` | body | integer | да | Вес |
| `packages[].items[].amount` | body | integer | да | Количество |
| `packages[].items[].marking` | body | string | нет | Код маркировки «Честный знак» |
| `print` | body | string | нет | Тип печатной формы для формирования |

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

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

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

### PATCH /v2/orders — Изменение заказа

Изменение возможно только в статусах `CREATED` и `ACCEPTED`. Удаление — `DELETE /v2/orders/{uuid}`.

## Нюансы

- Создание сущностей асинхронное: статус запроса `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/napechatat-kvitantsiyu-i-vyzvat-kurera.md)
- [Получать статусы заказов вебхуком](https://mcp-everything.ru/integrations/cdek/scenarios/poluchat-statusy-zakazov-vebhukom.md)

---

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