---
metadata:
  - name: generator
    content: Diplodoc Platform v5.52.0
alternate:
  - https://yandex.kz/routing/doc/ru/oob/basics.md
  - href: ru/oob/basics.md
    type: text/markdown
    title: Markdown version
  - href: llms.txt
    type: text/markdown
    title: llms.txt
title: Яндекс Маршрутизация — экспресс-доставка — базовые концепции
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.kz/routing/doc/ru/llms.txt


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

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

## Домены

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

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

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

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

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

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

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

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

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

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

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

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

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

Подробнее о токене см. в разделе [Токен идемпотентности](https://yandex.kz/routing/doc/ru/oob/authorization.md#idempotency-token).


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

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

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

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

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

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

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

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

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

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

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

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

<!-- * частичное применение событий поддерживается через параметр `last_applied_update_by_fields`, который позволяет обновлять только указанные поля сущности. -->

<!-- source: ru/oob/_includes/feedback.md -->
<a href="feedback">
  <span class="button">Написать в службу поддержки</span>
</a>


<!-- endsource: ru/oob/_includes/feedback.md -->