Skip to main content

apisdkopti24

Асинхронный Python SDK для Opti24 API: корпоративного API топливных карт АЗС (ОПТИ 24)

Карты, договоры, транзакции, отчёты, лимиты и оплата по QR-коду: типизированно, безопасно для повторов и без ручной работы с сессией.

CI PyPI Python Документация License

Документация · Каталог методов · Учебные примеры · Сообщить об ошибке

Демо: вход через auth_user, данные договора через get_contract_data и АЗС с ценами топлива через get_azs_list_v2; значения демонстрационные

О SDK

apisdkopti24: клиентская библиотека для приложений и сервисов, которые работают с корпоративным договором топливных карт ОПТИ 24 через API. Она берёт на себя транспорт, сессию, выбор договора, повторы и разбор ответов, чтобы код приложения оставался на уровне предметных действий: «получить карты», «заблокировать карту», «заказать отчёт».

Что покрывает. 89 операций корпоративного API (спецификация 1.1.60) и QR API (1.0.4): авторизация и выбор договора, топливные и виртуальные карты, группы карт, продуктовые лимиты, региональные ограничения и ограничители обслуживания, договоры и документы, транзакции, отчёты, пользователи и приглашения, электронный кошелёк, справочники и АЗС, расчёт итоговой стоимости, выпуск мобильного профиля карты (МПК) и оплата по QR-коду.

Как устроен. Один асинхронный APIClient объединяет 16 доменных сервисов: client.cards, client.transactions, client.reports и другие. Параметры проверяются до отправки запроса, ответы превращаются в типизированные Pydantic-модели. Маршрут, HTTP-метод, тарификация, доступность на DEMO, класс timeout и допустимость повтора каждой операции хранятся в едином реестре, сверенном со спецификацией, а не разбросаны по коду.

Где работает. Корпоративный API доступен на DEMO и в рабочей среде, QR API: на своём тестовом стенде и в рабочей среде. DEMO общий для всех клиентов, не тарифицируется и поддерживает только часть методов: какие именно, указано в каталоге методов.

Чего SDK не делает. Роли, IP-ограничения, квоты, тарифы и видимость объектов проверяет сервер. SDK не пытается их обойти, а превращает отказ в понятное исключение с очищенным текстом ответа.

Возможности

Предметные методы вместо HTTP

При первом вызове SDK сам открывает сессию и подставляет договор, а параметры проверяет до отправки запроса. Ответ приходит Pydantic-моделью: поля подсказывает IDE, ошибки типов находит mypy.

cards = await client.cards.get_cards_v2(onpage=20)
for card in cards.result:
    print(card.number, card.status)

Сбой сети не превращается в дубль операции

  • Автоматически повторяются только операции, которые каталог помечает безопасными. Перевод средств или блокировка карты после неясного сбоя не повторяются. Число попыток и паузы задаёт RetryPolicy (как настроить).
  • На каждую операцию действует общий срок и лимит попыток; повторы, вход и повторная авторизация их не обнуляют, а срок ограничивает и чтение тела ответа.
  • Ответ 401 вызывает одну повторную авторизацию на все параллельные запросы, а 409 превращается в DuplicateConflictError, а не в успех.
  • Лимит частоты включён по умолчанию: 1 запрос/с. Спецификация заявляет 2 запроса/с на DEMO и 5 в рабочей среде, но сервер отвечает 509 уже при 2 запросах/с; более высокую частоту по условиям договора задайте через API_REQUESTS_PER_SECOND (как настроить).

Подробнее: в разделе «Ошибки».

Журналы без секретов

По умолчанию SDK ничего не пишет. Если включить аудит, на каждую операцию приходится ровно одно JSONL-событие с кодом результата, числом попыток и временем выполнения. API key, пароли, идентификаторы карт и договоров и тела ответов в журнал не попадают, а текст исключений короткий и очищенный. Подробнее: в разделе «Журналирование и аудит».

Отчёты и оплата по QR-коду

  • download_report_file_to() пишет отчёт в файл потоком и заменяет файл атомарно: большой отчёт не держится в памяти, а недописанный файл не появится.
  • Ответы, которые читаются в память, ограничены по размеру; пределы задаются переменными API_MAX_JSON_RESPONSE_BYTES, API_MAX_IN_MEMORY_RESPONSE_BYTES и API_MAX_ERROR_RESPONSE_BYTES или полями max_json_response_bytes, max_in_memory_response_bytes и max_error_response_bytes в ConnectionSettings.
  • Мобильный профиль карты выпускается с подтверждением по SMS (init_mpc → confirm_mpc), а платёжная строка для QR приходит со сроком действия end_date и счётчиками tries и transaction_count от сервера. Подробнее: в описании QR-платежей.

