onemax

Python client for the OneMax partner API.

OneMax is a 1+1 membership club in Baku. Members pay for a plan and show a code at the counter to use a partner's offer. This library lets a partner's own system do what the counter does: check that someone is a member and record that they used the offer.

Sync and async, fully typed, one dependency.

pip install onemax

Getting a key

1. OneMax switches API access on for your business.
2. The owner opens the partner panel, goes to API and creates a key.
3. The key is shown once. It belongs to one venue and acts there like a cashier.

Keep the key on your server. It must never reach a browser or a mobile app.

Quick start: a member's code

A member opens their OneMax card and reads you the six digit code.

from onemax import OneMaxClient

client = OneMaxClient("omx_live_...")

check = client.verify_code("482915")
if not check.usable:
    print("No discount:", check.reason)
else:
    order = place_order(discounted=True)
    client.confirm_usage(check.usage_id, reference=order.id)

verify_code only answers the question. Nothing counts against the member until you call confirm_usage. If the order falls through, call void_usage(check.usage_id) instead.

Pass your own order id as reference. Confirming again with the same reference returns the same usage, so a retried request is safe.

Account linking

A member links their OneMax account to your app once. After that you check them without a code. Linking is the OAuth 2.0 authorization code flow with PKCE, so the same steps work for a website and a mobile app.

Register the addresses your app may return to in the partner panel, under API, Account linking. Your client id is shown there.

1. Send the member to the permission page.

from onemax import generate_pkce

pkce = generate_pkce()
session["onemax_verifier"] = pkce.verifier

url = client.authorize_url(
    client_id="omx_client_...",
    redirect_uri="https://example.az/onemax/return",
    code_challenge=pkce.challenge,
    state=session_id,
)

In a mobile app, open url in the system browser and use your app link as the redirect_uri, for example taksi://onemax/return.

2. The member returns to your address with code and state, or with error=access_denied if they declined. Check that state is the one you sent.

3. Exchange the code on your server and store the token.

link = client.exchange_code(
    code,
    code_verifier=session["onemax_verifier"],
    redirect_uri="https://example.az/onemax/return",
)
save(user_id, link.link_token)

The code works once and for five minutes.

4. Check the member whenever you need to.

status = client.link_status(link_token)
if not status.linked:
    forget(user_id)

check = client.verify_link(link_token)
if check.usable:
    client.confirm_usage(check.usage_id, reference=order.id)

A member can unlink at any time in their OneMax profile. From then on link_status answers linked=False and verify_link answers reason="not_linked". Neither raises.

You learn only whether the subscription is active. The member's name, email, phone and photo are never shared.

Async

AsyncOneMaxClient has the same methods, awaited:

from onemax import AsyncOneMaxClient

async with AsyncOneMaxClient("omx_live_...") as client:
    check = await client.verify_code("482915")

Results

verify_code and verify_link return a Verification:

Reason and UsageStatus are string enums, so check.reason == "ok" works as well. A value this version does not know is returned as a plain string.

If a venue has several offers open, pass offer_id. client.context() lists them.

Errors

Everything the library raises is a OneMaxError.

from onemax import ConflictError, OneMaxError

try:
    client.confirm_usage(usage_id, reference=order.id)
except ConflictError as error:
    if error.code == "usage_limit_reached":
        charge_full_price(order)
    else:
        raise
except OneMaxError:
    retry_later(order)

message is in Azerbaijani and meant for your logs. Decide on code.

Limits

• The member's daily limit applies exactly as it does at a counter.
• 120 requests a minute per key.
• The library never retries by itself. confirm_usage with a reference is safe to retry.

Development

uv sync
uv run ruff format --check .
uv run ruff check .
uv run mypy src
uv run pytest

Releasing

Set the version in src/onemax/_version.py, add a ## x.y.z section to CHANGELOG.md, commit, then push a tag vx.y.z. The Publish workflow checks that the tag equals the package version, runs the checks, publishes to PyPI and creates the GitHub release from the changelog section. A tag that does not match the version publishes nothing.

License

MIT