Python · API v2

Profirest API pro Python

Knihovna Profirest API v2 pro Python 3.10+ bez povinných závislostí – pro skripty, služby, kiosky a servery partnerů; synchronní, vláknově bezpečná a s typovými anotacemi.

The Profirest API v2 library for Python 3.10+ without required dependencies – for scripts, services, kiosks and partner servers; synchronous, thread-safe and type-annotated.

Knihovna dělá za vás to, co jinak musí každá aplikace napsat a hlavně nezapomenout: spáruje zařízení kódem, připojí aplikaci partnera se souhlasem majitele (OAuth s PKCE), uloží tokeny a obnoví je jen jednou i při souběžných požadavcích a mezi procesy, přihlásí zaměstnance PINem nebo čipem, pošle Idempotency-Key u každého POST (při opakování stejný), po výpadku opakuje podle Retry-After, chyby vrací s kódem z katalogu, prochází stránky seznamů a čte proud událostí. Cesty, těla a odpovědi jsou přesně podle reference; modely všech schémat jsou vygenerované ze smlouvy.

The library does what every application otherwise has to write and, above all, not forget: it pairs a device with a code, connects a partner application with the owner's consent (OAuth with PKCE), stores the tokens and refreshes them only once even for concurrent requests and across processes, signs employees in with a PIN or a card, sends an Idempotency-Key with every POST (the same one when retrying), retries after an outage following Retry-After, returns errors with a code from the catalog, walks list pages and reads the event feed. Paths, bodies and responses are exactly as in the reference; models of all schemas are generated from the contract.

Ke stažení

Download

Archiv obsahuje knihovnu, příkladového klienta, jednotkové testy, README s podrobným návodem, licenci (MIT) a seznam změn. Instalujte ho z archivu, jak ukazuje návod níže. Výchozí adresa knihovny je ostrá https://api.mujprofirest.cz – pracuje nad ostrými daty restaurací, zkoušejte na testovací provozovně.

The archive contains the library, the example client, unit tests, a README with a detailed guide, the licence (MIT) and the changelog. Install it from the archive as shown below. The default address of the library is production https://api.mujprofirest.cz – it works on live restaurant data, test on a test restaurant.

Instalace

Installation

Archiv nainstalujte přímo pipem (po zveřejnění stačí pip install profirest-api):

Install the archive with pip directly (once published, pip install profirest-api is enough):

pip install ./profirest-api-python.zip
pip install "./profirest-api-python.zip[httpx]"   # volitelně transport nad httpx

from profirest_api import ProfirestApi, FileStorage, ApiError, OAuthError, uuid7

Příkladový klient

Example client

Hotová aplikace k vyzkoušení: docházkový terminál v příkazové řádce. Při prvním spuštění zařízení spáruje (vypíše kód, vedoucí ho potvrdí v administraci v Správa PC / zařízení → Připojit kódem), tokeny uloží do souboru a pak přijímá příkazy. Ukazuje párování, píchnutí PINem, výběr zaměstnance při stejném PINu, rozlišení chyb podle kódu a seznam lidí v práci. Adresu API mění proměnná PROFIREST_BASE_URL, soubor s tokeny PROFIREST_TOKENS.

A ready application to try: an attendance terminal on the command line. On the first run it pairs the device (it prints a code that a manager confirms in the administration under PC / devices → Connect a device), stores the tokens in a file and then accepts commands. It shows pairing, punching with a PIN, choosing the employee when a PIN is shared, telling errors apart by code and the list of people at work. PROFIREST_BASE_URL changes the API address, PROFIREST_TOKENS the token file.

python examples/pichacka.py

