aiofarmad

Unofficial asynchronous Python library to interact with the Mijn Farmad Apotheek API. Requires Python >= 3.14.

This is a reverse-engineered client and the Farmad API may change or withdraw access without notice. It is not affiliated with or endorsed by Farmad.

Install

uv add aiofarmad

Login

import asyncio

from aiofarmad import FarmadClient


async def main() -> None:
    async with FarmadClient(
        email="you@example.com",
        password="your-password",
    ) as client:
        await client.async_login()
        account = await client.async_get_account()
        print(account.full_name, account.entitled_pharmacies)


asyncio.run(main())

The login scripts the same authorization-code flow the web app uses: PKCE against the hosted login form on signin.procura.farmad.be, then a token exchange for an access token and a rotating refresh token. Accounts with multi-factor authentication pass an otp provider, which the login awaits only when the hosted form demands a one-time code.

async def read_code() -> str:
    return input("code: ")


async with FarmadClient(
    email="you@example.com",
    password="your-password",
    otp_provider=read_code,
) as client:
    await client.async_login()

The wait for the code does not count against the request timeout. A rejected code raises FarmadAuthenticationError, and a login that needs a code but has no provider raises FarmadMfaRequiredError.

Token persistence

Log in once, store the access_token and refresh_token of the FarmadTokens that async_login returns, and pass them back on the next start. The client refreshes 30 seconds before the access token expires, retries a request once after a 401 when it holds a refresh token, and calls on_token_refresh after a login and after every rotation. The client logs an exception raised by the callback and does not raise it again, so a failed save leaves the stored pair stale while the client keeps working.

from datetime import UTC, datetime, timedelta

from aiofarmad import FarmadClient


async def run(stored_access: str, stored_refresh: str) -> None:
    start_of_today = datetime.now(UTC).replace(hour=0, minute=0, second=0, microsecond=0)
    end_of_today = start_of_today + timedelta(days=1)

    async def save_tokens(access_token: str, refresh_token: str | None) -> None:
        await write_tokens_somewhere(access_token, refresh_token)

    async with FarmadClient(
        access_token=stored_access,
        refresh_token=stored_refresh,
        on_token_refresh=save_tokens,
    ) as client:
        scheme = await client.async_get_medication_day_scheme(
            "343602",
            from_=start_of_today,
            until=end_of_today,
        )

Client options

FarmadClient takes an optional aiohttp.ClientSession as its first argument. An injected session stays owned by the caller, and the client closes only a session it created. request_timeout sets the timeout in seconds for each API call and defaults to 30. The login applies it to the hosted login steps as a whole, again to the steps after a one-time code, and once to the token exchange. Use the client as an async context manager or call async_close when done.

The account_id and patient_id properties come from the current access token. Methods that take an optional account_id or patient_id fall back to them and raise FarmadMissingIdentifierError, a subclass of FarmadAuthenticationError, when neither is available.

Pharmacies and permissions

Every pharmacy-scoped call takes an apb number, the identifier of one pharmacy. An account only has roles at pharmacies it has been linked to through the app's self-onboarding, which the library exposes as well:

linked = await client.async_link_pharmacy("343602")

The call returns True when the link is active right away and False when the pharmacy still has to accept it. A refused link raises.

Calls against a pharmacy the account has no role at raise FarmadAuthorizationError.

Reading data

Messaging

Reading conversations and messages is one half of the messaging service. The other half is the compose flow: one draft per account and pharmacy, with text, attachments, and a send that publishes it as a message the pharmacy sees.

from pathlib import Path

async with FarmadClient(access_token=..., refresh_token=...) as client:
    draft = await client.async_get_message_draft("343602")
    if draft is None:
        draft = await client.async_save_message_draft("343602", "hello")
    if draft is None:
        msg = "the pharmacy returned no draft"
        raise RuntimeError(msg)
    await client.async_update_message_draft("343602", draft.id, "hello pharmacy")
    await client.async_upload_message_attachment(
        "343602", draft.id, "note.pdf", Path("note.pdf").read_bytes()
    )
    await client.async_send_message_draft("343602", draft.id)

Sending consumes the draft: the next async_get_message_draft answers None until a new one is saved. async_upload_message_attachment returns the attachment id. The service accepts pdf attachments only and answers any other content type with a 500, raised as FarmadCommunicationError, so the content type parameter defaults to application/pdf. async_delete_message_attachment removes one attachment by its id, and async_mark_message_as_read marks one message in a conversation as read.

Ordering

Write calls build a draft, submit it, and can ask the pharmacy to cancel a submitted order:

from aiofarmad import DraftProduct, FarmadClient

products = (DraftProduct(product_cnk="1234567", quantity=1),)

async with FarmadClient(access_token=..., refresh_token=...) as client:
    draft_id = await client.async_save_draft_basket("343602", products=products)
    if draft_id is None:
        msg = "the pharmacy returned no draft id"
        raise RuntimeError(msg)
    order_id = await client.async_submit_basket(
        "343602",
        draft_id,
        products=products,
        unit_prices=(("1234567", 4.95),),
    )

async_save_draft_basket returns the draft id and async_submit_basket returns the order id. Both answer None when the response carries no id. async_update_draft_basket replaces the lines of an existing draft and async_clear_draft_basket deletes it.

Orders are paid at pickup by default. Most pharmacies do not allow online payments, and asking for one there raises FarmadCommunicationError with status 400. With pay_online=True, redirect_url sets where the payment provider sends the browser back after paying. async_pay_basket starts an online payment for a pharmacy that allows it and returns the raw session the app hands to a browser, because the checkout itself runs at the payment provider. Cancelling a submitted order is the pharmacy's decision: customer accounts regularly get FarmadAuthorizationError from async_cancel_basket.

Prescriptions

Prescriptions sit behind the Belgian eHealth platform, and Farmad gates the eHealth session to the browser that completed the itsme consent. Tested against the platform: replaying a live consent session from any non-browser client, with the exact cookies, the exact tokens, and a browser TLS fingerprint, answers 401 every time. No cookie transfer, token pairing, or fingerprint trick carries the session out of the browser.

The library handles the gate as follows:

• async_get_prescriptions and async_get_prescription carry the verified wire paths.
• Every eHealth call from a non-browser client raises FarmadEhealthAuthorizationRequiredError, without burning a refresh token cycle.
• ehealth_cookie exists to pass a consent session through, so the library works the day Farmad relaxes the gate. It currently does not open the prescriptions.

Until Farmad changes the platform, prescriptions work in the web app only.

Errors

Every API, transport, and authentication error derives from FarmadError, which carries the HTTP status when one applies. Invalid arguments, such as an empty apb or a datetime without a timezone, raise ValueError before any request is sent.

Development

uv sync
uv run python -m scripts.check

License

MIT. See LICENSE.