Интеграция со СДЭК: требования к документации

Коротко: Для успешной интеграции со СДЭК необходимо использовать актуальный REST API 2.0, предварительно заключив договор с логистической компанией. Процесс требует обязательного тестирования в среде api.edu.cdek.ru, соблюдения стандарта ISO 8601 для дат и настройки Webhooks для автоматического отслеживания статусов заказов. Использование устаревших версий API (1.5) не рекомендуется для новых проектов.

Кстати, в AmSales мы делаем автоматизацию склада и разработку личных кабинетов под ключ. Если нужна помощь - напишите нам.

Выбор версии API: почему REST 2.0 приоритетнее

Когда бизнес решает автоматизировать доставку, первым делом возникает вопрос: какую версию протокола использовать? На текущий момент, 19 октября 2026 года, в документации СДЭК четко прослеживается разделение. Существуют протоколы 1.5 и 2.0, но если вы начинаете разработку с нуля, выбор в пользу REST API 2.0 - это не просто рекомендация, а вопрос выживаемости вашего проекта в долгосрочной перспективе.

Версия 1.5 (XML API) все еще поддерживается для обеспечения обратной совместимости с очень старыми системами, но она постепенно уходит в прошлое. Она тяжеловесна, менее гибкая и требует больше ресурсов на парсинг данных. REST 2.0, напротив, построен на современных принципах, предлагает более интуитивную структуру запросов и быстрее работает с мобильными приложениями и современными веб-интерфейсами. Именно на REST 2.0 сейчас сделан основной упор во всех новых SDK и модулях для популярных CRM-систем.

Сравнение версий для разработчика

При выборе версии стоит учитывать, что интеграция со СДЭК API 2.0 позволит вам легче масштабировать систему. Если ваш маркетолог завтра захочет внедрить сложную систему лояльности, завязанную на моментальный расчет стоимости доставки в корзине, REST-протокол справится с этим быстрее и с меньшим количеством ошибок в коде. Попытка "сэкономить" и использовать старую версию приведет к тому, что через год-два вам придется переписывать весь модуль интеграции заново, когда поддержка 1.5 будет окончательно прекращена.

Важный нюанс: документация СДЭК для разработчиков на портале apidoc.cdek.ru сейчас максимально детализирована именно под вторую версию. Это значит, что найти решение типичной проблемы или получить пример кода для REST-запроса будет в разы проще, чем для старого XML-формата. Вы экономите время своих программистов, выбирая стандарт, который является индустриальным драйвером.

Юридический этап: договор и получение ключей доступа

Техническая часть - это только половина дела. Вы не сможете отправить ни одного запроса к серверу, пока не пройдете юридический этап. В отличие от публичных API (вроде карт или погоды), доступ к логистическим данным СДЭК строго регламентирован. Первое и самое главное правило: вы должны стать клиентом СДЭК и заключить с ними официальный договор на оказание транспортно-экспедиционных услуг.

Процесс выглядит следующим образом. Вы подаете заявку на сайте, подписываете документы (сейчас это чаще всего происходит через ЭДО), и после того как ваш статус в системе обновится на "Действующий клиент", вам открывается доступ к личному кабинету. Именно там, в разделе для разработчиков, вы найдете свои уникальные идентификаторы: Client ID и Client Secret. Без этих ключей любая попытка настройки API СДЭК в CRM закончится ошибкой авторизации 401 Unauthorized.

Порядок действий для бизнеса

1. Регистрация на сайте СДЭК как юридического лица или ИП.
2. Заключение договора на доставку (учитывайте актуальный Регламент оказания услуг, который претерпел изменения с 1 июля 2026 года).
3. Ожидание активации учетной записи в системе.
4. Генерация API-ключей в личном кабинете.

Не стоит пытаться использовать "тестовые" ключи из открытых репозиториев или надеяться на публичные доступы. Все запросы привязаны к вашему тарифу и условиям договора. Если вы планируете интеграцию с логистикой для крупного интернет-магазина, убедитесь, что в договоре прописаны все необходимые условия для работы с вашим объемом заказов. Ошибка на этом этапе - это простой бизнеса, когда техническая команда готова, а "вход" в систему закрыт юридическим отделом.

Также стоит помнить, что требования к интеграции с логистикой включают в себя и финансовую сторону. Ваши ключи доступа определяют, какие именно методы будут вам доступны. Например, если у вас не подключен сервис CDEK Pay, запросы на оплату через API будут возвращать ошибку. Поэтому юридическая чистота и полнота договора напрямую влияют на технические возможности вашего софта.

Разделение сред: тестирование на api.edu.cdek.ru