"""Docházkový terminál v příkazové řádce – příklad klienta Profirest API v2 pro Python.

Spuštění:  python pichacka.py
Proměnné:  PROFIREST_BASE_URL (výchozí https://api.mujprofirest.cz),
           PROFIREST_TOKENS   (soubor s tokeny, výchozí ./profirest-pichacka.json)
Příkazy:   p PIN = příchod, o PIN = odchod, pz PIN = začátek přestávky, kz PIN = konec přestávky,
           k = kdo je v práci, odparovat = zapomenout spárování, q = konec
"""
import os
import sys

try:
    from profirest_api import ApiError, FileStorage, OAuthError, ProfirestApi, uuid7
except ImportError:  # spuštěno ze zdrojů SDK (python/examples) bez instalace balíčku
    sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), '..', 'src'))
    from profirest_api import ApiError, FileStorage, OAuthError, ProfirestApi, uuid7

# české znaky i v konzoli Windows a při přesměrování do souboru
sys.stdout.reconfigure(encoding='utf-8')
sys.stdin.reconfigure(encoding='utf-8')

SCOPE = 'restaurants:read staff:read staff:authenticate attendance:read attendance:punch'
COMMANDS = {'p': 'clock_in', 'o': 'clock_out', 'pz': 'break_start', 'kz': 'break_end'}
STATES = {'working': 'v práci', 'on_break': 'na přestávce', 'off': 'mimo práci'}
HELP = ('Příkazy: p PIN = příchod, o PIN = odchod, pz PIN = začátek přestávky, kz PIN = konec přestávky,\n'
        '         k = kdo je v práci, odparovat = zapomenout spárování, q = konec')


def pair(api):
    """Spáruje terminál kódem: vedoucí ho potvrdí v administraci (Správa PC / zařízení → Připojit zařízení)."""
    pairing = api.pair(scope=SCOPE, device_name='Píchačka (příklad)')
    print('KÓD: ' + pairing.user_code, flush=True)
    print('Potvrďte ho v administraci, nebo otevřete ' + str(pairing.verification_uri_complete), flush=True)
    try:
        pairing.wait()  # blokuje, dokud vedoucí kód nepotvrdí (ptá se po intervalu serveru, 5 s)
    except OAuthError as e:
        if e.error == 'access_denied':
            print('Vedoucí párování odmítl.')
        elif e.error == 'expired_token':
            print('Kód vypršel (10 minut bez potvrzení). Spusťte program znovu.')
        else:
            print('Párování selhalo: ' + e.error)
        sys.exit(1)


def punch(api, kind, pin):
    """Jedno píchnutí. id vznikne jednou – i opakované odeslání (výběr zaměstnance) jde se stejným id."""
    body = {'id': uuid7(), 'type': kind, 'credential': {'method': 'pin', 'secret': pin}}
    path = '/restaurants/' + api.restaurant_id + '/attendance/punches'
    while True:
        try:
            r = api.post(path, body)
            print('OK: %s – %s' % (r['employee']['name'], STATES.get(r['state'], r['state'])), flush=True)
            return
        except ApiError as e:
            if e.code == 'staff_ambiguous':
                # stejný PIN má víc lidí: nechat vybrat a poslat znovu s employee_id
                print('Tento PIN má víc zaměstnanců:')
                for i, c in enumerate(e.candidates, 1):
                    print('  %d) %s' % (i, c['name']))
                print('Číslo:', end=' ', flush=True)
                choice = sys.stdin.readline().strip()
                if not choice.isdigit() or not 1 <= int(choice) <= len(e.candidates):
                    print('Zrušeno.')
                    return
                body['credential']['employee_id'] = e.candidates[int(choice) - 1]['id']
                continue
            if e.code == 'staff_credentials_invalid':
                print('Neznámý PIN.')
            elif e.code == 'staff_locked':
                print('Příliš mnoho špatných PINů – zkuste to za %s s.' % (e.retry_after or 'chvíli'))
            elif e.code == 'attendance_state_conflict':
                print('Nejde to: ' + e.title)  # např. odchod bez příchodu
            elif e.code in ('network_error', 'timeout'):
                print('Bez sítě – zkuste znovu.')  # skutečný terminál by píchnutí uložil a poslal později
            else:
                print('Chyba: %s (%s)' % (e.title, e.code))
            return