Установка

pip install apisdkopti24==0.0.10

или с uv:

uv add apisdkopti24==0.0.10

Проект в разработке, поэтому закрепляйте проверенную версию явно. Изменения между версиями, включая несовместимые, перечислены в CHANGELOG, правила — в политике совместимости.

Быстрый старт

Создайте рядом со скриптом файл .env и не добавляйте его в Git. Параметры DEMO-стенда приведены в спецификации API.

API_BASE_URL=https://api.example.ru/vip/
API_KEY=your_api_key
API_LOGIN=your_login
API_PASSWORD=your_password
import asyncio
from pathlib import Path

from apisdkopti24 import (
    APIClient,
    ConnectionSettings,
    ContractSelectionError,
    EnvironmentCredentialsProvider,
)


async def main() -> None:
    env_file = Path(__file__).with_name(".env")
    settings = ConnectionSettings.from_env(env_file=env_file)
    credentials = EnvironmentCredentialsProvider.from_env(env_file=env_file)

    async with APIClient(settings=settings, credentials_provider=credentials) as client:
        try:
            await client.auth.auth_user()
        except ContractSelectionError as exc:
            # Несколько договоров: SDK не выбирает первый без подтверждения.
            for contract_id, contract_number in exc.available_contracts:
                print(contract_id, contract_number)
            await client.auth.auth_user(contract_id=input("ID договора: ").strip())

        try:
            cards = await client.cards.get_cards_v2(page=1, onpage=5)
            print("Карт найдено:", cards.total_count)
        finally:
            await client.auth.logoff()


if __name__ == "__main__":
    asyncio.run(main())

Создавайте один APIClient на всё время жизни приложения, а не на каждый запрос. Лимит частоты действует внутри одного клиента: если несколько процессов работают с одним ключом API, разделите лимит между ними (как настроить). Каждый вызов метода API тарифицируется, если в каталоге методов не указано обратное; повторы и повторная авторизация тоже расходуют запросы. Подробнее: в разделе «Начало работы».

Что важно по спецификации

  • Договор выбирается явно: большинство методов используют договор сессии; переданный contract_id имеет приоритет.
  • QR-платёж: отдельный контур API. generate_payment_qr возвращает строку BER-TLV, а не изображение QR; срок действия нужно проверять по end_date перед показом. Корпоративный DEMO не проверяет QR-методы.
  • Суммы переводов и счетов (move_to_card, move_to_contract, order_invoice) SDK передаёт строкой из Decimal, без округления; суммы лимитов: числом, как в спецификации. Состав запроса может отличаться от привычного REST: например, update_template использует POST с _method=PUT.
  • Тарификация и повторы заданы для каждой операции отдельно. Не выводите их из HTTP-метода: SDK автоматически повторяет только операции, которые каталог помечает безопасными, и не повторяет изменение данных после неясного сбоя.

Подробности и ограничения: в описании QR-платежей, сопоставлении со спецификацией и каталоге операций.

Ошибки

SDK проверяет и HTTP-статус, и status.code в теле ответа: успешный код в теле не скроет неуспешный HTTP-ответ, и наоборот. Ошибки API наследуют APIError:

Код Исключение Что делает SDK Что делать приложению
400 ValidationError Не повторяет Исправить параметры запроса
401 NotAuthenticatedError Один раз переавторизуется и повторяет запрос Проверить credentials, если ошибка осталась
403 AccessDeniedError Не переавторизуется Проверить роль, API key, IP, квоту и договор; читать текст сообщения
404 NotFoundError Не повторяет Проверить идентификатор объекта
409 DuplicateConflictError Не повторяет Считать признаком дубля, а не успехом
429, 509 RateLimitError Повторяет только бесплатное чтение Снизить частоту: без 509 устойчиво около 1 запроса/с
5xx ServerError Не повторяет; вход (auth_user) — один раз Повторить чтение позже; изменение повторять только после проверки состояния чтением. 502/503/504 на изменение приходят с context.reason="outcome_unknown": оно могло выполниться
Распознанные ответы сервера и локальные ошибки

Некоторые ответы API приходят с кодом, который не называет причину. SDK узнаёт их по тексту сообщения сервера и поднимает подкласс, поэтому существующие except продолжают работать:

Ответ API Исключение Родитель
403 с «[Код ошибки: NN]» (отказ процессинга) ProcessingRefusalError, код в processing_code AccessDeniedError
403 «требуется оплатить API VIP» PlanNotPaidError AccessDeniedError
403 «Не найден контракт, карта или группа» ObjectNotAccessibleError AccessDeniedError
403 «логин пользователя уже существует» DuplicateLoginError AccessDeniedError и DuplicateConflictError
403 с HTML-страницей WAF WafBlockedError AccessDeniedError
500 «Приглашение не готово к отправке» InviteNotReadyError, context.transient=False ServerError
500 «Отчет не будет сформирован» ReportFailedError, context.transient=False ServerError
500 «технические проблемы» в move_to_card ServerError, context.transient=False —

У распознанного ответа есть стабильный код context.reason (processing_refused, plan_not_paid, object_not_accessible, duplicate_login, invite_not_ready, report_failed, transfer_failed, group_removal_unknown, region_limit_point_id, contract_data_missing, outcome_unknown, waf_blocked); он же пишется в аудит как error_reason. Если оператор изменит текст, придёт исходный класс по коду, а context.reason будет None.

Локальные сбои не выдают себя за ответ сервера и не наследуют APIError: OperationTimeoutError и RetryBudgetExceededError (исчерпан общий бюджет времени или попыток), RequestValidationError (параметр не прошёл проверку до отправки: формат даты, пустой идентификатор, строка вместо списка, сумма), ResponseValidationError (ответ не совпал с моделью), ContractSelectionError (нужно выбрать договор), PaginationLimitError (итератор с strict=True дошёл до max_pages раньше total_count), ReportWaitTimeoutError (reports.wait_for_report не дождался отчёта за timeout), APIConnectionError (сервер недоступен), APIResponseTimeoutError и APINetworkError (сервер не ответил; изменение могло выполниться: проверьте состояние чтением).

Все исключения SDK, и серверные, и локальные, наследуют Opti24Error: один except Opti24Error отделяет ошибки SDK от остальных исключений приложения (обработка ошибок).

from apisdkopti24 import AccessDeniedError, APIError, OperationTimeoutError

try:
    cards = await client.cards.get_cards_v2(page=1, onpage=20)
except AccessDeniedError as exc:
    # Причина отказа часто есть только в тексте сообщения сервера.
    print("Доступ запрещён:", exc.server_messages)
except APIError as exc:
    print("Ошибка API:", exc.http_status_code, exc.api_status_code)
except OperationTimeoutError:
    # Сервер мог получить запрос: это не доказательство, что операция не выполнена.
    print("Истёк общий deadline операции")

str(exc) даёт короткую однострочную строку: email, телефоны, пары ключ=значение и упоминания PIN или паролей из неё вырезаются. Полный ответ сервера доступен только явно через exc.get_raw_payload(); не журналируйте его.

Журналирование и аудит

По умолчанию SDK ничего не пишет на диск и не выводит в консоль. Чтобы видеть сообщения, подключите обработчик к логгеру apisdkopti24:

import logging

logging.getLogger("apisdkopti24").addHandler(logging.StreamHandler())
logging.getLogger("apisdkopti24").setLevel(logging.INFO)

Файлы журнала включаются явно: в .env или в ConnectionSettings (logger_file, request_log_file):

LOGGER_FILE=logs/sdk.log
REQUEST_LOG_FILE=logs/audit.jsonl

REQUEST_LOG_FILE хранит JSONL-аудит: на каждую операцию приходится ровно одно итоговое событие completed, failed или cancelled. Пример события (сокращено, значения условные):

{"event": "failed", "operation": "get_cards_v2", "operation_id": "kfpc…", "sdk_error_code": "api_access_denied", "http_status_code": 403, "api_status_code": 403, "attempts_used": 1, "elapsed_ms": 184, "transient": false, "retry_allowed": false}
  • operation_id: случайный локальный идентификатор, связывающий события одной операции;
  • sdk_error_code: стабильный символьный код; у локального timeout это operation_timeout, а HTTP-код остаётся null, а не придумывается;
  • retry_allowed уже учитывает идемпотентность метода: решайте о повторе по нему, а не по transient.
  • billable: тарифицируется ли маршрут по каталогу операций (null, если каталог его не знает);
  • correlation_id: идентификатор шага приложения, например ИИ-агента, из correlation_scope. Поле есть, только если блок задан, и пишется как есть: передавайте технический ID, а не персональные данные.

