Тестирование интеграции СДЭК через API

Коротко: Тестирование интеграции СДЭК требует использования отдельного учебного контура api.edu.cdek.ru и специальных ключей Account и Password. Это позволяет имитировать создание заказов и расчет стоимости доставки без списания реальных средств и создания физических накладных. Важно помнить, что тестовые заказы не отображаются в боевом личном кабинете lk.cdek.ru и являются полностью виртуальными.

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

Зачем нужен тестовый контур СДЭК

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

Тестовый контур - это изолированная среда, которая полностью имитирует работу логистической системы, но не имеет связи с реальным миром. Если вы ошибетесь в расчете стоимости доставки или передадите неверный индекс, система выдаст ошибку в консоль, а не выставит счет вашему клиенту. Это критически важно для автоматизации крупных интернет-магазинов, где процесс оформления заказа завязан на цепочку из CRM, складской программы и платежного шлюза. Ошибка на одном этапе может «положить» всю цепочку, и только sandbox-режим позволяет выявить эти узкие места до запуска системы в продакшн.

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

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

Различия между боевым и учебным API

Главное различие, которое нужно осознать любому интегратору, заключается в физическом разделении баз данных. Боевой API (api.cdek.ru) работает с реальными деньгами, реальными складами и реальными курьерами. Любой запрос, отправленный на этот адрес с валидными ключами, считается официальным намерением совершить логистическую операцию. Учебный контур (api.edu.cdek.ru) - это своего рода симулятор. Он отвечает на запросы, имитирует логику расчетов и возвращает структурированные JSON-ответы, которые выглядят точно так же, как боевые, но не имеют юридической или финансовой силы.

Ниже приведена сравнительная таблица, которая поможет быстро сориентироваться в различиях:

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

Также стоит учитывать специфику данных. В боевом API данные о городах, складах и тарифах актуальны на текущую секунду. В учебном контуре данные могут периодически очищаться или обновляться с задержкой. Это не должно мешать разработке, так как структура ответов (схема JSON) остается идентичной. Если ваша интеграция корректно обрабатывает ответы от учебного API, она с вероятностью 99% будет работать и с боевым, при условии правильной смены эндпоинтов и ключей.

Важность понимания архитектуры

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

Настройка тестового режима api.edu.cdek.ru

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

Процесс настройки можно разделить на несколько этапов:

1. Выбор метода авторизации. Для современных интеграций это всегда OAuth 2.0, но в учебном контуре могут использоваться упрощенные методы проверки через Account и Password.
2. Конфигурация эндпоинтов. Убедитесь, что все ваши запросы (на расчет стоимости, на создание заказа, на получение списка городов) направлены именно на учебный домен.
3. Проверка сетевых доступов. Иногда корпоративные файрволы или настройки сервера могут блокировать запросы к поддоменам. Проверьте, что ваш сервер может "достучаться" до api.edu.cdek.ru.
4. Валидация структуры данных. Сначала отправьте самый простой запрос, например, на получение списка городов, чтобы убедиться, что авторизация прошла успешно.

Важный нюанс: многие разработчики забывают, что настройки тестового режима должны быть жестко разделены в коде. Рекомендуется использовать переменные окружения (.env файлы). Например, в переменной `CDEK_API_URL` для локальной разработки должен стоять учебный адрес, а для продакшн-сервера - боевой. Это исключает человеческий фактор, когда при деплое сайта на хостинг забывают переключить режим, и компания начинает отправлять реальные заказы в пустоту учебного контура.

Еще один момент касается документации. Сдэк api v2 документация для учебного контура практически идентична боевой, но всегда проверяйте, нет ли специфических параметров для эмуляции ошибок. Иногда полезно протестировать, как ваш сайт отреагирует на ошибку 400 (Bad Request) или 500 (Internal Server Error). В учебном режиме это можно сделать, намеренно передавая некорректные данные, что невозможно сделать в боевом режиме без риска для репутации перед перевозчиком.

Проверка доступности сервиса

Перед тем как приступать к глубокому тестированию бизнес-логики, выполните простой тест через cURL или Postman. Отправьте GET-запрос на любой доступный метод учебного API. Если вы получили структурированный ответ, даже если он содержит ошибку авторизации, значит, сетевой уровень настроен верно. Если же вы получаете Timeout или Connection Refused, проблема в настройках вашего сервера или сетевом окружении, и копать в сторону кода API бесполезно.

Использование тестовых ключей Account и Password

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

При использовании этих ключей система понимает, что все создаваемые заказы являются виртуальными. Вы можете генерировать любые суммы доставки, любые веса и габариты. Это позволяет тестировать экстремальные значения. Например, что произойдет, если клиент закажет посылку весом 1000 кг или с нулевой стоимостью? В боевом API такие запросы могут быть отклонены системой безопасности или привести к некорректным начислениям, а в тестовом режиме вы просто увидите, как ваш код обрабатывает такие ответы.

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

При реализации программного кода никогда не "зашивайте" эти ключи прямо в исходный код (hardcode). Это грубейшая ошибка безопасности. Даже если это всего лишь тестовые ключи, их наличие в публичном репозитории (например, на GitHub) - плохой тон. Используйте механизмы хранения секретов или переменные окружения. При переходе на боевой режим вам нужно будет просто заменить эти значения на реальные Account и Password из вашего личного кабинета lk.cdek.ru.