def who_is_working(api):
    """Kdo je v práci: všechny stránky GET /restaurants/{id}/attendance/presence."""
    people = api.all('/restaurants/' + api.restaurant_id + '/attendance/presence')
    if not people:
        print('Nikdo.')
    for p in people:
        print('  %s – %s' % (p['employee']['name'], STATES.get(p['state'], p['state'])))


def main():
    api = ProfirestApi(
        base_url=os.environ.get('PROFIREST_BASE_URL', 'https://api.mujprofirest.cz'),
        client_id='profirest-dochazka',
        # tokeny přežijí restart programu; soubor chraňte jako heslo
        storage=FileStorage(os.environ.get('PROFIREST_TOKENS', 'profirest-pichacka.json')),
        on_unpaired=lambda reason: print('Zařízení bylo odpárováno – spusťte program znovu.'),
    )
    if not api.is_paired():
        pair(api)
    if api.restaurant_id is None:
        api.connection()  # GET /v2/connection zapamatuje provozovnu terminálu
    print('Provozovna ' + str(api.restaurant_id))
    print(HELP, flush=True)

    for line in sys.stdin:  # EOF (Ctrl+D / Ctrl+Z) = konec
        parts = line.split()
        if not parts:
            continue
        cmd = parts[0].lower()
        try:
            if cmd == 'q':
                break
            elif cmd == 'k':
                who_is_working(api)
            elif cmd == 'odparovat':
                api.unpair()  # zapomene tokeny a refresh token zneplatní na serveru
                print('Odpárováno.')
                break
            elif cmd in COMMANDS and len(parts) == 2:
                punch(api, COMMANDS[cmd], parts[1])
            else:
                print(HELP)
        except ApiError as e:
            if e.code == 'not_paired':
                print('Terminál není spárovaný – spusťte program znovu.')
                return 1
            print('Chyba: %s (%s)' % (e.title, e.code))
        sys.stdout.flush()
    return 0


if __name__ == '__main__':
    sys.exit(main())

Spárovat zařízení

Pair a device

Pokladna, kuchyňský displej, docházkový terminál a telefon kurýra se připojují kódem (RFC 8628). Zařízení ukáže kód, vedoucí ho zadá v administraci (Správa PC / zařízení → Připojit kódem) a vybere provozovnu; zařízení si tokeny vyzvedne samo a pak pracuje jen pro ni. Kód platí 10 minut; knihovna se ptá podle interval (5 s), po slow_down o 5 s déle a výpadek sítě přečká. Odmítnutí vedoucím = access_denied, propadlý kód = expired_token.

A register, kitchen display, attendance terminal and courier phone connect with a code (RFC 8628). The device shows the code, a manager enters it in the administration (PC / devices → Connect a device) and chooses the restaurant; the device collects its tokens itself and then works only for it. The code is valid for 10 minutes; the library polls every interval (5 s), 5 s slower after slow_down, and survives a network outage. A refusal by the manager = access_denied, an expired code = expired_token.

api = ProfirestApi(
    client_id='profirest-dochazka',
    storage=FileStorage('/var/lib/pichacka/profirest.json'),   # tokeny přežijí restart
    on_unpaired=lambda reason: show_pairing(),
)
if not api.is_paired():
    pairing = api.pair(scope='restaurants:read staff:read staff:authenticate attendance:read attendance:punch',
                       device_name='Píchačka u vchodu', app_version='2.0.0')
    show_code(pairing.user_code, pairing.verification_uri_complete)
    try:
        pairing.wait()                       # blokuje, než vedoucí kód potvrdí
    except OAuthError as e:
        raise SystemExit(f'Párování se nepovedlo: {e.error}')   # access_denied, expired_token
if api.restaurant_id is None:
    api.connection()