В журналы и аудит не попадают API key, пароли, session ID, телефоны, email, идентификаторы карт и договоров, PIN, данные МПК, URL с идентификаторами, тела запросов и ответов, а также текст сообщений сервера. Ожидаемые отказы (4xx, лимит частоты, локальная валидация) пишутся с уровнем WARNING, серверные и сетевые сбои: ERROR, отмена задачи: INFO.

Полный список полей и кодов: в разделе «Ошибки и retry», настройка журналов: в «Конфигурации».

Методы по задачам

В SDK 89 операций в 16 сервисах. Ниже: карта методов; ссылки ведут к полным описаниям параметров, тарификации и примерам.

Задача Сервисы и примеры методов
Доступ и пользователи auth: auth_user, logoff; users: get_users, create_user, attach_card; invites: create_invite, resend_invite
Топливные карты cards: get_cards_v2, block_card, reset_pin; card_groups: get_card_groups, set_card_group
Договоры и расчёты contracts: get_contract_data, get_payments, order_invoice; ewallet: move_to_card, set_card_product; final_prices: get_final_prices, check_purchase
Лимиты и шаблоны карт templates: create_template, create_template_limit, ограничения; limits, region_limits, restrictions
Операции и отчётность transactions: get_transactions_v2, get_transaction_detail; reports: order_report, download_report_file
QR и справочники virtual_cards: init_mpc, generate_payment_qr, get_mpc_qr_list; dictionaries: get_dictionary, get_azs_list_v2

Как проходит запрос

Один вызов метода сервиса проходит через восемь шагов. Каждый отвечает за одну задачу и лежит в своём модуле.

Путь вызова client.cards.get_cards_v2. Шаг 1: сервис проверяет параметры моделью CardsV2Query (services/cards.py); 2: создаются общий срок, лимит попыток и событие аудита (executor.py); 3: при отсутствии сессии выполняется один authUser на все параллельные вызовы (session.py, authentication.py); 4: по OperationSpec собирается запрос GET v2/cards с заголовками api_key, session_id и contract_id (executor.py, endpoints.py); 5: запрос занимает один из слотов одновременных запросов, выдерживает интервал лимита частоты и списывает попытку из бюджета, а при 429, 509 или сбое сети повторяется, только если каталог это разрешает (resilience.py); 6: httpx отправляет запрос без редиректов с timeout, равным остатку срока операции (transport.py); 7: проверяются HTTP-статус и status.code, при 401 выполняется одна повторная авторизация и повтор (response.py, errors.py); 8: ответ разбирается в CardsV2Response и пишется итоговое событие аудита (models/cards.py, error_reporting.py)

Что важно на этом пути:

  • Повтор решает каталог операции, а не HTTP-метод. Пауза и повтор после 429, 509 или сбоя сети возможны только у операций, которые каталог помечает безопасными. Перевод средств или блокировка карты не повторяются.
  • Срок и попытки общие на всю операцию. Ожидание слота, повторы и повторная авторизация расходуют один бюджет, а не начинают отсчёт заново.
  • Сессия восстанавливается один раз. Если несколько запросов одновременно получили 401, повторная авторизация выполняется один раз для всех. Неудачный вход тоже один: ожидавшие запросы получают ту же ошибку, а следующий вызов пробует войти заново.

Структура репозитория

Структура репозитория: слева папки src/apisdkopti24 (код SDK), specifications (каталог операций и контракты API), examples (примеры вызовов), docs (сайт документации), scripts (генераторы и сверка контрактов), tests, tools/spec_contract (аудит спецификации), typecheck и .github/workflows; справа слои кода SDK сверху вниз: публичный фасад (client.py, service_groups.py, composition.py), сервисы и модели (services/, models/, service_base.py, validation.py), реестр операций (endpoints.py, request_metadata.py, registry.py, policies.py), выполнение операции (executor.py, session.py, authentication.py, execution_budget.py), транспорт (transport.py, resilience.py, response.py, downloads.py, file_io.py) и сквозные модули (errors.py, error_reporting.py, logger.py, sanitization.py, config.py, credentials.py)
Структура текстом
src/apisdkopti24/       SDK: клиент, сервисы, модели, транспорт и повторы
specifications/         каталог 89 операций и контракты API 1.1.60 / QR 1.0.4
examples/methods/       исполняемые примеры вызовов API
tests/                  модульные проверки и сверка контрактов
tools/spec_contract/    инструменты валидации спецификаций
scripts/                генерация и служебные задачи проекта
typecheck/              проверки типов публичного интерфейса
docs/                   руководство, справочник и разбор совместимости
.github/workflows/      CI и публикационные процессы