Никогда, слышите, никогда не пытайтесь тестировать интеграцию сразу на "боевом" сервере. Это классическая ошибка, которая приводит к тому, что в систему случайно создаются сотни фейковых заказов, а складские службы получают уведомления о доставке несуществующих посылок. У СДЭК предусмотрена профессиональная среда для таких случаев - api.edu.cdek.ru.

Тестовая среда (sandbox) - это точная копия рабочей системы, но с "пустыми" данными. Здесь вы можете имитировать создание заказа, расчет стоимости, выбор ПВЗ и даже отмену доставки. Это критически важно для проверки логики вашей CRM. Например, вы должны убедиться, что при ошибке в адресе система корректно возвращает сообщение, а не "падает" в бесконечный цикл или не выдает нечитаемую ошибку. Работа через api.edu.cdek.ru позволяет отладить все сценарии без риска для реальной отчетности и финансов.

Как организовать процесс тестирования

Сначала разработчики прописывают базовые эндпоинты, используя тестовые ключи. Затем настраивается цепочка: запрос на расчет -> запрос на создание заказа -> запрос на получение трек-номера. На этом этапе важно проверить, как ваша система обрабатывает разные типы ответов от сервера. Что будет, если СДЭК вернет 500 ошибку? Что, если в ответе придет пустой список ПВЗ? Тестовая среда позволяет "сломать" систему в контролируемых условиях и подготовить к этому реальный продакшн.

После того как все сценарии отработаны на api.edu.cdek.ru, происходит переключение на рабочий адрес api.cdek.ru. Это делается путем замены базового URL в конфигурационном файле вашего приложения и замены тестовых ключей на реальные. Если вы сделали это правильно, переход будет бесшовным. Если нет - готовьтесь к тому, что первый же реальный заказ может превратиться в кошмар для логиста.

Важный нюанс: иногда тестовая среда может работать медленнее или иметь небольшие отличия в наборе доступных методов по сравнению с рабочей. Поэтому финальный этап проверки перед запуском должен включать в себя "smoke-test" (дымовое тестирование) на рабочей среде с одним реальным, но минимальным заказом, чтобы убедиться, что все цепочки - от API до склада - работают корректно.

Технические требования к форматам данных и ISO 8601

Для разработчика интеграция со СДЭК API 2.0 - это прежде всего работа с данными. Одной из самых частых причин сбоев в передаче информации является неправильный формат дат и времени. С 10 июня 2026 года в базовые типы данных СДЭК были официально добавлены требования к использованию формата `localDateTime`. Это означает, что вы не можете просто отправить "19.10.2026 14:00". Система ожидает строгого соблюдения стандарта ISO 8601.

Стандарт ISO 8601 требует представления даты и времени в формате YYYY-MM-DDThh:mm:ss. Например: `2026-10-19T14:30:00`. Если ваша CRM или складская программа использует другой формат (например, привычный многим DD/MM/YYYY), данные будут отклонены сервером СДЭК. Это может выглядеть как странная ошибка "Invalid parameter", но на самом деле проблема в лишней точке или неверном порядке цифр. Всегда проверяйте, как ваш бэкенд сериализует объекты даты перед отправкой JSON-пакета.

Ключевые правила работы с данными

• Используйте JSON как основной формат обмена.
• Даты и время передавайте строго по ISO 8601.
• Соблюдайте кодировку UTF-8, чтобы кириллические адреса и фамилии клиентов не превратились в "кракозябры".
• Учитывайте, что некоторые поля могут быть обязательными (например, индекс или вес), и их отсутствие приведет к ошибке валидации.

Еще один момент - работа с весом и габаритами. В API 2.0 важно передавать данные в тех единицах измерения, которые ожидает система. Ошибка в расчете объема (длина * ширина * высота) может привести к тому, что стоимость доставки, рассчитанная в вашей корзине, будет в разы отличаться от той, которую СДЭК выставит в инвойсе. Это прямой путь к конфликтам с покупателями и убыткам для бизнеса. Рекомендуем внедрить автоматическую проверку габаритов на стороне вашей системы еще до отправки запроса к API.

Наконец, не забывайте про обработку типов данных. Если API ожидает число (integer или float), а вы присылаете строку `"10"` (в кавычках), некоторые строгие парсеры могут выдать ошибку. Тщательно следуйте документации СДЭК для разработчиков, где для каждого поля указан его тип. Это сэкономит часы отладки, когда система начнет вести себя непредсказуемо при росте нагрузки.

Безопасность платежей и подпись запросов CDEK Pay

