---
slug: "cdek"
name: "СДЭК API v2"
vendor: "СДЭК"
industry: "logistics"
docsUrl: "https://apidoc.cdek.ru/"
version: 2
updatedAt: "2026-10-24"
---

# СДЭК API v2

Отрасль: Логистика и доставка. Актуально на 2026-10-24.

Клиентский протокол интеграции с логистикой СДЭК: расчёт стоимости и сроков доставки, справочники населённых пунктов и пунктов выдачи, регистрация и изменение заказов, вызов курьера, печать квитанций и штрихкодов, договорённости о доставке, возвраты и вебхуки о статусах. Создание сущностей асинхронное: запрос сначала принимается, а результат проверяют отдельным методом или получают вебхуком.

## Сценарии

### Рассчитать стоимость и сроки доставки

Показать покупателю цену и срок доставки СДЭК в корзине или калькуляторе на сайте.

1. Получи токен: POST /v2/oauth/token с grant_type=client_credentials, client_id (Account) и client_secret (Secure password) из личного кабинета СДЭК. Токен живёт expires_in секунд — сохрани его и переиспользуй, а не запрашивай на каждый расчёт.
2. Рассчитай все доступные тарифы: POST /v2/calculator/tarifflist с from_location, to_location и packages. Вес передавай в граммах, габариты — в сантиметрах.
3. В ответе для каждого тарифа есть код, название, стоимость delivery_sum и срок period_min–period_max в днях. Покажи покупателю подходящие тарифы и сохрани tariff_code — он понадобится при создании заказа.
4. Для отладки используй тестовый адрес https://api.edu.cdek.ru и тестовую учётную запись из документации, на боевом — https://api.cdek.ru.

```bash
# Токен (кешируй на expires_in секунд)
TOKEN=$(curl -s -X POST "https://api.cdek.ru/v2/oauth/token?grant_type=client_credentials&client_id=<Account>&client_secret=<Secure password>" | jq -r .access_token)

# Все тарифы: Москва → Санкт-Петербург, посылка 1,5 кг
curl -X POST https://api.cdek.ru/v2/calculator/tarifflist \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
        "from_location": {"code": 44},
        "to_location": {"code": 137},
        "packages": [{"weight": 1500, "length": 20, "width": 15, "height": 10}]
      }'
```

### Показать пункты выдачи в городе покупателя

Список ПВЗ и постаматов СДЭК для выбора на странице оформления заказа.

1. Найди код населённого пункта СДЭК: GET /v2/location/cities по названию города. Код нужен и для расчёта, и для списка пунктов.
2. Запроси пункты выдачи: GET /v2/deliverypoints с city_code и type (PVZ, POSTAMAT или ALL). Для приёма оплаты при получении добавь allowed_cod=true, для крупных посылок — weight_max.
3. Покажи пункты на карте или списком и сохрани код выбранного пункта — он пойдёт в delivery_point заказа.
4. Обновляй список раз в сутки: пункты открываются и закрываются, хранить его статично нельзя.

```bash
# Код города
curl -G https://api.cdek.ru/v2/location/cities \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode 'city=Казань' \
  --data-urlencode 'country_codes=RU'

# Пункты выдачи и постаматы в этом городе
curl -G https://api.cdek.ru/v2/deliverypoints \
  -H "Authorization: Bearer $TOKEN" \
  -d city_code=<код города> \
  -d type=ALL \
  -d is_handout=true
```

### Создать заказ и дождаться его регистрации

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

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"
```

### Напечатать квитанцию и вызвать курьера

Подготовить отправление к передаче: напечатать документы и заказать забор посылки со склада.

1. Закажи квитанцию: POST /v2/print/orders со списком заказов. Квитанция формируется асинхронно — сначала придёт uuid задания.
2. Когда задание готово, скачай PDF по адресу /v2/print/orders/{uuid}.pdf с тем же токеном. Штрихкоды мест печатаются отдельно через /v2/print/barcodes.
3. Вызови курьера: POST /v2/intakes с датой и интервалом забора, адресом и контактами отправителя. Свободные даты можно заранее узнать через /v2/intakes/availableDays.
4. Чтобы не опрашивать готовность квитанции, подпишись на событие PRINT_FORM через POST /v2/webhooks.

```bash
# Квитанция для двух заказов
curl -X POST https://api.cdek.ru/v2/print/orders \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"orders": [{"order_uuid": "<uuid заказа 1>"}, {"order_uuid": "<uuid заказа 2>"}], "copy_count": 2}'

