Базовые концепции

В разделе описаны основные концепции, определяющие логику работы сервиса.

Домены

В API сервиса экспресс-доставки выделены следующие ключевые функциональные блоки:

• orders — управление заказами;

• couriers — управление курьерами и их рабочими сменами;

• routes — построение и управление маршрутами;

• refbook — предоставление справочной информации.

Идентификаторы

Сервис оперирует двумя типами идентификаторов:

• client_id — назначается клиентской системой. Позволяет связать сущности с внешними данными клиента.

• id — генерируется сервисом экспресс-доставки. Используется для однозначной идентификации сущностей.

Идемпотентность

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

1. Через уникальные комбинации клиентских идентификаторов (например, company_id + client_order_id).

2. Через заголовок X-Idempotency-Token — для событийных операций (позволяет однозначно идентифицировать запрос и избежать повторной обработки).

Подробнее о токене см. в разделе Токен идемпотентности.

Версионирование

Для управления изменениями и разрешения конфликтов при конкурентных обновлениях в сервисе реализован механизм версионирования:

• в запросе присутствует опциональное поле version;

• значение version должно быть больше предыдущей версии сущности.

Система отклонит запрос, если переданный version меньше или равен текущему.

Если version не указан, для разрешения конфликтов используется поле occurred_ts.

Событийная модель

Обновления сущностей реализуются с помощью событийной модели:

• каждое событие содержит поле occurred_ts — время события на стороне клиента;

• приоритет при обработке отдается событиям, у которых:

  • более поздний occurred_ts;

  • большее значение version, если поле version заполнено.