Как подключить СДЭК к сайту и Flutter-приложению

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

28 октября 2026Технологии14 мин чтения

---

Какие задачи решает интеграция СДЭК

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

Доставка в составе заказа

Цена доставки зависит от маршрута и параметров посылки, а сумма для покупателя — ещё и от правил магазина. Бесплатная доставка может оплачиваться продавцом, поэтому нулевая строка в корзине не означает нулевой тариф перевозчика. В заказе нужно сохранять обе величины и основание скидки.

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

Исходные данные магазина

• Доступ к API. Параметры подключения к программному интерфейсу СДЭК и условия договора, определяющие доступные операции.
• Отправка. Склады, города, график передачи посылок и доступные способы получения.
• Товары и упаковка. Масса, габариты, ограничения и правила распределения по посылкам.
• Оплата. Кто платит перевозчику, есть ли оплата при получении, как учитываются скидки и возвраты.
• Ответственные системы. Где хранится заказ, кто создаёт отправление и где сотрудник исправляет ошибку.

Рабочая и тестовая среды СДЭК разделены: api.cdek.ru и api.edu.cdek.ru. Методы и схемы данных ниже сверены с официальной спецификацией API 26 октября 2026 года. Тарифы и доступность услуг проверяют для договора конкретного магазина.

Как связать сайт, Flutter-приложение и API перевозчика

Общая серверная часть магазина позволяет использовать одинаковые правила доставки в браузере и приложении на Flutter. Клиенты запрашивают варианты у сервера, а тот обращается к перевозчику и сохраняет результат. Это рекомендуемая учебная схема; она не описывает внутреннее устройство клиентских проектов FITTIN.

Выбор и запрос идут от клиента через сервер к СДЭК. Результат возвращается тем же путём; события о доставке поступают на сервер и сохраняются для обоих интерфейсов.

Секреты доступа остаются на сервере

API использует OAuth 2.0: сервер получает токен через POST /v2/oauth/token. Секрет подключения и токен перевозчика следует хранить на сервере, вне кода сайта и мобильного приложения. Время обновления токена определяют по ответу авторизации. Устройство покупателя работает с учётной записью магазина и получает только разрешённые ему данные.

В разделе авторизации СДЭК описан обмен с сервисом. Разделение ответственности, проверка прав на заказ и защита секретов должны входить в требования к серверному API, независимо от выбранного языка разработки.

Общий договор обмена для двух интерфейсов

Для сайта и приложения задают одинаковые поля: способ доставки, идентификатор ПВЗ, цена покупателю, срок и время расчёта. Flutter отвечает за экраны и состояния загрузки, сервер — за допустимость выбора. Это помогает избежать ситуации, когда на сайте доступен самовывоз, а приложение предлагает доставку для того же товара.

Как организовать выбор ПВЗ на карте и списком

Пункт выдачи заказов должен быть доступен для выбранного способа доставки и параметров отправления. В интерфейсе покупателю нужны адрес и понятное подтверждение выбора; карта помогает найти точку, список остаётся альтернативой при неудобном масштабе или ошибке загрузки карты.

Справочник пунктов и сохранение выбора

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

У СДЭК есть официальный виджет выбора ПВЗ для веб-интерфейса. Его наличие не определяет устройство Flutter-экрана: для приложения отдельно выбирают карту и способ отображения точек. Если используется веб-экран внутри приложения, проверяют возврат выбранного пункта и восстановление корзины после закрытия экрана.

ТВОЕ — доставка СДЭК и выбор способа получения

В проекте ТВОЕ подключена доставка СДЭК. Покупателям доступны ПВЗ списком и на карте с адресом, ценой и сроком, курьерская доставка и самовывоз из магазина сети. В корзине есть прогресс до бесплатной доставки; порог зависит от способа получения. Отдельно обрабатываются товары, доступные только офлайн или для самовывоза.

При подключении доставки в приложении магазина одежды нужно согласовать правила всех способов получения. Смена ПВЗ, курьера или самовывоза должна пересчитывать условия и учитывать ограничения товаров.

Как рассчитать стоимость и срок доставки

Расчёт выполняют по фактической посылке и выбранному маршруту. Если в каталоге указана масса одного товара, серверу ещё нужно учесть количество и упаковку. При смене склада, состава корзины или способа получения прежний результат может потерять актуальность.

Запрос к калькулятору