Webová aplikace: pairing.to_dict() uložte do session a v dalším požadavku zavolejte api.resume_pairing(data).poll(); cancel() (i z jiného vlákna) čekání ukončí.

A web application: store pairing.to_dict() in the session and call api.resume_pairing(data).poll() in the next request; cancel() (even from another thread) stops waiting.

Docházkový terminál

Attendance terminal

POST /v2/restaurants/{restaurant_id}/attendance/punches. Na terminálu se nikdo nepřihlašuje – každé píchnutí nese PIN nebo čip. id vznikne na zařízení ve chvíli píchnutí (UUIDv7 řazené podle času) a stejné id server nikdy nezapíše dvakrát: první zápis vrátí 201, opakování 200 se stejným tělem. Chyby se rozlišují podle kódu, ne podle HTTP stavu.

POST /v2/restaurants/{restaurant_id}/attendance/punches. Nobody signs in on a terminal – every punch carries a PIN or a card. The id is made on the device when the person punches (a time-ordered UUIDv7) and the server never records the same id twice: the first write returns 201, a repeat 200 with the same body. Errors differ by code, not by HTTP status.

body = {'id': uuid7(), 'type': 'clock_in', 'credential': {'method': 'pin', 'secret': pin}}
try:
    r = api.post(f'/restaurants/{api.restaurant_id}/attendance/punches', body)
    show_done(r['employee']['name'], r['state'])           # working, on_break, off
except ApiError as e:
    if e.code == 'staff_ambiguous':
        choose_employee(e.candidates)                      # znovu se stejným id a credential.employee_id
    elif e.code == 'staff_credentials_invalid':
        show_wrong_pin()
    elif e.code == 'staff_locked':
        show_locked(e.retry_after)
    elif e.code in ('network_error', 'timeout'):
        save_offline(body)
    else:
        show_message(e.title)

S modely: AttendancePunch.from_dict(api.post(path, AttendancePunchCreate(id=uuid7(), type='clock_in', …))).

With models: AttendancePunch.from_dict(api.post(path, AttendancePunchCreate(id=uuid7(), type='clock_in', …))).

Bez sítě píchnutí uložte i s id a časem occurred_at a pošlete později dávkou (nejvýš 100) na POST …/attendance/punches/batch – každá položka má vlastní výsledek. Frontu držte jen na zařízení, nese PINy.

Without a network store the punch with its id and occurred_at and send it later in a batch (at most 100) to POST …/attendance/punches/batch – every item gets its own result. Keep the queue on the device only, it carries PINs.

Pokladna a zaměstnanec

Register and employee

Na pokladně se zaměstnanec přihlásí PINem nebo čipem a knihovna pak posílá jeho token v hlavičce Profirest-Staff-Token u každého požadavku sama; token drží jen v paměti. Relace vyprší po nečinnosti (idle_timeout_seconds, každý úspěšný požadavek ji prodlouží) a nejpozději v max_expires_at – počítá se podle hodin zařízení. Stejný PIN víc lidí = 409 staff_ambiguous s kandidáty: nechte vybrat a zavolejte znovu s employee_id. Volba staff u požadavku: automaticky (výchozí – poslat, je-li někdo přihlášený), vyžadovat (bez přihlášení chyba staff_session_required a nic se neodešle), neposílat, nebo konkrétní token.

On a register an employee signs in with a PIN or a card and the library then sends their token in the Profirest-Staff-Token header with every request itself; the token stays in memory only. The session ends after inactivity (idle_timeout_seconds, every successful request extends it) and at max_expires_at at the latest – counted by the device clock. Several people with the same PIN = 409 staff_ambiguous with candidates: let the person choose and call again with employee_id. The staff request option: automatic (default – send it when somebody is signed in), required (without a sign-in the error staff_session_required and nothing is sent), never, or a specific token.

try:
    api.sign_in_staff(rid, {'method': 'card', 'secret': card_number})
