СДЭК API v2 API

Отрасль: Логистика и доставка. Актуально на 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.
# Токен (кешируй на 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. Обновляй список раз в сутки: пункты открываются и закрываются, хранить его статично нельзя.
# Код города
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.
# Тариф 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.
# Квитанция для двух заказов
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 сразу, а тяжёлую обработку делай в фоне, иначе повторы будут дублировать события.
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

Авторизация

Тип: 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 для событий

Нюансы

Ошибки

Код Описание
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 Сущность принадлежит другому клиенту

Ограничения

Источники

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