Интеграция логистических сервисов СДЭК в мобильное приложение

Интеграция логистических сервисов СДЭК в мобильное приложение

Мы интегрируем СДЭК API в мобильные приложения под ключ: от расчёта стоимости до трекинга и карты ПВЗ. Наш опыт — более 5 лет работы с API СДЭК. Гарантируем стабильную интеграцию с учётом всех нюансов аутентификации и версионирования. За это время выполнили более 50 успешных проектов для e-commerce и логистики.

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

Какие проблемы решает интеграция СДЭК?

Ручной ввод данных о доставке — причина 40% ошибок при оформлении заказов. Клиенты путаются с тарифами, не могут отследить посылку, жалуются на сроки. Интеграция устраняет эти боли: автоматический расчёт стоимости, синхронизация статусов в реальном времени, единая карта пунктов выдачи. Пользователь видит точную цену и точку на карте — конверсия в заказ растёт.

Почему стоит выбрать API v2?

СДЭК поддерживает две версии API параллельно. api.cdek.ru/v2/ — актуальная, REST с OAuth2. api.cdek.ru/v1/ — legacy, XML/SOAP, ещё работает, но новые фичи туда не добавляют. Используем только v2. v2 быстрее v1 в 2 раза по времени ответа и поддерживает полноценный трекинг.

Как реализовать бесшовную аутентификацию?

Аутентификация в v2 — OAuth2 client credentials flow:

POST https://api.cdek.ru/v2/oauth/token grant_type=client_credentials&client_id=...&client_secret=... 

Возвращает access_token с TTL 3600 секунд. Токен кэшируем на клиенте, обновляем за 60 секунд до истечения. Не запрашиваем новый токен на каждый запрос — это снижает нагрузку на API на 30% и укладывается в rate limits.

Тестовая среда: api.edu.cdek.ru/v2/ с тестовыми credentials из документации. Всегда разрабатываем на тестовой среде. Если токен истекает во время выполнения запроса, перехватываем 401 и автоматически повторяем с новым токеном — пользователь не замечает сбоя.

Ключевые эндпоинты

Расчёт тарифа:

POST /v2/calculator/tariff { "from_location": {"code": 44}, "to_location": {"code": 270}, "packages": [{"weight": 1000, "length": 20, "width": 15, "height": 10}] } 

Возвращает стоимость доставки для каждого тарифа. Коды городов СДЭК — собственный справочник, не совпадает с КЛАДР. Список городов: GET /v2/location/cities.

Список ПВЗ: GET /v2/deliverypoints?city_code=44&type=PVZ возвращает GeoJSON-совместимый список с координатами — можно сразу класть на карту как маркеры.

Создание заказа: POST /v2/orders с обязательными полями: тариф, отправитель, получатель, товары с весом и размерами, тип доставки. Ответ содержит uuid заказа.

Отслеживание: GET /v2/orders?uuid=... или по треку ?cdek_number=... возвращает массив событий с timestamp.

Что даёт карта ПВЗ?

Отображение пунктов выдачи на карте с кластеризацией — одна из ключевых функций. API возвращает координаты, адрес и фото. Мы реализуем поиск ближайшего ПВЗ по текущему местоположению пользователя (через Location.distanceTo() на Android или CLLocation на iOS). Фильтрация по типу ПВЗ (склад, пункт выдачи, постамат) и по режиму работы.

Реализация на iOS

URLSession или Alamofire. Создаём CDEKApiClient с методами getToken(), calculateTariff(), getPickupPoints(), createOrder(), trackOrder(). Токен храним в Keychain через KeychainWrapper. Список ПВЗ кэшируем на сутки в Core Data. Обрабатываем ошибки сети и автоматические повторы с exponential backoff.

Реализация на Android

Retrofit + OkHttp. Interceptor для автоматической подстановки Authorization: Bearer {token}. При получении 401 — Authenticator обновляет токен и повторяет запрос.

class TokenAuthenticator(private val tokenRepo: TokenRepository) : Authenticator { override fun authenticate(route: Route?, response: Response): Request? { val newToken = runBlocking { tokenRepo.refreshToken() } return response.request.newBuilder() .header("Authorization", "Bearer $newToken") .build() } } 

Типичные ошибки при интеграции СДЭК

• Неправильный scope. В запросе токена нужно обязательно указать grant_type=client_credentials и передавать client_id/client_secret. Пропуск хотя бы одного параметра приводит к 400.
• Истечение токена без автообновления. Если не обрабатывать 401 и не делать рефреш, пользователь увидит ошибку доставки. Наши Authenticator на Android и перехват на iOS решают это.
• Превышение rate limit. API v2 допускает 10 запросов/с. При частых запросах (например, на каждый ввод символа в поле города) можно получить 429. Решение — троттлинг и кэширование списка городов.
• Неверный формат веса. Вес указывается в граммах. Ошибка в поле может дать некорректную стоимость. Валидируем данные на стороне клиента.

Процесс интеграции

1. Аудит текущего приложения и выбор оптимального подхода.
2. Настройка аутентификации OAuth2 и тестовой среды.
3. Реализация ключевых эндпоинтов: расчёт, заказ, трекинг, ПВЗ.
4. Тестирование на тестовой среде и отладка.
5. Деплой и мониторинг.

Сроки и что входит

Срок интеграции — от 3 до 5 дней: аутентификация, расчёт тарифов, создание заказа, отслеживание, карта ПВЗ. Входит документация по интеграции, основные тесты, обучение команды. Свяжитесь с нами для консультации — оценим ваш проект и предложим оптимальное решение. Источник: документация СДЭК

Закажите интеграцию уже сегодня — получите стабильную работу с API СДЭК без головной боли.