except ApiError as e:
    if e.code != 'staff_ambiguous':
        raise
    who = choose_employee(e.candidates)
    api.sign_in_staff(rid, {'method': 'card', 'secret': card_number, 'employee_id': who['id']})
print(api.staff)                              # SignedInStaff(employee=…, expires_at=…, max_expires_at=…)
api.post(f'/restaurants/{rid}/receipts', receipt, staff=True)   # bez přihlášení se ani neodešle
api.sign_out_staff()

Aplikace partnera

Partner application

E-shop nebo jiná aplikace partnera se připojuje se souhlasem majitele restaurace (authorization code + PKCE S256). Na serveru je to důvěrný klient: client_secret posílá knihovna jako HTTP Basic (client_secret_basic, RFC 6749 2.3.1) a nikdy nepatří do aplikace u zákazníka. Ověřovač PKCE a state drží mezi přesměrováním a zpětným voláním úložiště; zpětné volání ověří state a iss (RFC 9207) a vymění kód za tokeny. Jedna instance = jedno připojení: tokeny i rozpracovaný souhlas leží pod jedním klíčem úložiště a výchozí klíč (profirest-api:<clientId>) je jeden pro celou aplikaci. Pro každý připojený účet proto použijte vlastní instanci s vlastním klíčem úložiště odvozeným z ID účtu ve vašem systému (znáte ho už před přesměrováním) – se společným klíčem by souhlas dalšího majitele přepsal tokeny předchozího a dva souběžné souhlasy by si přepsaly state. Víc provozoven jednoho majitele je jedno připojení. Když už token máte odjinud, předejte ho jako pevný access token – knihovna ho pošle a nikdy neobnovuje.

An e-shop or another partner application connects with the consent of the restaurant owner (authorization code + PKCE S256). On a server it is a confidential client: the library sends the client_secret as HTTP Basic (client_secret_basic, RFC 6749 2.3.1) and it never belongs into an app on the customer's device. The PKCE verifier and state are kept in the storage between the redirect and the callback; the callback checks state and iss (RFC 9207) and exchanges the code for tokens. One instance = one connection: the tokens and a consent in progress sit under one storage key, and the default key (profirest-api:<clientId>) is one for the whole application. So use a separate instance with its own storage key for every connected account, derived from the account ID in your system (you know it before the redirect) – with a shared key the consent of the next owner would overwrite the tokens of the previous one and two concurrent consents would overwrite each other's state. Several restaurants of one owner are one connection. When you already have a token from elsewhere, pass it as a fixed access token – the library sends it and never refreshes it.

def api_for(account_id):
    return ProfirestApi(client_id='your-client-id', client_secret=os.environ['PROFIREST_CLIENT_SECRET'],
                        storage=FileStorage('/var/lib/shop/profirest.json'), storage_key=f'account-{account_id}')

@app.get('/profirest/connect')
def connect():
    return redirect(api_for(current_account()).authorization_url(
        redirect_uri='https://shop.example/profirest/callback', scope='restaurants:read catalog:read orders:write'))

@app.get('/profirest/callback')
def callback():
    connection = api_for(current_account()).complete_authorization(request.url)   # ověří state a iss

Požadavky

Requests

Cesty se píšou relativně k /v2, přesně jako v referenci (/oauth/… a /.well-known/… jdou od kořene). Tělo: objekt nebo model → JSON; řetězec nebo bajty → syrově s typem obsahu (zálohy ZIP). Dotaz: prázdné hodnoty se vynechají, pole se spojí čárkou. Odpověď: JSON dekódovaný, 204 nic, jiný obsah bajty. U POST pošle knihovna vlastní Idempotency-Key a při automatickém opakování stejný; když požadavek opakujete vy (po restartu aplikace), předejte vlastní klíč uložený u záznamu. Klíč knihovny žije jen v paměti procesu, po pádu aplikace ho nemáte – u zápisů, které se nesmí provést dvakrát (objednávka), proto vlastní klíč vytvořte a uložte k záznamu dřív, než požadavek odešlete (server výsledek drží 24 hodin). Objednávka má navíc pojistky nezávislé na klíči: kalkulace jde použít jen jednou (409 quote_already_used) a external_id je trvalé (409 external_id_conflict); obě chyby nesou ID existující objednávky. Tokeny (Authorization i Profirest-Staff-Token) odcházejí jen na adresu API, nikdy na cizí absolutní adresu; přesměrování se nesledují.