Каталог операций задаёт параметры запросов, тарификацию, идемпотентность и политику повтора; он служит источником метаданных SDK и связан с тестами контрактов. Подробнее: в обзоре архитектуры.

Практическое применение

Пульт топливных карт: дашборд по договору на этом SDK: баланс и расход, скидки и сервисный сбор, группы карт, транзакции, карта заправок по регионам, контроль подозрительных заправок и расход запросов API. Исходный код: в raspopovaa/apisdkopti24-dashboard. Опубликован статический прототип на данных DEMO и синтетике; сервер, обращающийся к API через SDK, в разработке.

  • Методы. Данные дают get_contract_data, get_payments, транзакционный отчёт (order_report, get_report_jobs, download_report_file_to) и при необходимости get_transactions_v2. Карты, группы, справочники, АЗС и статистика get_info: бесплатные методы.
  • Бюджет запросов. К API обращается сервер по расписанию, а не браузер, поэтому расход не зависит от числа зрителей. Договор раз в 2 часа (372), суточный отчёт (62) и платежи при новом поступлении (≈ 5) дают около 439 тарифицируемых запросов в месяц на договор, остальное: резерв на повторы. Бесплатный пакет на 500 запросов действует по текущим условиям и зависит от тарифа: проверьте его в API-портале или в get_info().
  • Архитектура. Один APIClient на сервере FastAPI собирает данные в базу за 3 месяца; браузер раз в 10 секунд получает готовые снимки блоков с ETag. Ключи API остаются на сервере.

Расчёт по методам, варианты расписания и пример суточного отчёта: в разделе «Практическое применение».

Документация

Раздел Что внутри
Начало работы Установка, .env и первый запрос
Типовые сценарии Готовые цепочки вызовов: карты, лимиты, отчёты, приглашения, QR
Договоры и ограничения Выбор договора, строгие модели запросов, денежные операции, локальная проверка
Справочники Что в справочниках и какой ID куда передавать
Конфигурация Timeout, retry, лимит частоты, внедрение зависимостей
Учебные примеры Пример, HTTP-запрос, ответ и ошибки для каждого из 89 методов
Оплата по QR-коду Выпуск МПК, срок жизни платёжной строки, блокировки
Практическое применение Дашборд на SDK: методы, бюджет 500 запросов, архитектура
Ошибки и retry Исключения, поля аудита и правила безопасных повторов
Безопасность Credentials, журналирование и транспорт

Разработка

Проверки перед изменением
git clone https://github.com/raspopovaa/apisdkopti24.git && cd apisdkopti24
uv sync --frozen --all-extras
uv run make check

make check запускает линтеры, проверку типов, тесты, сверку контрактов и сборку документации (make lint, types, tests, contracts, docs по отдельности).

При изменении API-контрактов выполните дополнительные проверки из руководства по версиям и контрактам.

Лицензия

MIT

Metadata

Release files for apisdkopti24 0.0.10

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for apisdkopti24 0.0.10
File Size Uploaded Provenance Actions
apisdkopti24-0.0.10.tar.gz 267.3 kB With provenance Details for apisdkopti24-0.0.10.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for apisdkopti24 0.0.10
File Interpreter ABI Platform Actions
apisdkopti24-0.0.10-py3-none-any.whl Python 3 none any Details for apisdkopti24-0.0.10-py3-none-any.whl

Total release size: 440.0 kB

Release files / apisdkopti24-0.0.10.tar.gz

Download URL apisdkopti24-0.0.10.tar.gz
Size 267.3 kB
Tags Source
SHA-256 checksum
How to use checksums
60b8494da009ffab1e0f184d363a81c1ddd55e64a66539e02c88e78f7e7d3c48
BLAKE2b-256 checksum
How to use checksums
a91032fc21f85d96bf2d590e6d4f1634449d74110477470b8d92d69b2a34c84e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Release files / apisdkopti24-0.0.10-py3-none-any.whl

Download URL apisdkopti24-0.0.10-py3-none-any.whl
Size 172.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
126b6617d8a4134221706e8cbbc932274a97162cfcd7ce0cd461014387a3f1e9
BLAKE2b-256 checksum
How to use checksums
c7e3023eea098d28ccf06721c28b3b4ba07857014092195e11bf090ac4c7fbed
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Security for apisdkopti24 0.0.10

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for apisdkopti24-0.0.10.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page