Если ваш бизнес-процесс подразумевает оплату доставки прямо в момент оформления заказа на сайте, вам понадобится интеграция с сервисом CDEK Pay. Это не просто "кнопка оплаты", а сложный механизм, требующий повышенного внимания к безопасности. Здесь стандартных ключей доступа Client ID и Client Secret недостаточно. Для подтверждения того, что запрос на оплату пришел именно от вашего сервера, а не от злоумышленника, используется механизм подписи запросов секретным ключом.

Подпись (signature) - это результат хеширования определенных данных запроса с использованием вашего секретного ключа. Сервер СДЭК на своей стороне выполняет ту же операцию. Если результаты совпадают, транзакция считается легитимной. Если вы ошибетесь хотя бы в одном символе при формировании строки для подписи, платеж будет отклонен. Это критически важный аспект: неправильная реализация подписи не только блокирует продажи, но и делает вашу систему уязвимой для подмены данных о сумме платежа.

Как работает безопасный цикл оплаты

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

Рекомендуем хранить секретный ключ для подписи в защищенных переменных окружения (environment variables), а не прописывать его прямо в коде (hardcode). Это базовое правило безопасности, которое часто игнорируют при быстрой настройке API СДЭК в CRM. Если ключ попадет в публичный репозиторий на GitHub, любой сможет инициировать платежи от вашего имени или манипулировать данными о транзакциях.

Кроме того, при работе с CDEK Pay важно учитывать требования по обработке возвратов. В документации CDEK Pay API есть отдельные разделы, описывающие, как программно инициировать возврат средств клиенту. Это должно быть частью вашей интеграции, чтобы менеджеры могли делать это одной кнопкой в интерфейсе CRM, не переходя в личный кабинет СДЭК вручную. Автоматизация возвратов - это не только удобство, но и соблюдение законодательства о защите прав потребителей.

Автоматизация статусов через Webhooks и трекинг

Клиенты ненавидят неопределенность. "Где моя посылка?" - это самый частый вопрос в службе поддержки любого интернет-магазина. Чтобы не отвечать на него вручную, ваша интеграция должна поддерживать автоматический трекинг. Самый эффективный способ сделать это - использование Webhooks (вебхуков). Вместо того чтобы ваша система каждые 15 минут опрашивала сервер СДЭК ("А что там с заказом №123?"), сервер СДЭК сам присылает уведомление, как только статус посылки меняется.

Настройка Webhooks позволяет мгновенно обновлять информацию в вашей CRM или отправлять клиенту SMS/Email: "Ваш заказ прибыл в пункт выдачи". Это радикально снижает нагрузку на операторов и повышает уровень сервиса. Однако для работы вебхуков ваш сервер должен иметь публичный URL, доступный извне, и быть готовым обрабатывать входящие POST-запросы в режиме реального времени. Если ваш сервер "упадет" в момент отправки уведомления, информация о перемещении посылки может потеряться.

Рекомендации по внедрению трекинга

1. Настройте эндпоинт для приема уведомлений, который будет быстро отвечать кодом 200 OK.
2. Реализуйте очередь обработки сообщений. Если обработка уведомления (например, обновление статуса в базе) занимает много времени, СДЭК может посчитать, что ваш сервер не работает, и при повторной попытке заблокирует отправку.
3. Обязательно логируйте все входящие вебхуки. Если клиент пожалуется, что статус не обновился, у вас будет возможность проверить, приходило ли уведомление от СДЭК и почему оно не обработалось.

Если по какой-то причине вы не можете использовать вебхуки (например, из-за ограничений сетевой безопасности), у вас остается вариант "pull-модели" - периодического опроса API по расписанию. Но помните: это создает лишнюю нагрузку на серверы и может привести к задержкам в информировании клиента. При использовании pull-модели важно рассчитывать интервалы так, чтобы не превысить лимиты (rate limits) на количество запросов в минуту, установленные СДЭК.

Интеграция статусов должна быть сквозной. Когда статус меняется на "Доставлено", система должна не только обновить карточку заказа, но и, например, отправить клиенту письмо с просьбой оставить отзыв или автоматически закрыть сделку в CRM. Именно такая глубокая автоматизация превращает простую доставку в мощный инструмент маркетинга и удержания клиентов.

Особенности интеграции сервиса СДЭК Фулфилмент

Многие предприниматели путают обычную доставку с сервисом СДЭК Фулфилмент, но с точки зрения интеграции это принципиально разные вещи. Если при обычной доставке вы только передаете данные о заказе, то при работе с фулфилментом вы передаете данные о товарах, которые СДЭК должен хранить, упаковывать и отгружать за вас. Для этого существует отдельный сервис CDEK.api, который требует специфической настройки.

