Django backend для мобильной торговли: как спроектировать API каталога и заказов

05.11.2026 Эксперт 23 мин чтения

---

Серверная часть интернет-магазина: что заложить в контракты каталога, корзины и заказа, чтобы приложение выдержало рост нагрузки и смену учётной системы.

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

Что такое серверная часть мобильной торговли и за что отвечает API

Серверная часть (backend) — программа на сервере, которая хранит данные магазина и правила работы с ними: что считается товаром, по какой цене он продаётся сегодня, сколько единиц доступно к заказу, какие переходы статусов возможны у заказа. Django — веб-фреймворк на языке Python с готовой работой с базой данных, правами доступа и административным интерфейсом. Django REST Framework (DRF) — библиотека к нему, которая отвечает за HTTP-интерфейсы для внешних клиентов.

API (Application Programming Interface) — набор адресов и форматов ответа, по которым приложение обращается к серверу. В деловых терминах это контракт: приложение рассчитывает получить поле с таким названием и таким типом значения, сервер обязуется его отдавать. Пока контракт соблюдается, мобильное приложение и серверная часть развиваются независимо друг от друга — в том числе если клиентскую часть позже переписывают на другом стеке (матрица выбора между Flutter и нативной разработкой).

Разница между базой данных и контрактом API

База данных — внутреннее устройство магазина, её схему меняют в любой момент. Контракт API виден снаружи, и здесь у мобильного приложения есть особенность, которой нет у сайта: установленная у покупателя версия обновляется не по решению магазина. Часть аудитории месяцами остаётся на старых версиях, и старые контракты продолжают вызываться. Отсюда главное проектное требование: внутреннюю схему данных переделывают свободно, внешний контракт — только расширяют.

Из чего состоит серверная часть магазина

• Каталог — категории, карточки товаров, характеристики, медиафайлы, поиск и фильтры.
• Цены и остатки — отдельный поток данных с собственной частотой обновления.
• Корзина и заказ — пересчёт состава, резерв товара, оформление, оплата, статусы.
• Профиль и права доступа — регистрация, вход, адреса, история покупок, программа лояльности.
• Интеграции — учётная система, платёжный сервис, службы доставки, уведомления.

Зачем бизнесу проектировать API до старта разработки

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

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

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

Архитектура серверной части на Django: слои и компоненты

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

• HTTP-слой — представления и сериализаторы DRF: разбор запроса, проверка входных данных, формирование ответа. Бизнес-правил здесь нет.
• Слой бизнес-правил — модули, которые считают корзину, резервируют товар, переводят заказ в следующий статус. Их вызывают и HTTP-слой, и фоновые задачи, и административный интерфейс.
• Слой данных — модели Django и база PostgreSQL, с разделением чтения витрины и записи.
• Кеш — Redis или другое хранилище в памяти для готовых ответов каталога.
• Очередь задач — Celery с брокером сообщений для всего, что не должно происходить внутри запроса покупателя.
• Адаптеры интеграций — по одному модулю на внешнюю систему: учёт, оплата, доставка, уведомления. Внешние форматы дальше адаптера не проходят.
• Хранилище медиафайлов — объектное хранилище и сеть доставки контента (CDN) для изображений товаров.

Выделенный слой бизнес-правил

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

Разделение путей чтения и записи

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

API каталога: категории, карточки, фильтры, пагинация

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

Контракт списка товаров

GET /api/v1/catalog/products?category=krossovki&brand=lusio&cursor=cD0yMDI2

{
  "items": [
    {
      "sku": "SKU-10042",
      "title": "Кроссовки беговые, мужские",
      "brand": "Lusio",
      "images": [
        {"size": "list", "url": "https://cdn.example/.../10042-320.webp"},
        {"size": "card", "url": "https://cdn.example/.../10042-1080.webp"}
      ],
      "price_hint": {"value": 8990.00, "currency": "RUB", "as_of": "2026-10-22T09:15:00Z"},
      "availability": "in_stock"
    }
  ],
  "next_cursor": "cD0yMDI3",
  "as_of": "2026-10-22T09:15:00Z"
}