Paths are written relative to /v2, exactly as in the reference (/oauth/… and /.well-known/… go from the root). Body: an object or a model → JSON; a string or bytes → raw with a content type (ZIP backups). Query: empty values are left out, arrays are joined with a comma. Response: JSON decoded, 204 nothing, other content bytes. For a POST the library sends its own Idempotency-Key and the same one on an automatic retry; when you repeat a request yourself (after an application restart), pass your own key stored with the record. The library's key lives only in the memory of the process, after a crash you do not have it – for writes that must not happen twice (an order) create your own key and store it with the record before you send the request (the server keeps the result for 24 hours). An order also has guards that do not depend on the key: a quote can be used only once (409 quote_already_used) and external_id is permanent (409 external_id_conflict); both errors carry the ID of the existing order. Tokens (Authorization and Profirest-Staff-Token) go only to the API address, never to a foreign absolute URL; redirects are not followed.

catalog = api.get('/restaurants/11/catalog', query={'channel': 'pos'})

# stav a hlavičky (ETag, Location)
r = api.get(f'/customers/{customer_id}', with_response=True)
api.patch(f'/customers/{customer_id}', {'name': 'Jana Nováková'}, if_match=r.headers.get('ETag'))

# vlastní Idempotency-Key uložený u objednávky
api.post('/restaurants/11/orders', order, idempotency_key=order['local_id'])

# binární tělo a stažení
with open('zaloha.zip', 'rb') as fh:
    api.post(f'/restaurants/{rid}/backups', fh, content_type='application/zip', timeout=120)
data = api.get(f'/restaurants/{rid}/backups/{backup_id}/content', accept='application/zip')   # bytes

Seznamy po stránkách

Paged lists

Seznamy vrací {data, next_cursor}. Knihovna projde stránky sama (všechny položky najednou, nebo stránku po stránce); konec je stránka bez next_cursor nebo prázdná stránka. Kurzor je neprůhledný řetězec – nikdy ho neskládejte.

Lists return {data, next_cursor}. The library walks the pages itself (all items at once, or page by page); the end is a page without next_cursor or an empty page. The cursor is an opaque string – never build one.

staff = api.all('/restaurants/11/staff', {'limit': 100})
for page in api.pages('/restaurants/11/attendance/presence'):
    render(page['data'])

Proud událostí

Event feed

Proud událostí knihovna čte dokola. Když běží služba proudu, čte živě GET /v2/events/stream (Server-Sent Events) – událost přijde pár sekund po změně a nic se nedotazuje. Když neběží (503), na starším serveru nebo s vlastním transportem, který neumí číst odpověď po kouscích, čte GET /v2/events a o proud se pokusí znovu za Retry-After (výchozí 5 minut). Kurzor je v obou stejný (u proudu jde jako Last-Event-ID), přechod nic nepřeskočí; výpadek spojení není chyba – připojí se znovu za 2 s, 4 s, po třetím nezdaru minutu dotazuje. Volba stream (výchozí zapnuto; vypnuto = jen dotazování) a dotaz, zda teď běží proud, mají jména podle jazyka (viz Metody); krok pro cron (once) dělá dál jeden dotaz GET /v2/events. Kurzor posune a uloží až po úspěšném zpracování – událost tak přijde aspoň jednou, zpracování má být idempotentní (např. podle id události). Plnou stránku dožene hned, jinak čeká interval (5 s); bez uloženého kurzoru začne na konci proudu. Po 410 cursor_expired zavolá obsluhu resetu (načtěte si stav znovu), při chybě čeká podle Retry-After nebo déle a déle (až 60 s) a ztráta spárování čtení ukončí. limit je nejvýš 100. Kurzor leží v úložišti pod events_cursor[:provozovna][:typy].