Интеграция с фулфилментом подразумевает управление остатками на складе логистического оператора. Ваша система должна не просто "отправлять заказы", а синхронизировать складские запасы. Если на складе СДЭК закончился товар, ваша CRM должна мгновенно узнать об этом и скрыть позицию с сайта, чтобы не продать то, чего нет. Это требует настройки двустороннего обмена данными: вы передаете заказы на сборку, а система возвращает информацию об упаковке, весе и фактическом наличии.

Что нужно учитывать при работе с фулфилментом

Во-первых, это работа с товарными матрицами и артикулами. Ваши SKU (Stock Keeping Unit) должны строго совпадать с теми, что зарегистрированы в системе СДЭК Фулфилмент. Любое расхождение приведет к тому, что при попытке создать заказ система выдаст ошибку "Товар не найден". Во-вторых, это учет упаковки. При интеграции важно передавать информацию о том, в какой тип короба или пакета должен быть упакован товар, если это предусмотрено вашими правилами.

В-третьих, это финансовая прозрачность. Работа с фулфилментом подразумевает дополнительные списания за хранение, упаковку и обработку каждого заказа. Ваша система учета должна уметь корректно учитывать эти расходы, чтобы вы могли видеть реальную маржинальность бизнеса. Интеграция должна позволять выгружать отчеты по складским операциям, чтобы сверять их с данными из личного кабинета СДЭК.

На практике интеграция с фулфилментом - это более сложный проект, чем просто "подключить доставку". Он требует участия не только разработчиков, но и менеджеров по закупкам и складских работников. Если вы планируете масштабироваться, использование СДЭК Фулфилмент через API станет вашим главным преимуществом, позволяя сосредоточиться на продажах, а не на управлении коробками и скотчем.

Типичные ошибки при составлении ТЗ на интеграцию

Самая большая проблема, с которой сталкиваются собственники и РОПы, - это размытое техническое задание. Когда в ТЗ написано "нужна интеграция со СДЭК, чтобы заказы уходили автоматически", разработчики пишут код, который работает "в вакууме", но ломается при первой же реальной проблеме. Плохое ТЗ - это прямой путь к раздуванию бюджета и срыву сроков.

Первая и самая частая ошибка - отсутствие описания обработки исключений (error handling). Хорошее ТЗ должно отвечать на вопрос: "Что делать, если API СДЭК недоступен?", "Что делать, если адрес клиента не проходит валидацию?", "Что делать, если вес посылки превышает допустимый?". Если эти сценарии не прописаны, система либо просто остановит работу, либо (что хуже) создаст некорректные данные, которые придется исправлять вручную.

Список критических ошибок в ТЗ

• Отсутствие требований к форматам: не указано использование ISO 8601 или JSON.
• Игнорирование тестовой среды: нет требования об обязательном тестировании на api.edu.cdek.ru.
• Нет описания логики статусов: не прописано, какие именно статусы из API должны триггерить действия в CRM.
• Не учтена безопасность: не прописаны требования к хранению ключей и подписи запросов.
• Отсутствие требований к синхронизации остатков: (актуально для фулфилмента).

Вторая ошибка - попытка "изобрести велосипед". Не нужно просить разработчиков писать свой собственный протокол обмена данными или пытаться переделать логику СДЭК под себя. Ваша задача - максимально точно описать, как существующие возможности API 2.0 должны встроиться в ваши бизнес-процессы. ТЗ должно быть ориентировано на результат: "При изменении статуса заказа на 'В пути' в СДЭК, статус сделки в CRM должен измениться на 'Доставка', а клиенту должно уйти письмо с трек-номером". Вот это - понятное требование, которое можно протестировать.

Наконец, не забывайте про масштабируемость. Если вы сегодня возите 10 посылок в неделю, а через год планируете 1000 в день, ваше ТЗ должно учитывать нагрузки. Уточните у разработчиков, как система будет справляться с массовой обработкой заказов и не "ляжет" ли база данных при получении сотен вебхуков одновременно. Качественное ТЗ - это ваш страховой полис от бесконечных правок и переплат.

Что запомнить

• Используйте только REST API 2.0 - это современный стандарт, на который ориентируется СДЭК.
• Сначала договор и ключи, затем разработка. Без договора API не заработает.
• Тестируйте всё на api.edu.cdek.ru, прежде чем переходить в продакшн.
• Соблюдайте ISO 8601 для дат, иначе интеграция будет постоянно "сыпаться".
• Автоматизируйте статусы через Webhooks, чтобы не утонуть в ручной обработке заказов.