За доверие к данным в этом ответе отвечают два поля. as_of — отметка времени, по которой приложение показывает покупателю свежесть данных. price_hint названо подсказкой намеренно: цена в списке нужна для показа, а сумма к оплате подтверждается сервером при добавлении в корзину и ещё раз при оформлении.

Пагинация: курсор вместо смещения

Постраничный доступ по смещению (?offset=2000&limit=20) на каталоге в десятки тысяч позиций даёт две проблемы. База данных отсчитывает и отбрасывает первые две тысячи строк, и чем дальше листает покупатель, тем медленнее ответ. Вторая заметнее: пока покупатель листает, товары добавляются и скрываются, нумерация сдвигается, и часть позиций он видит дважды, а часть не видит вообще. Курсорная пагинация передаёт метку последней отданной позиции, и следующий запрос продолжает список от неё — реализация есть в документации DRF.

Фильтры и поиск

Параметры фильтрации перечисляют явным списком разрешённых и сопоставляют с полями базы на стороне сервера. Проброс произвольных параметров запроса прямо в фильтр ORM (Object-Relational Mapping, слой доступа к базе через объекты) экономит день работы, а затем открывает доступ к служебным полям и позволяет одним запросом положить базу тяжёлой выборкой.

Текстовый поиск решают отдельной подсистемой, а не сравнением подстрок в базе: полнотекстовый поиск PostgreSQL для небольшого ассортимента, выделенный поисковый движок для крупного. Требования к ранжированию и обработке опечаток растут вместе с каталогом — что меняется в этой части, разобрано в материале AI-поиск в e-commerce.

Изображения и медиафайлы

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

Цены и остатки: отдельные контракты и правила актуальности

Цены и остатки выносят в отдельные контракты из-за частоты изменений: карточка товара живёт неделями, цена в акции меняется в течение дня, остаток — после каждой продажи в любом канале.

Пример распределения данных по источникам истины и способам передачи

Остаток на витрине и остаток в учёте

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

Цена, по которой оформляется заказ

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

Корзина и заказ: идемпотентность, резерв и статусы

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

Ключ идемпотентности при оформлении

Оформление заказа меняет состояние данных, и по стандарту HTTP (RFC 9110) метод POST не идемпотентен: два одинаковых запроса создают два заказа. На мобильной связи это происходит регулярно — ответ не дошёл, приложение повторило отправку. Приложение генерирует ключ запроса и передаёт его в заголовке, сервер запоминает связку «ключ — созданный заказ» и на повторе отдаёт тот же результат.

POST /api/v1/orders
Idempotency-Key: 8f14e45f-ceea-467a-9c1e-2b1a7d3f9001

{
  "cart_id": "c-7781",
  "delivery": {"type": "pickup", "point_id": "pvz-204"},
  "payment_method": "card_online",
  "client_total": 8990.00
}

201 Created
{"order_id": "A-250431", "server_total": 8990.00, "status": "created"}

# повтор того же запроса с тем же ключом
200 OK
{"order_id": "A-250431", "server_total": 8990.00, "status": "created"}

# расхождение суммы
409 Conflict
{"type": "/errors/price-changed", "title": "Цена изменилась", "status": 409,
 "code": "PRICE_CHANGED", "items": [{"sku": "SKU-10042", "was": 8990.00, "now": 9490.00}]}

Формат ошибки приводят к стандарту Problem Details for HTTP APIs (RFC 9457) и добавляют поле с собственным кодом. Приложение показывает покупателю текст по коду, а не разбирает сообщение на русском: текст правят редакторы, код остаётся стабильным.

Резерв товара в транзакции

Списание доступного количества — место состязания запросов: два покупателя одновременно забирают последнюю единицу. Защита даётся блокировкой строки на время транзакции (явные блокировки PostgreSQL, транзакции Django).

