cargo.run-api-docs

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

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

• Запрос может выполняться как с 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 элементов.

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

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

1. deviceNumber + createdAt
2. cardNumber + createdAt
3. 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 помогает дедуплицировать данные из внешних систем.
• Координаты и адрес используются для сопоставления с плановыми точками заправки на маршруте.