{
  "openapi":"3.0.3",
  "info":{
    "title":"CARGO.RUN API клиентского кабинета",
    "version":"1.1.0",
    "description":"API для интеграции учетных и транспортных систем клиента. Все данные и команды автоматически ограничены компанией API-доступа. Изменения требуют отдельных write-scopes, UUID Idempotency-Key и, кроме создания водителя, сильного If-Match из заголовка ETag. Команды поставщика могут быть асинхронными: ответ 202 содержит operationId, а итог читается через /v1/operations. Настройки администратора имеют приоритет. Цены АЗС — только итоговые клиентские цены; внутренние поставщики, закупочные цены, формулы тарифов, сырые ответы и PIN-коды не раскрываются. Время передается в ISO 8601 UTC."
  },
  "servers":[{"url":"/","description":"Текущий сервер"}],
  "tags":[
    {"name":"Авторизация"},{"name":"Компания"},{"name":"Карты"},{"name":"Водители"},
    {"name":"Транзакции"},{"name":"Баланс"},{"name":"АЗС"},{"name":"Документы"},{"name":"Счета"},{"name":"Операции"}
  ],
  "paths":{
    "/oauth/token":{"post":{"tags":["Авторизация"],"summary":"Получить access token","description":"OAuth 2.0 Client Credentials. Передайте client_id и client_secret через HTTP Basic либо поля формы. Токен действует 15 минут.","security":[],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["grant_type"],"properties":{"grant_type":{"type":"string","enum":["client_credentials"]},"client_id":{"type":"string"},"client_secret":{"type":"string","format":"password"},"scope":{"type":"string","description":"Необязательный список запрошенных scopes через пробел"}}}}}},"responses":{"200":{"description":"Токен выдан","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Token"}}}},"400":{"$ref":"#/components/responses/OAuthError"},"401":{"$ref":"#/components/responses/OAuthError"},"429":{"$ref":"#/components/responses/OAuthError"}}}},
    "/v1/me":{"get":{"tags":["Авторизация"],"summary":"Текущий API-доступ","responses":{"200":{"description":"Контекст доступа","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientContext"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},
    "/v1/capabilities":{"get":{"tags":["Авторизация"],"summary":"Доступные scopes и возможности карт","responses":{"200":{"description":"Возможности","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Capabilities"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},
    "/v1/company":{"get":{"tags":["Компания"],"summary":"Реквизиты компании","security":[{"clientCredentials":["company.read"]}],"responses":{"200":{"description":"Компания","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},
    "/v1/cards":{"get":{"tags":["Карты"],"summary":"Список топливных карт","security":[{"clientCredentials":["cards.read"]}],"parameters":[{"$ref":"#/components/parameters/Search"},{"name":"cardType","in":"query","schema":{"type":"string","enum":["physical","virtual"]}},{"name":"status","in":"query","schema":{"type":"string"}},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"responses":{"200":{"description":"Страница карт","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardsPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},
    "/v1/cards/{id}":{"get":{"tags":["Карты"],"summary":"Карточка топливной карты","security":[{"clientCredentials":["cards.read"]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Карта","headers":{"ETag":{"description":"Версия карты для If-Match","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Card"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/RateLimited"}}}},
    "/v1/cards/{id}/controls":{"get":{"tags":["Карты"],"summary":"Лимиты и доступные возможности карты","security":[{"clientCredentials":["cards.read"]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Настройки карты","headers":{"ETag":{"description":"Версия настроек для If-Match","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardControl"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/RateLimited"}}}},
    "/v1/cards/{id}/controls/limits":{"post":{"tags":["Карты"],"summary":"Создать лимит","description":"Доступные unitType, durationType, services и ограничения берите из capabilities карты.","security":[{"clientCredentials":["cards.controls.write"]}],"parameters":[{"$ref":"#/components/parameters/Id"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/IfMatch"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LimitDefinitionWrite"}}}},"responses":{"202":{"$ref":"#/components/responses/AcceptedOperation"},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Conflict"},"412":{"$ref":"#/components/responses/PreconditionFailed"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"428":{"$ref":"#/components/responses/PreconditionRequired"},"429":{"$ref":"#/components/responses/RateLimited"}}}},
    "/v1/cards/{id}/controls/limits/{limitKey}":{"patch":{"tags":["Карты"],"summary":"Изменить величину лимита","security":[{"clientCredentials":["cards.controls.write"]}],"parameters":[{"$ref":"#/components/parameters/Id"},{"$ref":"#/components/parameters/LimitKey"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/IfMatch"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LimitValueWrite"}}}},"responses":{"202":{"$ref":"#/components/responses/AcceptedOperation"},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Conflict"},"412":{"$ref":"#/components/responses/PreconditionFailed"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"428":{"$ref":"#/components/responses/PreconditionRequired"},"429":{"$ref":"#/components/responses/RateLimited"}}},"put":{"tags":["Карты"],"summary":"Изменить определение лимита","security":[{"clientCredentials":["cards.controls.write"]}],"parameters":[{"$ref":"#/components/parameters/Id"},{"$ref":"#/components/parameters/LimitKey"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/IfMatch"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LimitDefinitionWrite"}}}},"responses":{"202":{"$ref":"#/components/responses/AcceptedOperation"},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Conflict"},"412":{"$ref":"#/components/responses/PreconditionFailed"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"428":{"$ref":"#/components/responses/PreconditionRequired"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"tags":["Карты"],"summary":"Удалить лимит","security":[{"clientCredentials":["cards.controls.write"]}],"parameters":[{"$ref":"#/components/parameters/Id"},{"$ref":"#/components/parameters/LimitKey"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/IfMatch"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LimitDeleteWrite"}}}},"responses":{"202":{"$ref":"#/components/responses/AcceptedOperation"},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Conflict"},"412":{"$ref":"#/components/responses/PreconditionFailed"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"428":{"$ref":"#/components/responses/PreconditionRequired"},"429":{"$ref":"#/components/responses/RateLimited"}}}},
    "/v1/cards/{id}/controls/block":{"put":{"tags":["Карты"],"summary":"Заблокировать или разблокировать карту","description":"Физическая карта блокируется нулевым лимитом и разблокируется восстановлением; виртуальная — изменением статуса. Конкретный канал в ответе не раскрывается.","security":[{"clientCredentials":["cards.controls.write"]}],"parameters":[{"$ref":"#/components/parameters/Id"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/IfMatch"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlockWrite"}}}},"responses":{"202":{"$ref":"#/components/responses/AcceptedOperation"},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Conflict"},"412":{"$ref":"#/components/responses/PreconditionFailed"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"428":{"$ref":"#/components/responses/PreconditionRequired"},"429":{"$ref":"#/components/responses/RateLimited"}}}},
    "/v1/cards/{id}/assignment":{"put":{"tags":["Карты"],"summary":"Назначить водителя и ТС","description":"null driverId снимает водителя; пустое vehicle снимает ТС. Локальное назначение возвращает 200 и ETag, внешняя команда — 202.","security":[{"clientCredentials":["cards.assignments.write"]}],"parameters":[{"$ref":"#/components/parameters/Id"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/IfMatch"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardAssignmentWrite"}}}},"responses":{"200":{"description":"Назначение сохранено","headers":{"ETag":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Card"}}}},"202":{"$ref":"#/components/responses/AcceptedOperation"},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Conflict"},"412":{"$ref":"#/components/responses/PreconditionFailed"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"428":{"$ref":"#/components/responses/PreconditionRequired"},"429":{"$ref":"#/components/responses/RateLimited"}}}},
    "/v1/drivers":{"get":{"tags":["Водители"],"summary":"Справочник водителей","security":[{"clientCredentials":["drivers.read"]}],"parameters":[{"$ref":"#/components/parameters/Search"},{"name":"status","in":"query","schema":{"type":"string"}},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"responses":{"200":{"description":"Страница водителей","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DriversPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Водители"],"summary":"Создать водителя","description":"If-Match не нужен. Локальное создание возвращает 201; передача в мобильное приложение может вернуть 202.","security":[{"clientCredentials":["drivers.write"]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DriverWrite"}}}},"responses":{"201":{"description":"Водитель создан","headers":{"Location":{"schema":{"type":"string"}},"ETag":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Driver"}}}},"202":{"$ref":"#/components/responses/AcceptedOperation"},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"}}}},
    "/v1/drivers/{id}":{"get":{"tags":["Водители"],"summary":"Карточка водителя","security":[{"clientCredentials":["drivers.read"]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Водитель","headers":{"ETag":{"description":"Версия водителя для If-Match","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Driver"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/RateLimited"}}},"put":{"tags":["Водители"],"summary":"Изменить или уволить водителя","description":"Для увольнения передайте status=dismissed. Физического удаления нет.","security":[{"clientCredentials":["drivers.write"]}],"parameters":[{"$ref":"#/components/parameters/Id"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/IfMatch"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DriverWrite"}}}},"responses":{"200":{"description":"Водитель изменён","headers":{"ETag":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Driver"}}}},"202":{"$ref":"#/components/responses/AcceptedOperation"},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Conflict"},"412":{"$ref":"#/components/responses/PreconditionFailed"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"428":{"$ref":"#/components/responses/PreconditionRequired"},"429":{"$ref":"#/components/responses/RateLimited"}}}},
    "/v1/mobile-app/organizations":{"get":{"tags":["Водители"],"summary":"Организации мобильного приложения","description":"Возвращает нейтральные UUID и названия доступных организаций без внутренних ID поставщика.","security":[{"clientCredentials":["drivers.read"]}],"responses":{"200":{"description":"Организации","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MobileOrganization"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},
    "/v1/transactions":{"get":{"tags":["Транзакции"],"summary":"Транзакции и итоговые клиентские суммы","security":[{"clientCredentials":["transactions.read"]}],"parameters":[{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}},{"name":"cardNumber","in":"query","schema":{"type":"string"}},{"name":"vehicle","in":"query","schema":{"type":"string"}},{"name":"driver","in":"query","schema":{"type":"string"}},{"name":"station","in":"query","schema":{"type":"string"}},{"name":"fuel","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"litresMin","in":"query","schema":{"type":"number"}},{"name":"litresMax","in":"query","schema":{"type":"number"}},{"name":"priceMin","in":"query","schema":{"type":"number"}},{"name":"priceMax","in":"query","schema":{"type":"number"}},{"name":"amountMin","in":"query","schema":{"type":"number"}},{"name":"amountMax","in":"query","schema":{"type":"number"}},{"name":"sort","in":"query","schema":{"type":"string","enum":["occurredAt","cardNumber","cardType","vehicle","driver","station","fuel","litres","price","amount","status"],"default":"occurredAt"}},{"name":"direction","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"responses":{"200":{"description":"Страница транзакций","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionsPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},
    "/v1/balance":{"get":{"tags":["Баланс"],"summary":"Единый баланс","security":[{"clientCredentials":["balance.read"]}],"responses":{"200":{"description":"Баланс","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Balance"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},
    "/v1/ledger":{"get":{"tags":["Баланс"],"summary":"Движения баланса","security":[{"clientCredentials":["balance.read"]}],"parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"responses":{"200":{"description":"Страница движений","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LedgerPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},
    "/v1/ledger/daily":{"get":{"tags":["Баланс"],"summary":"Поступления и списания по дням","security":[{"clientCredentials":["balance.read"]}],"parameters":[{"name":"from","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":true,"schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Итоги по дням","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DailyLedger"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},
    "/v1/ledger/days/{day}":{"get":{"tags":["Баланс"],"summary":"Детализация дня","security":[{"clientCredentials":["balance.read"]}],"parameters":[{"name":"day","in":"path","required":true,"schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Движения за день","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/LedgerEntry"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},
    "/v1/stations":{"get":{"tags":["АЗС"],"summary":"Доступные АЗС с итоговыми ценами","security":[{"clientCredentials":["stations.read"]}],"parameters":[{"$ref":"#/components/parameters/Search"},{"name":"cardFilter","in":"query","description":"physical, virtual, product:{name} или card:{uuid}","schema":{"type":"string"}},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"responses":{"200":{"description":"Страница АЗС","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StationsPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},
    "/v1/stations/{id}":{"get":{"tags":["АЗС"],"summary":"АЗС, услуги и итоговые цены","security":[{"clientCredentials":["stations.read"]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"АЗС","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Station"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/RateLimited"}}}},
    "/v1/documents":{"get":{"tags":["Документы"],"summary":"Опубликованные документы","security":[{"clientCredentials":["documents.read"]}],"parameters":[{"$ref":"#/components/parameters/Search"},{"name":"category","in":"query","schema":{"type":"string","enum":["bulletin","offer","pricing","other"]}},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"responses":{"200":{"description":"Документы","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentsPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},
    "/v1/documents/{id}/file":{"get":{"tags":["Документы"],"summary":"Скачать документ","security":[{"clientCredentials":["documents.read"]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Файл","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}},"application/vnd.openxmlformats-officedocument.wordprocessingml.document":{"schema":{"type":"string","format":"binary"}},"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/RateLimited"}}}},
    "/v1/invoices":{"get":{"tags":["Счета"],"summary":"Список счетов","security":[{"clientCredentials":["invoices.read"]}],"parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"responses":{"200":{"description":"Страница счетов","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoicesPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},
    "/v1/invoices/{id}/file":{"get":{"tags":["Счета"],"summary":"Скачать PDF счета","security":[{"clientCredentials":["invoices.read"]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"PDF","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/RateLimited"}}}},
    "/v1/operations":{"get":{"tags":["Операции"],"summary":"Статусы команд по картам","security":[{"clientCredentials":["operations.read"]}],"parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"responses":{"200":{"description":"Страница операций","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationsPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},
    "/v1/operations/{id}":{"get":{"tags":["Операции"],"summary":"Статус команды","security":[{"clientCredentials":["operations.read"]}],"parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Операция","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Operation"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/RateLimited"}}}}
  },
  "components":{
    "securitySchemes":{"clientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"company.read":"Реквизиты компании","cards.read":"Карты и лимиты","drivers.read":"Водители","transactions.read":"Транзакции","balance.read":"Баланс и движения","stations.read":"АЗС и итоговые цены","documents.read":"Документы","invoices.read":"Счета","operations.read":"Статусы операций","cards.controls.write":"Изменение лимитов и блокировки карт","cards.assignments.write":"Назначение водителя и ТС на карту","drivers.write":"Создание и изменение водителей"}}}}},
    "parameters":{
      "Id":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},
      "Search":{"name":"search","in":"query","schema":{"type":"string","maxLength":200}},
      "Page":{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},
      "PageSize":{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},
      "LimitKey":{"name":"limitKey","in":"path","required":true,"description":"Нейтральный UUID лимита из GET /v1/cards/{id}/controls. Идентификатор поставщика не раскрывается.","schema":{"type":"string","format":"uuid"}},
      "IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"description":"Непустой UUID. Повтор того же запроса с тем же ключом возвращает прежний результат; другое тело — 409.","schema":{"type":"string","format":"uuid"}},
      "IfMatch":{"name":"If-Match","in":"header","required":true,"description":"Сильный ETag ресурса, например \"v12\". Отсутствует — 428; устарел — 412.","schema":{"type":"string","pattern":"^\\\"v[0-9]+\\\"$"}}
    },
    "responses":{
      "Problem":{"description":"Ошибка","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},
      "Unauthorized":{"description":"Токен отсутствует, истек, отозван или заменен","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},
      "Forbidden":{"description":"Scope или IP-адрес не разрешен","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},
      "RateLimited":{"description":"Превышен лимит запросов","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},
      "AcceptedOperation":{"description":"Команда принята в асинхронную очередь","headers":{"Location":{"description":"Адрес статуса операции","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationAccepted"}}}},
      "Conflict":{"description":"Конфликт idempotency, незавершенная операция или приоритет администратора","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},
      "PreconditionFailed":{"description":"If-Match устарел","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},
      "PreconditionRequired":{"description":"Требуется If-Match","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},
      "UnprocessableEntity":{"description":"Карта или её канал не поддерживают запрошенную возможность","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},
      "OAuthError":{"description":"Ошибка OAuth 2.0","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"error_description":{"type":"string"}}}}}}
    },
    "schemas":{
      "Token":{"type":"object","required":["access_token","token_type","expires_in","scope"],"properties":{"access_token":{"type":"string"},"token_type":{"type":"string","enum":["Bearer"]},"expires_in":{"type":"integer"},"scope":{"type":"string"}}},
      "Problem":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"traceId":{"type":"string"}}},
      "PageMeta":{"type":"object","required":["total","page","pageSize"],"properties":{"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"}}},
      "ClientContext":{"type":"object","required":["id","name","company","scopes"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"company":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"scopes":{"type":"array","items":{"type":"string"}},"expiresAt":{"type":"string","format":"date-time","nullable":true}}},
      "Capability":{"type":"object","properties":{"scope":{"type":"string"},"description":{"type":"string"}}},
      "Capabilities":{"type":"object","properties":{"granted":{"type":"array","items":{"$ref":"#/components/schemas/Capability"}},"cardControls":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}},
      "Company":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"fullName":{"type":"string"},"inn":{"type":"string"},"kpp":{"type":"string"},"address":{"type":"string"},"actualAddress":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"contactName":{"type":"string"},"contractNumber":{"type":"string"},"contractDate":{"type":"string","format":"date","nullable":true},"version":{"type":"integer","format":"int64"}}},
      "Balance":{"type":"object","properties":{"available":{"type":"number"},"credit":{"type":"number"},"updatedAt":{"type":"string","format":"date-time"}}},
      "Limit":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"number"},"used":{"type":"number"},"unit":{"type":"string"},"durationType":{"type":"integer"},"durationValue":{"type":"integer"}}},
      "Card":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"number":{"type":"string"},"label":{"type":"string"},"driver":{"type":"string"},"vehicle":{"type":"string"},"department":{"type":"string"},"status":{"type":"string"},"dailyLimit":{"type":"number","nullable":true},"spent":{"type":"number","nullable":true},"version":{"type":"integer","format":"int64"},"updatedAt":{"type":"string","format":"date-time"},"pendingOperationStatus":{"type":"string","nullable":true},"cardType":{"type":"string","enum":["physical","virtual"]},"productName":{"type":"string"},"limits":{"type":"array","items":{"$ref":"#/components/schemas/Limit"}},"driverId":{"type":"string","format":"uuid","nullable":true}}},
      "CardsPage":{"allOf":[{"$ref":"#/components/schemas/PageMeta"},{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Card"}}}}]},
      "CardLimitControl":{"type":"object","properties":{"key":{"type":"string","format":"uuid","description":"Стабильный публичный UUID лимита; не является ID поставщика."},"name":{"type":"string"},"value":{"type":"number"},"used":{"type":"number"},"unit":{"type":"string"},"unitType":{"type":"integer"},"durationType":{"type":"integer"},"durationValue":{"type":"integer"},"editable":{"type":"boolean"},"usageKnown":{"type":"boolean"},"services":{"type":"array","items":{"type":"integer"}},"serviceGroups":{"type":"array","items":{"type":"string"}}}},
      "LimitOption":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"group":{"type":"string","nullable":true},"measure":{"type":"string","nullable":true},"isGroup":{"type":"boolean"}}},
      "ControlCapabilities":{"type":"object","properties":{"canCreateLimit":{"type":"boolean"},"canDeleteLimit":{"type":"boolean"},"canEditValue":{"type":"boolean"},"canEditUnit":{"type":"boolean"},"canEditDuration":{"type":"boolean"},"canEditDurationValue":{"type":"boolean"},"canEditServices":{"type":"boolean"},"minServices":{"type":"integer"},"maxServices":{"type":"integer"},"maxLimits":{"type":"integer"},"minValue":{"type":"number"},"maxValue":{"type":"number"},"units":{"type":"array","items":{"$ref":"#/components/schemas/LimitOption"}},"durations":{"type":"array","items":{"$ref":"#/components/schemas/LimitOption"}},"services":{"type":"array","items":{"$ref":"#/components/schemas/LimitOption"}},"note":{"type":"string"}}},
      "CardControl":{"type":"object","properties":{"cardId":{"type":"string","format":"uuid"},"cardNumber":{"type":"string"},"cardType":{"type":"string"},"status":{"type":"string"},"blocked":{"type":"boolean"},"clientControlsEnabled":{"type":"boolean"},"version":{"type":"integer","format":"int64"},"syncStatus":{"type":"string"},"message":{"type":"string"},"checkedAt":{"type":"string","format":"date-time","nullable":true},"pendingStatus":{"type":"string","nullable":true},"limits":{"type":"array","items":{"$ref":"#/components/schemas/CardLimitControl"}},"capabilities":{"$ref":"#/components/schemas/ControlCapabilities"}}},
      "DriverCard":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"number":{"type":"string"},"cardType":{"type":"string"},"productName":{"type":"string"},"vehicle":{"type":"string"}}},
      "Driver":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fullName":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"driverLicense":{"type":"string"},"status":{"type":"string"},"version":{"type":"integer","format":"int64"},"cardCount":{"type":"integer"},"syncStatus":{"type":"string"},"syncMessage":{"type":"string"},"lastSyncedAt":{"type":"string","format":"date-time","nullable":true},"mobileAppStatus":{"type":"string"},"mobileOrganizationId":{"type":"string","format":"uuid","nullable":true},"cards":{"type":"array","items":{"$ref":"#/components/schemas/DriverCard"}}}},
      "DriversPage":{"allOf":[{"$ref":"#/components/schemas/PageMeta"},{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Driver"}}}}]},
      "Transaction":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"cardNumber":{"type":"string"},"vehicle":{"type":"string"},"station":{"type":"string"},"fuel":{"type":"string"},"litres":{"type":"number"},"price":{"type":"number","nullable":true},"amount":{"type":"number","nullable":true},"occurredAt":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string"},"driver":{"type":"string"},"cardType":{"type":"string"},"currency":{"type":"string"},"pricingPending":{"type":"boolean"}}},
      "TransactionsPage":{"allOf":[{"$ref":"#/components/schemas/PageMeta"},{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}}}}]},
      "LedgerEntry":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string"},"description":{"type":"string"},"amount":{"type":"number"},"occurredAt":{"type":"string","format":"date-time"}}},
      "LedgerPage":{"allOf":[{"$ref":"#/components/schemas/PageMeta"},{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/LedgerEntry"}}}}]},
      "DailyLedger":{"type":"object","properties":{"day":{"type":"string","format":"date"},"incoming":{"type":"number"},"outgoing":{"type":"number"},"count":{"type":"integer"}}},
      "StationPrice":{"type":"object","properties":{"fuel":{"type":"string"},"cardType":{"type":"string"},"productName":{"type":"string"},"price":{"type":"number","nullable":true},"currency":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"},"availability":{"type":"string","enum":["available","unavailable","temporarily_unavailable"]}}},
      "Station":{"type":"object","description":"Цены являются итоговыми ценами клиента. Поля поставщика, закупочной цены и формулы тарифа отсутствуют.","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"brand":{"type":"string"},"address":{"type":"string"},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true},"updatedAt":{"type":"string","format":"date-time"},"cardTypes":{"type":"array","items":{"type":"string"}},"services":{"type":"array","items":{"type":"string"}},"prices":{"type":"array","items":{"$ref":"#/components/schemas/StationPrice"}},"pricesCheckedAt":{"type":"string","format":"date-time","nullable":true}}},
      "StationsPage":{"allOf":[{"$ref":"#/components/schemas/PageMeta"},{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Station"}}}}]},
      "Document":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"seriesId":{"type":"string","format":"uuid"},"revision":{"type":"integer"},"title":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"fileName":{"type":"string"},"contentType":{"type":"string"},"fileSize":{"type":"integer","format":"int64"},"publishedAt":{"type":"string","format":"date-time","nullable":true},"effectiveFrom":{"type":"string","format":"date","nullable":true},"effectiveTo":{"type":"string","format":"date","nullable":true},"updatedAt":{"type":"string","format":"date-time"}}},
      "DocumentsPage":{"allOf":[{"$ref":"#/components/schemas/PageMeta"},{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Document"}}}}]},
      "Invoice":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"number":{"type":"string"},"amount":{"type":"number"},"buyerName":{"type":"string"},"buyerInn":{"type":"string"},"buyerKpp":{"type":"string"},"buyerAddress":{"type":"string"},"taxLabel":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"contractNumber":{"type":"string"},"contractDate":{"type":"string","format":"date","nullable":true},"paymentPurpose":{"type":"string"}}},
      "InvoicesPage":{"allOf":[{"$ref":"#/components/schemas/PageMeta"},{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"}}}}]},
      "MobileOrganization":{"type":"object","required":["id","name","default"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"default":{"type":"boolean"}}},
      "LimitValueWrite":{"type":"object","required":["value"],"properties":{"value":{"type":"number","minimum":0,"example":500}}},
      "LimitDefinitionWrite":{"type":"object","required":["value","unitType","durationType","durationValue"],"properties":{"value":{"type":"number","minimum":0,"example":500},"unitType":{"type":"integer","example":1},"durationType":{"type":"integer","example":1},"durationValue":{"type":"integer","minimum":1,"example":1},"services":{"type":"array","items":{"type":"integer"},"example":[10]},"serviceGroups":{"type":"array","items":{"type":"string"},"example":["fuel"]},"comment":{"type":"string","maxLength":500,"example":"Лимит для рабочей смены"}}},
      "LimitDeleteWrite":{"type":"object","properties":{"comment":{"type":"string","maxLength":500,"example":"Лимит больше не нужен"}}},
      "BlockWrite":{"type":"object","required":["blocked"],"properties":{"blocked":{"type":"boolean","example":true},"comment":{"type":"string","maxLength":500,"example":"Пауза по заявке диспетчера"}}},
      "CardAssignmentWrite":{"type":"object","properties":{"driverId":{"type":"string","format":"uuid","nullable":true,"example":"00000000-0000-4000-8000-000000000001"},"vehicle":{"type":"string","maxLength":100,"example":"Аб234АА123"}}},
      "DriverWrite":{"type":"object","required":["fullName","phone","email","driverLicense","status"],"properties":{"fullName":{"type":"string","maxLength":200,"example":"Иванов Иван Иванович"},"phone":{"type":"string","maxLength":40,"example":"+79990000000"},"email":{"type":"string","format":"email","maxLength":200,"example":"driver@example.com"},"driverLicense":{"type":"string","maxLength":100,"example":"9911 123456"},"status":{"type":"string","enum":["active","dismissed"],"example":"active"},"mobileOrganizationId":{"type":"string","format":"uuid","nullable":true,"example":"00000000-0000-4000-8000-000000000003"}}},
      "OperationAccepted":{"type":"object","required":["operationId","status","location"],"properties":{"operationId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued"]},"location":{"type":"string","example":"/v1/operations/00000000-0000-4000-8000-000000000002"}}},
      "Operation":{"type":"object","description":"Нейтральная операция без имён и идентификаторов внутреннего поставщика.","required":["id","type","resourceType","resourceId","status","message","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","example":"card.limit.update"},"resourceType":{"type":"string","enum":["card","driver"],"example":"card"},"resourceId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","processing","succeeded","failed","verification_required"]},"message":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},
      "OperationsPage":{"allOf":[{"$ref":"#/components/schemas/PageMeta"},{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Operation"}}}}]}
    }
  },
  "security":[{"clientCredentials":[]}]
}