Для одного тарифа используется POST /v2/calculator/tariff, для списка — POST /v2/calculator/tarifflist. В документации калькулятора масса упаковки задаётся в граммах, размеры — в сантиметрах. Перевод единиц должен выполняться явно: значение из товарной базы нельзя отправлять без проверки его смысла.

В ответе различаются базовая стоимость delivery_sum и сумма с дополнительными услугами и НДС total_sum. Для поля delivery_sum документация оговаривает зависимость включения НДС от договора. Строку покупателю рассчитывают по согласованному составу услуги, после чего применяют правила магазина. Нельзя автоматически считать базовую сумму окончательной ценой.

Срок перевозки и обещание магазина

Поля period_min и period_max выражены в рабочих днях, без дня приёма груза на складе. Отдельно предусмотрены календарные значения. Магазин должен учитывать свою подготовку заказа и выбранную дату передачи. Формулировка «доставка завтра» требует расчёта всей цепочки, а не механической подстановки числа из ответа.

Состояния расчёта и ошибок нужно учитывать при проектировании интерфейса оформления покупки.

Как создать отправление и передать данные заказа

Отправление создают после того, как магазин подтвердил состав заказа и выполнил собственное условие передачи в доставку. Для предоплаты это может быть подтверждённая оплата, для оплаты при получении — другой согласованный этап. Правило должно одинаково работать для сайта и приложения.

Данные и результат регистрации

Метод POST /v2/orders получает сведения об отправителе, получателе, доставке и содержимом отправления. Обязательные поля зависят от типа заказа и сценария. Сопоставление товаров, цен и оплаты при получении проверяют по разделу регистрации заказов, а не по случайному примеру запроса.

Создание работает асинхронно. Статус запроса ACCEPTED означает прохождение первичной проверки; далее возможны SUCCESSFUL или INVALID. Результат уточняют запросом информации о заказе, в том числе через GET /v2/orders/{uuid}. До подтверждения регистрации интерфейс должен показывать ожидание, а при ошибке — понятный путь исправления.

Связь заказа магазина с отправлением

Сервер сохраняет внутренний номер заказа и идентификатор отправления СДЭК. Если заказ разделяется между складами, связь становится «один заказ — несколько отправлений» и требует отдельной модели. Повторное нажатие кнопки или повтор сообщения об оплате должно находить существующую операцию, не создавать новую посылку.

Gulliver — доставка СДЭК и состав корзины

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

Учебный пример: покупатель видит три позиции, но одна недоступна к оформлению. Доставку рассчитывают для подтверждённых двух, а перед созданием отправления повторно проверяют состав. Это учебный сценарий проверки данных при интеграции доставки; он не описывает техническую реализацию Gulliver.

Как получать и показывать статусы доставки

Статус отправления хранится на сервере магазина и доступен покупателю при следующем открытии заказа. Закрытое приложение не должно останавливать обновления. Для нескольких посылок отображают состояние каждой и понятное общее состояние покупки.

События от перевозчика и сверка

Через POST /v2/webhooks регистрируют подписку на события, для статусов предусмотрен тип ORDER_STATUS. Webhook — уведомление сервера о событии. Перечень и параметры описаны в документации вебхуков СДЭК. При настройке проверяют существующие подписки: повторная регистрация того же типа может создать ещё одну.

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

Понятные состояния для покупателя

Технические коды переводят в формулировки магазина: «Подготовка к отправке», «В пути», «Ожидает в пункте выдачи». Это примеры текстов интерфейса, не названия кодов API. Оплату и доставку показывают раздельно: оплаченный заказ может ещё ожидать передачи перевозчику.

Push-уведомление об изменении статуса дополняет историю заказа. При повторном событии уведомление не отправляют второй раз, а после перехода из сообщения пользователь видит актуальные данные с сервера. Отдельно проверяют право пользователя на просмотр конкретного заказа.

Какие ошибки проверить до запуска

Проверка интеграции охватывает путь от изменения корзины до подтверждённого статуса. Успешный ответ одного метода показывает только один шаг. Особое внимание нужно уделить повторам, задержкам и действиям пользователя во время расчёта.

Ошибки, доступные сотруднику

В административном интерфейсе нужны причина отказа и действие: исправить данные, уточнить результат или повторить регистрацию после устранения ошибки. В журнале сохраняют технические идентификаторы и время операции; секреты доступа и избыточные данные получателя туда не записывают. Требования к наблюдению согласуют вместе с сопровождением приложения.

Приёмка на сайте и устройствах