with transaction.atomic():
    stock = Stock.objects.select_for_update().get(sku=sku, warehouse=warehouse)
    if stock.available < qty:
        raise OutOfStock(sku=sku, available=stock.available)
    stock.available -= qty
    stock.save(update_fields=["available"])
    Reservation.objects.create(order=order, sku=sku, qty=qty, expires_at=deadline)

У резерва обязательно есть срок жизни и фоновая задача, которая возвращает товар в продажу по неоплаченным заказам. Без неё ассортимент постепенно «уходит в ноль» на витрине, оставаясь на складе.

Статусы заказа и переходы между ними

Статусы описывают конечным набором с явным перечнем разрешённых переходов: из «оформлен» заказ попадает в «подтверждён» или «отменён», но не в «выдан». Произвольная смена статуса через API закрыта — доступны только названные переходы, каждый со своими проверками прав и побочными действиями: уведомление покупателю, возврат резерва, запись в журнал обмена.

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

Оплата как отдельный ресурс

Заказ создаётся до оплаты и живёт отдельно от неё. Факт оплаты серверная часть узнаёт из уведомления платёжного сервиса, а не из возврата покупателя в приложение: тот закрывает приложение на экране банка, теряет связь, переключается на звонок. Уведомление проверяют по подписи, обрабатывают идемпотентно и только после этого двигают статус заказа. Как меняется этот сценарий, когда оплата уходит из экрана корзины, разобрано в материале Agentic Checkout: оплата внутри AI-агента.

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

Аутентификация и права доступа

Для мобильного приложения используют пару токенов: короткоживущий токен доступа и долгоживущий токен обновления, привязанный к устройству. Формат JWT (JSON Web Token, RFC 7519) удобен тем, что сервер проверяет подпись без обращения к базе, но отозвать такой токен до истечения срока нельзя. Поэтому срок жизни токена доступа держат коротким, а список отозванных токенов обновления — на стороне сервера.

Главная ошибка в правах доступа — проверка только на уровне списка. По адресу /orders покупатель корректно получает свои заказы, а по адресу /orders/A-250431 сервер отдаёт любой заказ, потому что проверка владельца здесь не написана. Подстановка чужого идентификатора — частый способ получить персональные данные другого покупателя; в DRF за это отвечают права на уровне объекта.

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

Ограничение частоты запросов ставят на вход, восстановление пароля и поиск: без него эти адреса используют для перебора. В ответах оставляют минимально необходимый набор полей о покупателе — это помогает учитывать требования 152-ФЗ о персональных данных и снижает цену утечки, если ключ интеграции окажется скомпрометирован.

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

Версию указывают в адресе (/api/v1/) или в заголовке запроса; DRF поддерживает оба подхода. Выбор между ними второстепенен, а вот правило изменений — нет: контракт расширяют, а не переписывают.

Какие изменения контракта безопасны для уже установленных приложений

Контракт фиксируют машиночитаемым описанием в формате OpenAPI — для Django его генерирует drf-spectacular. Это даёт две практические вещи: разработчики приложения получают актуальную документацию без переписки, а автоматические проверки при выпуске показывают несовместимое изменение до выхода на рабочие серверы. Принудительное обновление приложения через минимально поддерживаемую версию — крайняя мера: часть аудитории на этом шаге теряется.

Асинхронные задачи и обмен с учётной системой

Внутри запроса покупателя происходит только то, без чего нельзя отдать ответ. Всё остальное уходит в очередь задач — так витрина перестаёт зависеть от скорости внешних систем.

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

Требования к фоновым задачам

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

Три механизма обмена с 1С

