Создание заказа

CarSharing создаёт заказ на выездную заправку конкретного автомобиля.

POST /v1/providers/orders Authorization: Bearer <ваш-токен>

Тело запроса

Поле	Тип	Обяз.	Описание
`external_id`	string	да	Идентификатор заказа в вашей системе. Используется для идемпотентности — повторный запрос с тем же `external_id` не создаст дубль, а вернёт уже созданный заказ.
`car_number`	string	да	Госномер автомобиля.
`car_id`	string	нет	Ваш внутренний идентификатор машины (для сверки на вашей стороне).
`latitude`	number	да	Широта местоположения автомобиля.
`longitude`	number	да	Долгота местоположения автомобиля.
`fuel_type_code`	string	да	Код типа топлива — см. справочник кодов.
`urgent`	boolean	нет	Срочная заправка. По умолчанию `false`.
`antifreeze`	boolean	нет	Требуется долив незамерзающей жидкости. По умолчанию `false`.
`small_tank`	boolean	нет	Автомобиль с маленьким баком (напр. Smart). По умолчанию `false`.
`fuel_amount_liters`	string (число)	нет	Целевой объём заправки в литрах. Если не указан — заправщик заливает по потребности автомобиля, фактический объём фиксируется по факту.
`fuel_level_liters`	string (число)	нет	Текущий остаток топлива в баке, литры (`>= 0`). Используется вместо `fuel_amount_liters`, если вы не знаете целевой объём напрямую, а знаете текущее состояние бака.
`fuel_level_percent`	string (число)	нет	Текущий уровень заполнения бака, проценты (`0..=100`, не доля 0..1).
`tank_capacity_liters`	string (число)	нет	Ёмкость бака автомобиля, литры (`> 0` и `<= 300`). Можно прислать инлайн здесь либо один раз зарегистрировать за `car_number` заранее (см. регистрацию машины) — тогда повторять на каждом заказе не нужно.

Как считается целевой объём Если fuel_amount_liters не указан, но известно текущее состояние бака, Twin Turbo сам вычислит целевой объём: fuel_amount_liters = tank_capacity_liters − текущий остаток, где текущий остаток — это fuel_level_liters, если он прислан, иначе tank_capacity_liters × fuel_level_percent / 100 (нужны оба). Ёмкость бака берётся из инлайн-tank_capacity_liters, а если его нет — из значения, зарегистрированного заранее. Если данных всё равно недостаточно (например, известен только процент, а ёмкость бака нигде не задана) — fuel_amount_liters остаётся null, поведение как при полном отсутствии этих полей («залить по потребности»); присланные fuel_level_liters/fuel_level_percent при этом всё равно сохраняются и возвращаются в ответе. Если fuel_amount_liters указан явно — он используется как есть, поля состояния бака на расчёт не влияют.

Пример запроса

{
  "external_id": "cs-order-58213",
  "car_number": "O518XP199",
  "car_id": "smart-4471",
  "latitude": 55.740151,
  "longitude": 37.419008,
  "fuel_type_code": "AI_92",
  "urgent": true,
  "antifreeze": false,
  "small_tank": false,
  "fuel_level_percent": "35",
  "tank_capacity_liters": "55"
}

В этом примере целевой объём не указан явно — Twin Turbo посчитает его сам: 55 × (1 − 35/100) = 35.75 л.

Ответы

201 CreatedЗаказ создан — тело: OrderResponse.

200 OKПовторный запрос с тем же external_id — идемпотентный повтор, дубль не создаётся. Тело: OrderResponse уже существующего заказа.

400 Bad RequestНевалидные координаты / неизвестный fuel_type_code / некорректный fuel_amount_liters / некорректные поля состояния бака — см. справочник ошибок.

401 UnauthorizedТокен отсутствует или недействителен.

409 ConflictМашина с этим car_number снята вами с учёта через DELETE /v1/providers/cars/{car_number}. Код ошибки: car_removed_from_fleet.

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