The library reads the event feed in a loop. While the stream service runs, it reads GET /v2/events/stream live (Server-Sent Events) – an event arrives a few seconds after the change and nothing is polled. When it does not run (503), on an older server or with a custom transport that cannot read a response in pieces, it reads GET /v2/events and tries the stream again after Retry-After (5 minutes by default). The cursor is the same in both (the stream gets it as Last-Event-ID), switching skips nothing; a dropped connection is not an error – it reconnects after 2 s, 4 s, and after the third failure polls for a minute. The stream option (on by default; off = polling only) and the query whether the stream runs now are named per language (see Methods); the cron step (once) still makes one GET /v2/events request. It moves and stores the cursor only after successful processing – an event arrives at least once, so processing should be idempotent (for example by the event id). A full page is caught up at once, otherwise it waits the interval (5 s); without a stored cursor it starts at the end of the feed. After 410 cursor_expired it calls the reset handler (reload your state), on an error it waits per Retry-After or longer and longer (up to 60 s), and losing the pairing ends the reading. limit is at most 100. The cursor lives in the storage under events_cursor[:restaurant][:types].

watcher = api.watch_events(
    lambda events: reload_board(),           # výjimka = stránka přijde znovu
    restaurant_id=api.restaurant_id,
    types=['kitchen.ticket_updated', 'order.created', 'order.status_changed'],
    interval=3,
    on_reset=lambda e: reload_board(),
    on_error=lambda e: log.warning('události: %s', e),
)
watcher.start()       # vlákno na pozadí; watcher.run() blokuje, watcher.once() jeden dotaz (cron)
watcher.is_streaming  # True = živý proud, False = dotazování GET /v2/events
watcher.stop()        # i z jiného vlákna; zavře i otevřený proud

Chyby

Errors

Každá chyba API přijde jako výjimka s kódem z katalogu (RFC 9457). Rozhodujte se podle kódu, ne podle HTTP stavu – kódy se nikdy nemění, nové mohou přibýt. Název pro člověka je česky nebo anglicky podle volby jazyka.

Every API error arrives as an exception with a code from the catalog (RFC 9457). Decide by the code, not by the HTTP status – codes never change, new ones may come. The title for a person is in Czech or English depending on the language option.

try:
    api.post(f'/restaurants/{rid}/quotes', quote)
except ApiError as e:
    if e.code == error_codes.VALIDATION_FAILED:
        for f in e.errors:
            print(f['pointer'], f['message'])
    log.warning('Profirest %s (%s)', e.code, e.request_id)

Kódy jen z knihovny

Library-only codes

Opakování a výpadky

Retries and outages

Knihovna opakuje jen to, co opakovat jde, nejvýš 3× se stejným tělem a Idempotency-Key. Odstup se zdvojnásobuje od 1 s do 30 s s rozptylem ±25 %, aby se zařízení po výpadku nevrátila všechna najednou. Retry-After (sekundy i HTTP datum) má přednost; delší než 30 s knihovna nečeká a vrátí chybu s počtem sekund.

The library retries only what can be retried, at most 3× with the same body and Idempotency-Key. The delay doubles from 1 s up to 30 s with ±25 % jitter so devices do not all come back at once after an outage. Retry-After (seconds or an HTTP date) wins; the library does not wait longer than 30 s and returns the error with the seconds.

Tokeny a úložiště

Tokens and storage

