apisdkopti24
Асинхронный Python SDK для Opti24 API: корпоративного API топливных карт АЗС (ОПТИ 24)
Карты, договоры, транзакции, отчёты, лимиты и оплата по QR-коду: типизированно, безопасно для повторов и без ручной работы с сессией.
Документация · Каталог методов · Учебные примеры · Сообщить об ошибке
О 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 |
Как проходит запрос
Один вызов метода сервиса проходит через восемь шагов. Каждый отвечает за одну задачу и лежит в своём модуле.
Что важно на этом пути:
- Повтор решает каталог операции, а не HTTP-метод. Пауза и повтор после
429,509или сбоя сети возможны только у операций, которые каталог помечает безопасными. Перевод средств или блокировка карты не повторяются. - Срок и попытки общие на всю операцию. Ожидание слота, повторы и повторная авторизация расходуют один бюджет, а не начинают отсчёт заново.
- Сессия восстанавливается один раз. Если несколько запросов одновременно
получили
401, повторная авторизация выполняется один раз для всех. Неудачный вход тоже один: ожидавшие запросы получают ту же ошибку, а следующий вызов пробует войти заново.
Структура репозитория
Структура текстом
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-контрактов выполните дополнительные проверки из руководства по версиям и контрактам.
Лицензия
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.