Для обмена с «1С:Предприятие» используют HTTP-сервисы, опубликованные на стороне учётной системы, интерфейс OData для чтения справочников или пакетный обмен файлами через промежуточное хранилище. Выбор зависит от версии конфигурации, нагрузки и того, кто обслуживает учёт. Общее правило одно: серверная часть магазина не обращается к учётной системе в момент запроса покупателя — витрина отвечает из своих данных, а обмен идёт по расписанию и по событиям в фоновом режиме.

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

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

Типичные ошибки проектирования API

• Приложение считает сумму заказа. Правило акций дублируется в коде приложения и на сервере, расходится после первой же правки, и покупатель видит одну сумму, а платит другую.
• Один универсальный ответ на все экраны. Ответ растёт за счёт полей, нужных другим экранам, мобильный интернет этого не прощает, а любое изменение затрагивает все экраны сразу.
• Смещение вместо курсора в пагинации. При листании большого каталога покупатель получает дубли и пропуски, а база — тяжёлые запросы на дальних страницах.
• Проброс параметров запроса прямо в фильтр ORM. Открывает доступ к служебным полям и позволяет одним запросом перегрузить базу данных.
• Проверка прав только на уровне списка. Заказ, профиль или адрес другого покупателя оказываются доступны по прямому обращению к идентификатору.
• Синхронный вызов учётной системы в запросе покупателя. Регламентные работы в учёте останавливают продажи на витрине.
• Ломающее изменение контракта без новой версии. Установленные приложения перестают работать, и починить их можно только выпуском обновления и ожиданием, пока аудитория его установит.

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

Метрики и чек-лист перед стартом разработки

Метрики состояния API

Среднее время ответа скрывает проблемы, поэтому смотрят на 95-й процентиль — значение, которое не превышено в 95 запросах из 100. Остальные метрики привязывают к сценарию покупателя, а не к серверу.

Метрики серверной части, по которым видно состояние мобильной витрины

Эти же метрики снимают под нагрузкой до пика продаж, а не во время него — что именно воспроизводят в сценарии проверки, разобрано в материале нагрузочное тестирование приложения интернет-магазина перед распродажей.

Чек-лист проектирования

• Каталог, цены и остатки разведены по отдельным контрактам с собственной частотой обновления.
• Пагинация курсорная, набор параметров фильтрации перечислен явным списком, в ответах списков есть отметка времени.
• Сумма заказа и доступность товара подтверждаются сервером при оформлении.
• Оформление заказа принимает ключ идемпотентности, повтор не создаёт второй заказ.
• Резерв имеет срок жизни, фоновая задача возвращает неоплаченный товар в продажу.
• Переходы статусов перечислены, коды учётной системы в контракт приложения не попадают.
• Права проверяются на уровне объекта, а не только списка; на вход и поиск стоит ограничение частоты запросов.
• Версия контракта объявлена с первого релиза, ломающие изменения выходят только в новой версии.
• Описание контракта в формате OpenAPI лежит в репозитории и проверяется автоматически при выпуске.
• Обращений к учётной системе внутри запроса покупателя нет: обмен идёт через очередь задач.
• Журнал обмена и регулярная сверка остатков настроены до запуска, а не после первого расхождения.

Итог: контракты каталога и заказов на одной странице

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

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

Что делать дальше

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

Источники

• Django: транзакции базы данных и Django: кеширование, Django: оптимизация работы с базой.
• Django REST Framework: пагинация, версионирование, права доступа, ограничение частоты запросов.
• Celery: руководство по задачам.
• PostgreSQL: явные блокировки.
• RFC 9110: HTTP Semantics (идемпотентность методов), RFC 9457: Problem Details for HTTP APIs, RFC 7519: JSON Web Token.
• Спецификация OpenAPI и drf-spectacular.
• Механизмы обмена с «1С:Предприятие» (HTTP-сервисы, интерфейс OData, пакетный обмен файлами) — по официальной документации «1С:Предприятие».

Ссылки проверены 22 октября 2026 года. Разделы официальной документации обновляются вместе с версиями библиотек — перед внедрением стоит сверяться с версией, которая стоит в проекте.