Stav klienta (tokeny, provozovna zařízení, kurzory událostí) ukládá rozhraní úložiště se třemi metodami – načíst, uložit a smazat řetězec. Paměťové úložiště vydrží do konce procesu, souborové drží JSON s právy jen pro vlastníka. Access token platí 30 minut; knihovna ho obnoví minutu před koncem a po 401 invalid_token. Refresh token veřejného klienta platí jen na jedno použití – sdílí-li úložiště víc procesů, obnovuje pod zámkem úložiště jen jeden a ostatní použijí jeho nový token. invalid_grant (zařízení odpárováno) tokeny smaže a zavolá obsluhu odpárování; invalid_client a unauthorized_client jsou přechodné a tokeny nechá. Pod klíčem profirest-api:<client_id> leží JSON se stejnými klíči ve všech knihovnách.

The client state (tokens, the device's restaurant, event cursors) is kept by a storage interface with three methods – read, write and delete a string. Memory storage lasts until the process ends; file storage keeps JSON readable by the owner only. An access token is valid for 30 minutes; the library refreshes it a minute before the end and after 401 invalid_token. A public client's refresh token is single-use – when several processes share the storage, only one refreshes under the storage lock and the others use its new token. invalid_grant (device unpaired) deletes the tokens and calls the unpaired handler; invalid_client and unauthorized_client are temporary and keep them. Under the key profirest-api:<client_id> lies JSON with the same keys in every library.

class DbStorage:                             # protokoly TokenStorage + LockingStorage
    def __init__(self, db): self.db = db
    def get(self, key): return self.db.fetch_value('SELECT value FROM kv WHERE key = %s', key)
    def set(self, key, value): self.db.execute('REPLACE INTO kv (key, value) VALUES (%s, %s)', key, value)
    def remove(self, key): self.db.execute('DELETE FROM kv WHERE key = %s', key)
    def with_lock(self, name, fn):
        with self.db.advisory_lock(name):    # např. GET_LOCK() v MySQL
            return fn()

MemoryStorage() (výchozí) vydrží do konce procesu, FileStorage(path) zamyká <soubor>.lock (msvcrt na Windows, fcntl jinde). Klient je synchronní a vláknově bezpečný; v asyncio ho volejte přes asyncio.to_thread.

MemoryStorage() (default) lasts until the process ends, FileStorage(path) locks <file>.lock (msvcrt on Windows, fcntl elsewhere). The client is synchronous and thread-safe; in asyncio call it through asyncio.to_thread.

Reference

Volby klienta

Client options

api = ProfirestApi(base_url=…, client_id=…, storage=…, …)

Metody

Methods

Volby požadavku: query, body, content_type, idempotency_key (False = bez klíče), if_match, staff, retries, timeout, accept, headers, with_response, auth.

Request options: query, body, content_type, idempotency_key (False = no key), if_match, staff, retries, timeout, accept, headers, with_response, auth.

Bezpečnost

Security

• client_secret patří jen na server, nikdy do aplikace na zařízení nebo v prohlížeči.
• client_secret belongs on a server only, never into an app on a device or in a browser.
• Tokeny zařízení patří zařízení a jen jeho provozovně. Soubor s tokeny chraňte jako heslo; ztracené zařízení odpárujte v administraci – tokeny přestanou platit hned.
• Device tokens belong to the device and its restaurant only. Protect the token file like a password; unpair a lost device in the administration – its tokens stop working at once.
• Token zaměstnance zůstává jen v paměti a končí nečinností. PIN knihovna nikam neukládá.
• The staff token stays in memory only and ends with inactivity. The library never stores a PIN.
• Tokeny odcházejí jen na adresu API; přesměrování se nesledují.
• Tokens go only to the API address; redirects are not followed.
• Offline fronta docházkového terminálu nese PINy – držte ji jen na zařízení a po odeslání ji smažte.
• The offline queue of an attendance terminal carries PINs – keep it on the device only and delete it after sending.

Změny

Changes