# Готовый PDF
curl -o receipt.pdf https://api.cdek.ru/v2/print/orders/<uuid задания>.pdf -H "Authorization: Bearer $TOKEN"
```

### Получать статусы заказов вебхуком

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

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

## Методы

### POST /v2/oauth/token — Получение токена авторизации

В ответе: `access_token`, `token_type`, `expires_in`, `scope`, `jti`.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `grant_type` | query | string | да | client_credentials |
| `client_id` | query | string | да | Идентификатор клиента |
| `client_secret` | query | string | да | Секретный ключ клиента |

### POST /v2/calculator/tarifflist — Расчёт по доступным тарифам

Стоимость и сроки доставки по всем доступным тарифам. Расчёт по конкретному тарифу — `POST /v2/calculator/tariff`, с доп. услугами — `POST /v2/calculator/tariffAndService`.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `date` | body | string | нет | Плановая дата передачи заказа; по умолчанию текущая |
| `type` | body | integer | нет | 1 — интернет-магазин (по умолчанию), 2 — доставка |
| `currency` | body | integer | нет | Код валюты расчёта |
| `lang` | body | string | нет | rus, eng, zho |
| `shipment_point` | body | string | нет | ПВЗ, куда клиент привезёт посылку |
| `delivery_point` | body | string | нет | ПВЗ доставки |
| `from_location` | body | object | да | Откуда: code, postal_code, country_code, city, address, координаты |
| `to_location` | body | object | да | Куда: те же поля |
| `packages` | body | array | да | Места |
| `packages[].weight` | body | integer | да | Вес в граммах |
| `packages[].length` | body | integer | нет | Длина, см |
| `packages[].width` | body | integer | нет | Ширина, см |
| `packages[].height` | body | integer | нет | Высота, см |

### 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}`.

### POST /v2/intakes — Вызов курьера

Регистрация заявки на вызов курьера за посылкой. Доступные даты — `POST /v2/intakes/availableDays`, статус — `GET /v2/intakes/{uuid}`.

### POST /v2/print/orders — Формирование квитанции к заказу

Асинхронно формирует квитанцию; готовый PDF — `GET /v2/print/orders/{uuid}.pdf`. Штрихкод места — `POST /v2/print/barcodes`.

### GET /v2/deliverypoints — Список офисов

Список действующих ПВЗ и постаматов. Обновляйте список раз в сутки, не храните статично.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `code` | query | string | нет | Код ПВЗ |
| `type` | query | string | нет | POSTAMAT, PVZ, ALL |
| `postal_code` | query | string | нет | Почтовый индекс |
| `city_code` | query | integer | нет | Код населённого пункта СДЭК |
| `country_code` | query | string | нет | Код страны ISO 3166-1 alpha-2 |
| `region_code` | query | integer | нет | Код региона СДЭК |
| `have_cashless` | query | boolean | нет | Есть терминал оплаты |
| `allowed_cod` | query | boolean | нет | Разрешён наложенный платёж |
| `weight_max` | query | integer | нет | Макс. вес, кг |
| `is_handout` | query | boolean | нет | Пункт выдачи |
| `is_reception` | query | boolean | нет | Приём заказов |
| `size` | query | integer | нет | Размер страницы |
| `page` | query | integer | нет | Номер страницы |

### GET /v2/location/cities — Список населённых пунктов

Справочник населённых пунктов СДЭК с кодами. Поиск по названию — `GET /v2/location/suggest/cities`.

### 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; обязательные поля не могут быть пустыми.

## Ошибки

| Код | Описание |
|---|---|
| `v2_internal_error` | Системная ошибка |
| `v2_similar_request_still_processed` | Предыдущий запрос того же типа над этой сущностью ещё не выполнен |
| `v2_update_forbidden` | Заказ уже принят к перевозке — изменять нельзя |
| `v2_bad_request` | Некорректный запрос |
| `v2_invalid_format` | Некорректное значение параметра |
| `v2_field_is_empty` | Не передано обязательное поле |
| `v2_parameters_empty` | Все параметры пустые |
| `v2_invalid_value_type` | Некорректный тип данных |
| `v2_entity_not_found` | Сущность не найдена или удалена |
| `v2_entity_forbidden` | Сущность принадлежит другому клиенту |

## Ограничения

- Гарантированная обработка — до 200 запросов в секунду на все методы; при превышении корректность не гарантируется.
- В заказе от 1 до 255 мест, до 10 телефонов получателя.

## Источники

- [Портал документации СДЭК API](https://apidoc.cdek.ru/)
- [OpenAPI-спецификация](https://gateway.cdek.ru/api-cdek-docs/web/docs/merged?sectionId=api_v2_integration)

---

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