Особенности работы в sandbox-режиме

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

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

Третий нюанс касается интеграции платежей. Если ваш проект использует CDEK Pay, то для тестирования платежной логики используется отдельный механизм. Для него применяется специальный тестовый ключ и тестовая валюта с кодом TST. Это позволяет проверить, как ваша система реагирует на успешную оплату, отмену платежа или ошибку эквайринга, не совершая реальных транзакций. Это критически важный этап для e-commerce, так как ошибки в обработке платежных статусов - самая частая причина потери заказов и недовольства клиентов.

Подводя итог, sandbox-режим - это идеальная лаборатория, но она не является точной копией реальности в плане времени и физических процессов. Она точна в плане структуры данных и логики ответов. Используйте ее для проверки "математики" и "логики", но помните, что реальный мир гораздо более хаотичен и медленен.

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

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

Второй распространенный тип ошибок - это игнорирование различий в версиях API. Часто разработчики начинают писать интеграцию на базе старых методов, найденных в старых статьях, в то время как СДЭК активно продвигает API v2. Если вы пытаетесь использовать методы старой версии на эндпоинтах новой (или наоборот), вы получите невнятные ошибки авторизации или неверную структуру ответа. Всегда сверяйтесь с актуальной документацией, актуальной на текущую дату - 5 октября 2026 года.

Вот список типичных "граблей", на которые наступают даже опытные команды:

• Путаница с ключами: Попытка использовать боевой Account в учебном контуре api.edu.cdek.ru.
• Ожидание синхронности: Ожидание того, что тестовый заказ появится в личном кабинете lk.cdek.ru. Его там не будет.
• Игнорирование ошибок валидации: Разработчик видит, что API вернул ошибку (например, "неверный индекс"), и считает, что это проблема СДЭК, хотя на самом деле это его код передает некорректный формат данных.
• Забытые исключения: Код написан так, что он ожидает только успешный ответ (200 OK), и не обрабатывает ситуации, когда API возвращает 4xx или 5xx ошибки. В реальности сеть может моргнуть, а сервер СДЭК - уйти на перезагрузку.

Также часто встречается ошибка "неполного тестирования". Разработчик проверил, что заказ создается, но не проверил, как система ведет себя при изменении статуса заказа или при попытке пересчитать стоимость доставки для уже созданного заказа. Тестирование должно быть комплексным: вы должны проверить не только "счастливый путь" (happy path), когда всё работает идеально, но и все возможные сценарии отказов.

Переход с устаревших версий на API v2

Мир API не стоит на месте, и СДЭК не исключение. Сейчас идет активный процесс миграции на API v2.0. Если вы начинаете проект с нуля в октябре 2026 года, у вас нет причин использовать устаревшие версии. Но если у вас уже работает старая интеграция, переход на v2 станет необходимостью, так как поддержка старых методов рано или поздно будет прекращена.

Главное отличие API v2 заключается в использовании современного стандарта авторизации OAuth 2.0. Если в старых версиях вы могли просто передавать Account и Password в заголовках, то в v2 процесс выглядит иначе: вы сначала обмениваете свои учетные данные на временный access_token, и уже этот токен используете во всех последующих запросах. Это повышает безопасность, но усложняет архитектуру вашего кода - вам нужно реализовать механизм автоматического обновления токена, когда срок его действия истекает.

Процесс перехода рекомендуется делать поэтапно:

1. Аудит текущей интеграции: Составьте список всех методов, которые вы используете (расчет, создание, статусы, города).
2. Параллельное тестирование: Не отключайте старую версию сразу. Настройте в системе возможность переключаться между API v1 и API v2 через конфиг.
3. Тестирование в sandbox: Прогоните все сценарии через api.edu.cdek.ru, используя новые методы v2. Убедитесь, что структура ответов в вашей CRM/ERP корректно обрабатывается новым форматом.
4. Поэтапный раскат (Canary Deployment): Если возможно, переведите на API v2 сначала небольшой процент заказов или только одну категорию товаров, чтобы минимизировать риски.

Важно понимать, что API v2 - это не просто "другие ссылки". Это другая логика взаимодействия. Например, работа с адресами, городами и складами может иметь более глубокую вложенность в JSON-структуре. Если ваша интеграция написана на жестком парсинге по индексам массива, она "сломается" при переходе на v2. Используйте именованные поля и современные библиотеки для работы с JSON, чтобы сделать ваш код устойчивым к изменениям в структуре данных.

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

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

• Для тестов используйте только api.edu.cdek.ru, чтобы не создавать фейковые заказы в боевой базе.
• Тестовые заказы не видны в личном кабинете lk.cdek.ru и не ведут к реальной доставке.
• Всегда разделяйте боевые и тестовые ключи (Account/Password) через переменные окружения.
• API v2 - это стандарт. Используйте OAuth 2.0 и закладывайте логику обновления токенов.
• Тестируйте не только успех, но и ошибки (4xx, 5xx) для устойчивости вашей системы.