Для юридических лиц
Зарегистрироваться в личном кабинете
Здравствуйте! Оставьте свои контакты и мы перезвоним Вам!
Интеграция СДЭК с сайтом: пошаговое руководство для разработчиков
Когда количество заказов в интернет-магазине начинает измеряться десятками и сотнями в день, ручная обработка доставки становится неэффективной. Возникают ошибки в расчётах, задержки в обработке, теряются посылки — и всё это неизбежно ведёт к ухудшению клиентского опыта. Автоматизация доставки перестала быть просто удобным инструментом и превратилась в необходимость для любого растущего бизнеса.
Интеграция со СДЭК — это возможность полностью автоматизировать логистику: от расчёта стоимости доставки на этапе оформления заказа до автоматического создания заявки в системе перевозчика, отслеживания статусов и печати документов. Служба доставки СДЭК зарекомендовала себя как надёжный партнёр для интернет-бизнеса, располагая сетью из около 6000 пунктов выдачи заказов и предлагая гибкие решения для интеграции с онлайн-магазинами.
В этой статье мы подробно разберём пошаговую инструкцию по интеграции СДЭК с сайтом. Вы узнаете, как получить доступ к API, настроить авторизацию, реализовать основные методы, подключить веб-хуки для отслеживания статусов, а также как избежать типичных ошибок. Статья ориентирована на разработчиков, которые подключают СДЭК к интернет-магазину на любой CMS или самописной системе.
Что нужно знать перед началом интеграции
Прежде чем приступить к интеграции, важно убедиться, что у вас есть всё необходимое. Это сэкономит время и избавит от лишних вопросов в процессе работы.
- Требования к разработчикуДля успешной интеграции вам потребуются:
- Базовое понимание REST API, HTTP-запросов, JSON и принципов авторизации через токены.
- Навыки работы с выбранным языком программирования (PHP, Python, Ruby, Java, JavaScript и др.).
- Доступ к серверу или хостингу для настройки веб-хуков и тестирования.
- Опыт работы с системами управления сайтом (CMS), если вы планируете использовать готовый модуль.
- Что нужно получить от СДЭКДля доступа к API СДЭК необходимо:
- Заключить договор со СДЭК (для юридических лиц или индивидуальных предпринимателей). Доступ к API выдаётся только при наличии договора с компанией.
- Получить учётные данные для API: Для API v2.0 — client_id и client_secret. Эти данные создаются в личном кабинете СДЭК в разделе «Интеграция». Для устаревших версий API — Account и Secure Password.
- Доступ к личному кабинету СДЭК (https://lk.cdek.ru/) — здесь вы будете управлять ключами, настраивать веб-хуки и отслеживать заказы.
- Версии API СДЭКСДЭК предлагает две версии API:
- API v2.0 — современная версия, рекомендуется для всех новых интеграций. Использует OAuth 2.0 для авторизации. Базовый URL: https://api.cdek.ru/v2/.
- XML API (v1.5) — устаревшая версия, поддерживается для обратной совместимости.
Заключить договор со «СДЭК»
Для юридических лиц, ИП, самозанятых
* Нажимая на кнопку, вы даете согласие на обработку персональных данных и соглашаетесь c политикой конфиденциальности и публичной офертой
Пошаговая инструкция по интеграции
Интеграция СДЭК с сайтом — процесс, который можно разбить на семь последовательных шагов. Следуйте им, и вы сможете настроить автоматическую доставку в своём интернет-магазине.
- Шаг 1. Получение доступа к API СДЭК
- Авторизуйтесь в личном кабинете СДЭК по адресу https://lk.cdek.ru/.
- Перейдите в раздел «Интеграция» (https://lk.cdek.ru/integration).
- Нажмите кнопку «Создать новый ключ».
- Скопируйте и сохраните полученные client_id и client_secret в надёжном месте. Секретный ключ отображается только при создании — при его утере придётся генерировать новый.
- Для тестирования можно использовать тестовую среду https://api.edu.cdek.ru/ с общими тестовыми учётными данными, которые указаны в официальной документации.
- Шаг 2. Выбор способа интеграцииУ вас есть два основных варианта интеграции.
Вариант А: Готовый модуль для CMSЕсли ваш интернет-магазин работает на популярной CMS, самый быстрый способ — установить готовый модуль доставки.- WordPress + WooCommerce — официальный плагин CDEKDelivery:
- Установите плагин через меню «Плагины» в WordPress или загрузите архив в панели администратора.
- Активируйте плагин.
- Перейдите в WooCommerce → Настройки → Доставка и выберите «CDEKDelivery».
- Введите данные для подключения к API СДЭК и настройте параметры доставки. После установки модуля в настройках модуля необходимо указать Account и Secure Password из личного кабинета.
- 1С-Битрикс — интеграция охватывает расчёт стоимости доставки по тарифам, создание заказов, получение накладных и трекинг. СДЭК предоставляет официальный SDK для PHP, что упрощает работу с API.
- Другие CMS — модули доступны для OpenCart, PrestaShop, Magento 2 и других платформ.
- PHP SDK — cdek-it/sdk2.0, antistress-store/cdek-sdk-v2, neverfan/cdek-optimized-sdk2.
- Ruby — cdek_api_client.
- Другие языки — реализация HTTP-запросов напрямую к API.
- Шаг 3. Настройка авторизации и получение токенаAPI СДЭК v2.0 использует OAuth 2.0 для авторизации. Токен получается через POST-запрос на эндпоинт /v2/oauth/token с client_id и client_secret из личного кабинета.
Параметры запроса (формат x-www-form-urlencoded):- grant_type = client_credentials
- client_id = ваш идентификатор клиента
- client_secret = ваш секретный ключ
- Тестовая среда: https://api.edu.cdek.ru/v2/oauth/token
- Боевая среда: https://api.cdek.ru/v2/oauth/token
Важно: токен действует 3600 секунд (1 час). Его необходимо кэшировать и обновлять по истечении срока действия, а не запрашивать при каждом вызове API. Это снизит нагрузку на сервер и ускорит работу вашего сайта. - Шаг 4. Основные методы APIПосле получения токена вы можете работать со следующими основными методами API:
- Расчёт стоимости доставкиМетод: POST /v2/calculator/tariff — расчёт по одному тарифу.
- Метод: POST /v2/calculator/tarifflist — расчёт по всем доступным тарифам.
- Что передать: коды городов отправления и назначения, вес, габариты (длина, ширина, высота), код тарифа.
- Что получить: стоимость доставки (total_sum) и сроки (deliveryPeriodMin, deliveryPeriodMax).
- Создание заказаМетод: POST /v2/orders.
- Что передать: данные отправителя и получателя, список мест (товаров), код тарифа, дополнительные услуги.
- Что получить: UUID заказа в системе СДЭК и трек-номер для отслеживания.
- Получение информации о заказеМетод: GET /v2/orders?cdek_number={n}.
- Что получить: текущий статус, историю изменений, дату вручения.
- Отмена заказаМетод: DELETE /v2/orders/{uuid}.
- Печать документовМетод: POST /v2/print/orders — генерация накладной в формате PDF.
- Также доступна печать штрих-кода места (наклейка на посылку).
- Получение списка ПВЗМетод: GET /v2/deliverypoints.
- Что передать: код города, тип пункта.
- Что получить: адрес, телефон, режим работы, координаты для отображения на карте.
- Получение списка городовМетод: GET /v2/location/cities.
- Используется для поиска кода города по названию — необходимо для корректного расчёта стоимости доставки.
- Шаг 5. Настройка веб-хуков для отслеживания статусовВеб-хуки позволяют автоматически получать уведомления об изменении статуса заказа без необходимости периодически опрашивать API.
Как настроить веб-хуки:- В личном кабинете СДЭК перейдите в раздел управления веб-хуками.
- Укажите URL вашего сайта, на который СДЭК будет отправлять POST-запросы при изменении статуса заказа.
- СДЭК отправляет JSON-уведомления — ваш скрипт должен обрабатывать эти данные и обновлять статус заказа в своей системе.
- Эндпоинт для приёма веб-хуков (не требует авторизации).
- Обработку входящих JSON-уведомлений — парсинг данных, обновление статуса заказа в базе данных, запись в историю.
- Логирование всех входящих запросов для отладки.
- Шаг 6. Тестирование интеграцииПеред боевым запуском обязательно протестируйте интеграцию.
Использование тестовой среды:- Базовый URL: https://api.edu.cdek.ru/.
- В настройках модуля доставки включите тестовый режим (test_mode).
- Используйте тестовые учётные данные, если они предусмотрены для вашего модуля.
- Расчёт стоимости доставки для разных тарифов и городов.
- Создание заказа с разными типами тарифов (до ПВЗ, до двери, склад-дверь и т.д.).
- Отображение списка ПВЗ на карте при оформлении заказа.
- Получение статуса заказа через API и через веб-хуки.
- Частичная доставка (multi-seater mode) — распределение товаров по разным посылкам.
- Обработка ошибок — например, неверный код города, превышение допустимого веса и т.д.
- Шаг 7. Боевой запускКогда тестирование завершено успешно, можно переходить к боевому режиму:
- Переключите тестовый режим на «Нет» (test_mode = No).
- Используйте боевые учётные данные (client_id и client_secret от реального договора).
- Настройте адрес и контактные данные вашего склада отправления.
- Задайте способ передачи посылок в СДЭК (самовывоз в ПВЗ или вызов курьера).
- Выполните один реальный заказ и полностью отследите его путь — от создания до вручения получателю.
Примеры кода (для разных языков)
Ниже приведены примеры кода для реализации ключевых операций интеграции.
Установка SDK через Composer:
<pre><code>composer require cdek-it/sdk2.0</code></pre>
<p>Пример создания заказа:</p>
<pre><code><?php
use CdekSDK2\Client;
use CdekSDK2\BaseTypes\Order;
$client = new Client();
$cdek = new \CdekSDK2\Client($client);
$cdek->setAccount('ваш_account');
$cdek->setSecure('ваш_secure');
// Создание заказа
$order = Order::create([
// заполните данными заказа
]);
$res = $cdek->orders()->add($order);
if ($res->hasErrors()) {
foreach ($res->getErrors() as $error) {
// обрабатываем ошибки
}
}
if ($res->isOk()) {
$cdek_order = $cdek->formatResponse($res, Order::class);
$uuid = $cdek_order->entity->uuid; // сохраните UUID заказа
}
?></code></pre>
<p>Получение информации о заказе:</p>
<pre><code>$res = $cdek->orders()->get($uuid);
if ($res->isOk()) {
$order_info = $cdek->formatResponse($res, OrderInfo::class);
}</code></pre>
<p>Получение списка ПВЗ:</p>
<pre><code>$res = $cdek->offices()->getFiltered(['country_code' => 'ru']);
if ($res->isOk()) {
$pvzlist = $cdek->formatResponseList($res, PickupPointList::class);
foreach ($pvzlist->items as $pvz) {
// работа с данными ПВЗ
}
}</code></pre>
<pre><code>composer require cdek-it/sdk2.0</code></pre>
<p>Пример создания заказа:</p>
<pre><code><?php
use CdekSDK2\Client;
use CdekSDK2\BaseTypes\Order;
$client = new Client();
$cdek = new \CdekSDK2\Client($client);
$cdek->setAccount('ваш_account');
$cdek->setSecure('ваш_secure');
// Создание заказа
$order = Order::create([
// заполните данными заказа
]);
$res = $cdek->orders()->add($order);
if ($res->hasErrors()) {
foreach ($res->getErrors() as $error) {
// обрабатываем ошибки
}
}
if ($res->isOk()) {
$cdek_order = $cdek->formatResponse($res, Order::class);
$uuid = $cdek_order->entity->uuid; // сохраните UUID заказа
}
?></code></pre>
<p>Получение информации о заказе:</p>
<pre><code>$res = $cdek->orders()->get($uuid);
if ($res->isOk()) {
$order_info = $cdek->formatResponse($res, OrderInfo::class);
}</code></pre>
<p>Получение списка ПВЗ:</p>
<pre><code>$res = $cdek->offices()->getFiltered(['country_code' => 'ru']);
if ($res->isOk()) {
$pvzlist = $cdek->formatResponseList($res, PickupPointList::class);
foreach ($pvzlist->items as $pvz) {
// работа с данными ПВЗ
}
}</code></pre>
<pre><code>require 'cdek_api_client'
client = CdekApiClient::Client.new(
account: 'ваш_account',
secure_password: 'ваш_secure_password'
)
# Расчёт стоимости
result = client.calculate_tariff(
from_location: { code: '44' },
to_location: { code: '137' },
packages: [{ weight: 1000, length: 20, width: 20, height: 20 }],
tariff_code: 136
)
puts "Стоимость доставки: #{result['total_sum']} руб."
# Создание заказа
order = client.create_order(
tariff_code: 136,
from_location: { code: '44' },
to_location: { code: '137' },
packages: [{ weight: 1000, length: 20, width: 20, height: 20 }],
# другие параметры...
)
puts "UUID заказа: #{order['entity']['uuid']}"</code></pre>
client = CdekApiClient::Client.new(
account: 'ваш_account',
secure_password: 'ваш_secure_password'
)
# Расчёт стоимости
result = client.calculate_tariff(
from_location: { code: '44' },
to_location: { code: '137' },
packages: [{ weight: 1000, length: 20, width: 20, height: 20 }],
tariff_code: 136
)
puts "Стоимость доставки: #{result['total_sum']} руб."
# Создание заказа
order = client.create_order(
tariff_code: 136,
from_location: { code: '44' },
to_location: { code: '137' },
packages: [{ weight: 1000, length: 20, width: 20, height: 20 }],
# другие параметры...
)
puts "UUID заказа: #{order['entity']['uuid']}"</code></pre>
<p><strong>Получение токена</strong>:</p>
<pre><code>curl -X POST https://api.cdek.ru/v2/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
-d "client_id=ваш_client_id" \
-d "client_secret=ваш_client_secret"</code></pre>
<p><strong>Создание заказа</strong>:</p>
<pre><code>curl -X POST https://api.cdek.ru/v2/orders \
-H "Authorization: Bearer {ваш_токен}" \
-H "Content-Type: application/json" \
-d '{
"type": 1,
"tariff_code": 136,
"from_location": { "code": "44" },
"to_location": { "code": "137" },
"packages": [{ "weight": 1000, "length": 20, "width": 20, "height": 20 }],
"recipient": {
"name": "Иван Иванов",
"phones": [{ "number": "79991234567" }]
}
}'</code></pre>
<p><strong>Расчёт стоимости доставки</strong>:</p>
<pre><code>curl -X POST https://api.cdek.ru/v2/calculator/tariff \
-H "Authorization: Bearer {ваш_токен}" \
-H "Content-Type: application/json" \
-d '{
"type": 1,
"tariff_code": 136,
"from_location": { "code": "44" },
"to_location": { "code": "137" },
"packages": [{ "weight": 1000, "length": 20, "width": 20, "height": 20 }]
}'</code></pre>
<pre><code>curl -X POST https://api.cdek.ru/v2/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
-d "client_id=ваш_client_id" \
-d "client_secret=ваш_client_secret"</code></pre>
<p><strong>Создание заказа</strong>:</p>
<pre><code>curl -X POST https://api.cdek.ru/v2/orders \
-H "Authorization: Bearer {ваш_токен}" \
-H "Content-Type: application/json" \
-d '{
"type": 1,
"tariff_code": 136,
"from_location": { "code": "44" },
"to_location": { "code": "137" },
"packages": [{ "weight": 1000, "length": 20, "width": 20, "height": 20 }],
"recipient": {
"name": "Иван Иванов",
"phones": [{ "number": "79991234567" }]
}
}'</code></pre>
<p><strong>Расчёт стоимости доставки</strong>:</p>
<pre><code>curl -X POST https://api.cdek.ru/v2/calculator/tariff \
-H "Authorization: Bearer {ваш_токен}" \
-H "Content-Type: application/json" \
-d '{
"type": 1,
"tariff_code": 136,
"from_location": { "code": "44" },
"to_location": { "code": "137" },
"packages": [{ "weight": 1000, "length": 20, "width": 20, "height": 20 }]
}'</code></pre>
Частые ошибки при интеграции и их решение
- Ошибка «Fail to get token»
- Причина: модулю не удалось получить токен авторизации.
- Решение: проверьте, что в настройках модуля указаны актуальные client_id и client_secret из личного кабинета СДЭК (раздел «Интеграция»). Убедитесь, что вы используете правильные учётные данные для боевой или тестовой среды.
- Ошибка «v2_entity_not_found»
- Причина: заказ с указанным UUID не найден в системе СДЭК.
- Решение: проверьте правильность переданного UUID. Убедитесь, что заказ был успешно создан.
- Неверный формат даты
- Причина: дата и время передаются в неверном формате.
- Решение: используйте формат UTC — YYYY-MM-DDThh:mm:ss.
- Разделитель в числах
- Причина: используется запятая вместо точки.
- Решение: все дробные числа должны передаваться с точкой (например, 10.5, а не 10,5).
- Не найден город
- Причина: передан неверный код города или город отсутствует в справочнике.
- Решение: используйте метод GET /v2/location/cities для поиска кода города по названию.
- Ошибка 429 Too Many Requests
- Причина: слишком много запросов к API за короткий промежуток времени.
- Решение: обновите модуль до последней версии и проверьте условия использования API. Реализуйте кэширование токена и результатов расчётов.
- Габариты не передаются
- Причина: в некоторых версиях API не предусмотрена передача габаритов для каждого товара.
- Решение: укажите габариты на уровне посылки (packages) или используйте стандартные значения в настройках модуля.
- Заказ не создаётся при использовании тестовой среды
- Причина: перепутаны URL тестовой и боевой среды.
- Решение: для тестов используйте https://api.edu.cdek.ru/, для боевого режима — https://api.cdek.ru/.
Часто задаваемые вопросы
Да. Для получения боевых ключей API необходим договор со СДЭК. В тестовом режиме можно использовать общие тестовые данные.
В личном кабинете СДЭК в разделе «Интеграция» (https://lk.cdek.ru/integration) нажмите кнопку «Создать новый ключ».
Коды тарифов указаны в официальной документации API (приложение 1 к протоколу интеграции). Также их можно получить через метод /v2/tariff/list.
Да, API поддерживает международные отправления. Для международных заказов необходимо передавать дополнительные поля: date_invoice, shipper_name, shipper_address.
Через веб-хуки (рекомендуемый способ) или через метод GET /v2/orders?cdek_number={номер_заказа}.
По вопросам интеграции обращайтесь на почту integrator@cdek.ru. Также доступна документация на официальном сайте.
От 1 дня (при использовании готового модуля для CMS) до 2–3 недель (при кастомной разработке через API).
Только в тестовом режиме с общими тестовыми данными. Для полноценной работы в боевой среде договор обязателен.
Заключение
Интеграция СДЭК с сайтом открывает перед интернет-магазином широкие возможности для автоматизации логистики. Расчёт стоимости доставки в реальном времени, автоматическое создание заказов, печать документов и отслеживание статусов — всё это перестаёт быть рутиной и становится частью автоматизированного бизнес-процесса.
Главные выводы:
- Выберите подходящий способ интеграции: готовый модуль для CMS (быстро и просто) или кастомная разработка через API (максимальная гибкость).
- Для доступа к API необходимо заключить договор со СДЭК и получить client_id и client_secret в личном кабинете.
- API v2.0 использует OAuth 2.0 — токен действует 3600 секунд, его необходимо кэшировать.
- Основные методы API: расчёт стоимости, создание заказа, получение информации, печать документов, список ПВЗ и городов.
- Веб-хуки позволяют получать уведомления об изменении статусов в реальном времени.
- Тщательное тестирование в тестовой среде — залог успешного боевого запуска.
Не откладывайте автоматизацию доставки на потом. Чем быстрее вы настроите интеграцию, тем больше сэкономите времени и денег, а ваши клиенты будут получать быструю и прозрачную доставку.
Начните интеграцию прямо сейчас — получите доступ к API в личном кабинете СДЭК или обратитесь в поддержку разработчиков.
Остались вопросы по доставке?
Заключить договор со «СДЭК»
Здравствуйте! Оставьте свои контакты и мы перезвоним Вам!