Пройдите одинаковую корзину в браузере, на iOS и Android, включая отказ в геолокации и недоступность карты. Сценарии выполняют в тестовой среде, затем отдельно проверяют рабочие настройки. Для тестирования приложения нужны ожидаемые результаты; для проверки под нагрузкой — согласованные ограничения обращений к внешнему API.

После запуска отслеживайте долю ошибок расчёта, неподтверждённые регистрации, обнаруженные дубли и время последнего обновления статусов. У этих показателей должны быть ответственные и правила реакции. Целевые значения определяют по процессам магазина; универсальный срок ответа перевозчика здесь не предполагается.

Стоимость интеграции и данные для оценки

Стоимость зависит от существующей серверной части и числа пользовательских сценариев. Подключение карты, обмен с учётной системой и разделение заказа на посылки требуют разных работ. Оценку формируют после проверки текущих API и требований, отдельно учитывая расходы перевозчика и картографического сервиса.

• Готовность данных. Есть ли масса, габариты, склады и согласованные правила упаковки.
• Состав доставки. ПВЗ, курьер, самовывоз, несколько отправлений, оплата при получении.
• Устройство магазина. Кто создаёт накладную и как передаются изменения в CRM или учётную систему.
• Клиентские интерфейсы. Готовы ли экраны сайта и Flutter-приложения, включая ошибки и восстановление выбора.
• Эксплуатация. Исправление ошибок, сверка статусов, журналирование и уведомления сотрудников.

Материалы для оценки проекта

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

Если одновременно нужен новый магазин, сайт и приложение на одной базе позволяют согласовать общий путь покупки. Платформа FITTIN устроена как конструктор готовых модулей: любой из них можно доработать под процессы магазина. Состав подключения доставки определяют для проекта; наличие платформы само по себе не подтверждает готовность конкретной интеграции.

Итог

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

Часто задаваемые вопросы

Как подключить СДЭК к сайту интернет-магазина?

Определите способы получения, подготовьте данные товаров и получите параметры доступа к API. Затем свяжите выбор ПВЗ, расчёт и создание отправления с серверной частью магазина. Если накладные уже создаёт учётная система, сохраните один ответственный источник. Перед запуском проверьте смену корзины, ошибки расчёта, повторные действия и получение статусов. Для сайта на готовой системе отдельно оцените возможности существующего модуля и его совместимость с вашими правилами заказа.

Можно ли подключить СДЭК к Flutter-приложению?

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

Где взять ключи API СДЭК?

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

Как рассчитать стоимость доставки СДЭК на сайте?

Сервер передаёт калькулятору маршрут, тариф и параметры упаковок. В API масса указана в граммах, размеры — в сантиметрах. Ответ нужно сопоставить с дополнительными услугами, условиями договора и правилами магазина. После этого получается сумма для покупателя, которая может отличаться от расходов продавца. Пересчитывайте условия при изменении корзины или получения и проверяйте выбранный вариант перед подтверждением покупки.

Как получать статусы доставки СДЭК?

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

Почему отправление СДЭК не создаётся после запроса?

Регистрация асинхронна: принятие запроса ещё не подтверждает создание отправления. Проверьте результат обработки и сообщения об ошибках через методы получения информации о заказе. При разрыве связи сначала выясните судьбу исходного запроса, затем принимайте решение о повторе. Автоматическое создание новой заявки без сверки может привести к дублю. Сотруднику магазина нужен доступный способ исправить данные и увидеть окончательный результат.

Сколько стоит интеграция СДЭК с интернет-магазином?

Для оценки нужны текущая серверная схема, способы получения, данные товаров и перечень систем, участвующих в заказе. На объём влияют несколько складов, разделение отправлений, оплата при получении и обработка исключений. Наличие готового виджета карты покрывает только часть пути. Разработку и сопровождение оценивают по согласованному составу работ; тарифы перевозчика, услуги карты и другие внешние расходы учитывают отдельно.

Источники и границы примеров

Технические сведения проверены 26 октября 2026 года по официальной спецификации СДЭК API v2 и материалам CDEK-IT, ссылки приведены в соответствующих разделах. Схема взаимодействия и сценарии проверки — рекомендации по проектированию. В проектах ТВОЕ и Gulliver подключён СДЭК. Перечисленные функции интерфейса описаны в кейсах; учебная схема не раскрывает техническое устройство этих интеграций.

Никита БережновРуководитель отдела бэкенда