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
Один APIClient открывает 16 сервисов и 89 операций: client.cards,
client.transactions, client.reports и другие. При первом вызове 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.2
или с uv:
uv add apisdkopti24==0.0.2
Проект в разработке, поэтому закрепляйте проверенную версию явно.
Быстрый старт
Создайте рядом со скриптом файл .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 тарифицируется, если в
каталоге методов
не указано обратное; повторы и повторная авторизация тоже расходуют запросы.
Подробнее — в разделе
«Начало работы».
Что важно по спецификации
- Договор выбирается явно: большинство методов используют договор сессии;
переданный
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 |
Не повторяет | Повторить чтение позже; изменение повторять только после проверки состояния чтением |
Локальные сбои не выдают себя за ответ сервера и не наследуют APIError:
OperationTimeoutError и RetryBudgetExceededError (исчерпан общий бюджет
времени или попыток), RequestValidationError (неверный формат или диапазон
дат), ResponseValidationError (ответ не совпал с моделью),
ContractSelectionError (нужно выбрать договор), APIConnectionError (сервер
недоступен), APIResponseTimeoutError и APINetworkError (сервер не ответил;
изменение могло выполниться — проверьте состояние чтением).
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": "3f9c…", "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.
В журналы и аудит не попадают 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 и связан с тестами контрактов. Подробнее — в обзоре архитектуры.
Документация
| Раздел | Что внутри |
|---|---|
| Начало работы | Установка, .env и первый запрос |
| Конфигурация | Timeout, retry, лимит частоты, внедрение зависимостей |
| Учебные примеры | Пример, HTTP-запрос, ответ и ошибки для каждого из 89 методов |
| Оплата по QR-коду | Выпуск МПК, срок жизни платёжной строки, блокировки |
| Ошибки и retry | Исключения, поля аудита и правила безопасных повторов |
| Безопасность | Credentials, журналирование и транспорт |
Разработка
Проверки перед изменением
git clone https://github.com/raspopovaa/apisdkopti24.git && cd apisdkopti24
uv sync --frozen --all-extras
uv run pytest
uv run ruff check src tests scripts tools typecheck
uv run black --check src tests scripts tools typecheck
uv run mypy src/apisdkopti24 typecheck
При изменении API-контрактов выполните дополнительные проверки из руководства по версиям и контрактам.
Лицензия
Metadata
Release files for apisdkopti24 0.0.2
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.2.tar.gz | 209.7 kB | With provenance | Details for apisdkopti24-0.0.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| apisdkopti24-0.0.2-py3-none-any.whl | Python 3 | none | any | Details for apisdkopti24-0.0.2-py3-none-any.whl |
Total release size: 362.4 kB
Release files / apisdkopti24-0.0.2.tar.gz
| Download URL | apisdkopti24-0.0.2.tar.gz |
|---|---|
| Size | 209.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
23c935d46f4d46982b5dd7fe9cae65fecd3e5c28699fd46bd0a6c948bb1fc443
|
|
BLAKE2b-256 checksum How to use checksums |
4ab6cdaf3d6644795fd5e5b4238dd488d4a6c9d9d644f93173f4c7f14a289bab
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 Oct 5, 2026.
Transparency logRelease files / apisdkopti24-0.0.2-py3-none-any.whl
| Download URL | apisdkopti24-0.0.2-py3-none-any.whl |
|---|---|
| Size | 152.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ef61a9d7ae2a3c8aad985969411f3e52327f52a1c8445625f0218163c130700a
|
|
BLAKE2b-256 checksum How to use checksums |
a9a793004672425d5af712abe627642064d7b1aff82007ecec116062ad38a2d6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 Oct 5, 2026.
Transparency logSecurity for apisdkopti24 0.0.2
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.2.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 Oct 5, 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.