Транзакции заправок¶

Метод загрузки транзакций с АЗС для формирования отчёта план‑факт по посещению АЗС и сопоставления с маршрутом.

Запрос может выполняться как с X-Api-Key, так и с JWT.
При запросе с X-Api-Key без JWT — доступ ко всем транзакциям.
При запросе с JWT — доступ ограничен текущей организацией; чужие трекеры отфильтровываются.

1. Создание транзакций¶

POST /api/refuelingTransactions/create
Content-Type: application/json

Тело запроса¶

{
  "transactions": [
    {
      "deviceNumber": "string",
      "cardNumber": "string",
      "externalId": "string",
      "createdAt": "2025-12-01T12:42",
      "volume": 1.0,
      "cost": 1.0,
      "description": "string",
      "address": "string",
      "x": 55.23123,
      "y": 69.42
    }
  ]
}

Обязательность и ограничения полей¶

Идентификатор: обязателен один из deviceNumber или cardNumber или externalId. Если не указан ни один — элемент пропускается и вернётся в errors.
Остальные обязательные поля: createdAt, volume, cost, address, x, y.
deviceNumber: max 128 символов.
cardNumber: max 128 символов.
externalId: max 512 символов.
createdAt: не ранее 2023 года, не позже текущее время + 6 часов (UTC).
address: max 1024 символа.
description: необязательное, max 2048 символов.
x (долгота): диапазон [-90, 90], точность до 6 знаков после запятой.
y (широта): диапазон [-180, 180], точность до 6 знаков после запятой.
transactions: максимум 4096 элементов.

Идемпотентность и ключи¶

Транзакция определяется одним из ключей (приоритет сверху вниз):

deviceNumber + createdAt
cardNumber + createdAt
externalId + createdAt
Если указаны все три — используется deviceNumber, остальные игнорируются.
При наличии записи с тем же ключом данные обновляются, а не дублируются.
Если внутри одного запроса есть несколько элементов с одинаковым ключом, применяется последний по порядку.
Обновление существующих транзакций возможно только для дат не старше четырёх месяцев; более поздние транзакции вернутся с ошибкой.
Если deviceNumber или cardNumber не существуют в системе, такие транзакции просто игнорируются (не попадут в errors).

2. Ответы сервера¶

201 — все транзакции сохранены; тело ответа пустое.
200 — часть транзакций не принята:

{
  "errors": [
    {
      "message": "Причина, почему не создалась транзакция",
      "transaction": { }
    }
  ]
}

400 или 500 — текстовая ошибка; ни одна транзакция не сохранена.
401 — не указан X-Api-Key и отсутствует валидный токен.
403 (если нет X-Api-Key) — недостаточно прав/нет нужной роли у пользователя.

3. Назначение и сценарии¶

Загрузка транзакций с АЗС для отчёта план‑факт по маршруту.
Поля deviceNumber/cardNumber позволяют связать транзакцию с трекером и топливной картой; externalId помогает дедуплицировать данные из внешних систем.
Координаты и адрес используются для сопоставления с плановыми точками заправки на маршруте.