PHP · API v2

Profirest API pro PHP

Knihovna Profirest API v2 pro PHP 8.1+ bez závislostí (jen ext-curl) – pro e-shopy partnerů, skripty, služby a kiosky na serveru.

The Profirest API v2 library for PHP 8.1+ without dependencies (just ext-curl) – for partner e-shops, scripts, services and kiosks on a server.

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 rozbalte do projektu a přidejte ho do composer.json jako cestu (po zveřejnění stačí composer require profirest/api-client):

Unpack the archive into your project and add it to composer.json as a path (once published, composer require profirest/api-client is enough):

{
    "repositories": [{ "type": "path", "url": "lib/profirest-api-php-1.0.0" }],
    "require": { "profirest/api-client": "^1.0" }
}

composer update profirest/api-client

Bez Composeru stačí autoloader PSR-4 na složku src/ (jmenný prostor Profirest\Api\).

Without Composer a PSR-4 autoloader for the src/ folder is enough (namespace Profirest\Api\).

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.

php examples/pichacka.php

<?php

/**
 * Příkladový klient Profirest API v2: docházkový terminál v příkazové řádce.
 *
 *   php pichacka.php
 *
 * Při prvním spuštění zařízení spáruje – vypíše kód, který vedoucí potvrdí v administraci (Správa PC / zařízení →
 * Připojit zařízení). Pak čte 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
 *
 * Proměnné prostředí: PROFIREST_BASE_URL (výchozí https://api.mujprofirest.cz), PROFIREST_TOKENS (soubor s tokeny,
 * výchozí ./profirest-pichacka.json – chraňte ho jako heslo).
 */

declare(strict_types=1);

// knihovna z Composeru, nebo přímo ze zdrojů vedle příkladu
$autoload = __DIR__ . '/../vendor/autoload.php';
if (is_file($autoload)) {
    require $autoload;
} else {
    spl_autoload_register(static function (string $class): void {
        $prefix = 'Profirest\\Api\\';
        if (str_starts_with($class, $prefix)) {
            $file = __DIR__ . '/../src/' . str_replace('\\', '/', substr($class, strlen($prefix))) . '.php';
            if (is_file($file)) {
                require $file;
            }
        }
    });
}

use Profirest\Api\ApiError;
use Profirest\Api\Client;
use Profirest\Api\ErrorCode;
use Profirest\Api\OAuthError;
use Profirest\Api\Storage\FileStorage;

$api = new Client(
    baseUrl: getenv('PROFIREST_BASE_URL') ?: 'https://api.mujprofirest.cz',
    clientId: 'profirest-dochazka',
    storage: new FileStorage(getenv('PROFIREST_TOKENS') ?: __DIR__ . '/profirest-pichacka.json'),
);

// 1) spárování kódem (RFC 8628) – jen poprvé, tokeny pak zůstávají v souboru
if (!$api->isPaired()) {
    try {
        $pairing = $api->pair(
            scope: 'restaurants:read staff:read staff:authenticate attendance:read attendance:punch',
            deviceName: 'Píchačka (příklad)',
        );
        echo "Zařízení není spárované. Vedoucí potvrdí kód v administraci (Správa PC / zařízení → Připojit zařízení).\n";
        echo "KÓD: {$pairing->userCode}\n";
        echo "nebo otevřete: {$pairing->verificationUriComplete}\n";
        $pairing->wait();                                   // ptá se podle intervalu, než vedoucí potvrdí
    } catch (OAuthError $e) {
        echo match ($e->error) {
            'access_denied' => "Vedoucí párování odmítl.\n",
            'expired_token' => "Kód vypršel (10 minut). Spusťte příklad znovu.\n",
            default => "Párování se nepovedlo: {$e->getMessage()}\n",
        };
        exit(1);
    }
}
if ($api->restaurantId() === null) {
    $api->connection();                                     // zapamatuje provozovnu zařízení
}
$rid = $api->restaurantId();
echo "Provozovna $rid. Příkazy: p/o/pz/kz PIN, k = kdo je v práci, odparovat, q = konec.\n";

$types = ['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'];

// 2) píchnutí – id vznikne jednou na píchnutí; při opakování (výběr zaměstnance, výpadek) se posílá stejné
function punch(Client $api, string $rid, string $type, string $pin, array $states): void
{
    $body = ['id' => Client::uuid(), 'type' => $type, 'credential' => ['method' => 'pin', 'secret' => $pin]];
    for (;;) {
        try {
            $r = $api->post("/restaurants/$rid/attendance/punches", $body);
            echo "OK: {$r['employee']['name']} – " . ($states[$r['state']] ?? $r['state']) . "\n";
            return;
        } catch (ApiError $e) {
            switch ($e->errorCode) {
                case ErrorCode::STAFF_AMBIGUOUS:            // stejný PIN má víc lidí – vybrat a poslat znovu
                    echo "Tento PIN má víc lidí:\n";
                    foreach ($e->candidates as $i => $c) {
                        echo '  ' . ($i + 1) . ") {$c['name']}\n";
                    }
                    echo 'Číslo: ';
                    $choice = (int)trim((string)fgets(STDIN));
                    if (!isset($e->candidates[$choice - 1])) {
                        echo "Zrušeno.\n";
                        return;
                    }
                    $body['credential']['employee_id'] = $e->candidates[$choice - 1]['id'];
                    continue 2;
                case ErrorCode::STAFF_CREDENTIALS_INVALID:
                    echo "Neznámý PIN.\n";
                    return;
                case ErrorCode::STAFF_LOCKED:
                    echo "Moc špatných pokusů – zkuste to za {$e->retryAfter} s.\n";
                    return;
                case ErrorCode::ATTENDANCE_STATE_CONFLICT:
                    echo "Teď to nejde: {$e->title}\n";
                    return;
                case ErrorCode::NETWORK_ERROR:
                case ErrorCode::TIMEOUT:
                    echo "Bez sítě – zkuste znovu.\n";     // skutečný terminál by píchnutí uložil a poslal dávkou
                    return;
                default:
                    echo "Chyba: {$e->title} ({$e->errorCode})\n";
                    return;
            }
        }
    }
}

// 3) smyčka příkazů
while (($line = fgets(STDIN)) !== false) {
    $parts = preg_split('/\s+/', trim($line), 2);
    $cmd = strtolower($parts[0] ?? '');
    try {
        if (isset($types[$cmd]) && isset($parts[1])) {
            punch($api, $rid, $types[$cmd], $parts[1], $states);
        } elseif ($cmd === 'k') {
            foreach ($api->all("/restaurants/$rid/attendance/presence") as $p) {
                echo "  {$p['employee']['name']}: " . ($states[$p['state']] ?? $p['state']) . "\n";
            }
        } elseif ($cmd === 'odparovat') {
            $api->unpair();
            echo "Spárování zapomenuto.\n";
            break;
        } elseif ($cmd === 'q') {
            break;
        } elseif ($cmd !== '') {
            echo "Příkazy: p/o/pz/kz PIN, k, odparovat, q\n";
        }
    } catch (ApiError $e) {
        if ($e->errorCode === ErrorCode::NOT_PAIRED) {       // vedoucí zařízení odpároval
            echo "Zařízení bylo odpárováno. Spusťte příklad znovu.\n";
            exit(1);
        }
        echo "Chyba: {$e->title} ({$e->errorCode})\n";
    }
}

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.

use Profirest\Api\Client;
use Profirest\Api\OAuthError;
use Profirest\Api\Storage\FileStorage;

$api = new Client(clientId: 'profirest-dochazka', storage: new FileStorage('/var/lib/pichacka/profirest.json'));
if (!$api->isPaired()) {
    $pairing = $api->pair(scope: 'restaurants:read staff:read staff:authenticate attendance:read attendance:punch',
                          deviceName: 'Píchačka u vchodu', appVersion: '1.4.0');
    echo $pairing->userCode, "\n", $pairing->verificationUriComplete, "\n";   // kód a QR pro vedoucího
    try {
        $pairing->wait();                    // blokuje, než vedoucí kód potvrdí
    } catch (OAuthError $e) {
        exit('Párování se nepovedlo: ' . $e->error);   // access_denied, expired_token
    }
}
echo 'Provozovna ', $api->restaurantId();

Webová stránka, která se ptá AJAXem: stav $pairing->toArray() uložte do session a v dalším požadavku zavolejte $api->resumePairing($state)->poll() – vrátí true po spárování a na server se zeptá jen po uplynutí intervalu. Stav obsahuje device_code, nikdy ho neposílejte do prohlížeče.

A web page that polls with AJAX: store $pairing->toArray() in the session and call $api->resumePairing($state)->poll() in the next request – it returns true once paired and asks the server only after the interval. The state contains device_code, never send it to the browser.

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.

use Profirest\Api\ApiError;
use Profirest\Api\ErrorCode;

$body = ['id' => Client::uuid(), 'type' => 'clock_in', 'credential' => ['method' => 'pin', 'secret' => $pin]];
try {
    $punch = $api->post('/restaurants/' . $api->restaurantId() . '/attendance/punches', $body);
    echo $punch['employee']['name'], ' – ', $punch['state'];          // working, on_break, off
} catch (ApiError $e) {
    match ($e->errorCode) {
        ErrorCode::STAFF_AMBIGUOUS => chooseEmployee($e->candidates),  // znovu se stejným id a credential.employee_id
        ErrorCode::STAFF_CREDENTIALS_INVALID => showWrongPin(),
        ErrorCode::STAFF_LOCKED => showLocked($e->retryAfter),         // sekundy do odemčení
        ErrorCode::ATTENDANCE_STATE_CONFLICT => showMessage($e->title),
        ErrorCode::NETWORK_ERROR, ErrorCode::TIMEOUT => saveOffline($body),
        default => showMessage($e->title),
    };
}

S modely ze smlouvy (typy a doplňování v IDE):

With models from the contract (types and IDE completion):

use Profirest\Api\Model\{AttendancePunch, AttendancePunchCreate, StaffCredential};

$punch = AttendancePunch::fromArray($api->post("/restaurants/$rid/attendance/punches", new AttendancePunchCreate(
    id: Client::uuid(), type: 'clock_in', credential: new StaffCredential(method: 'pin', secret: '5678'),
)));
echo $punch->employee->name, ' ', $punch->state;

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->signInStaff($rid, ['method' => 'pin', 'secret' => $pin]);
} catch (ApiError $e) {
    if ($e->errorCode !== ErrorCode::STAFF_AMBIGUOUS) {
        throw $e;
    }
    $who = chooseEmployee($e->candidates);
    $api->signInStaff($rid, ['method' => 'pin', 'secret' => $pin, 'employee_id' => $who['id']]);
}
$preview = $api->post("/restaurants/$rid/receipts/preview", ['items' => $items]);
$api->post("/restaurants/$rid/receipts", $receipt, ['staff' => true]);   // bez přihlášení se ani neodešle
$api->signOutStaff();

Webová aplikace, kde objekt nepřežije požadavek, si token relace uloží sama a pošle ho volbou 'staff' => $token.

A web application where the object does not outlive the request stores the session token itself and sends it with 'staff' => $token.

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.

$api = new Client(clientId: 'muj-eshop', clientSecret: getenv('PROFIREST_CLIENT_SECRET'),
                  storage: new FileStorage(__DIR__ . '/../var/profirest.json'), storageKey: 'account-7');

// tlačítko „Připojit Profirest“ v administraci e-shopu
header('Location: ' . $api->authorizationUrl('https://eshop.example.cz/profirest/callback',
                                             'restaurants:read catalog:read orders:write'));

// zpětné volání /profirest/callback – ověří state a iss, vymění kód za tokeny
$connection = $api->completeAuthorization($_GET);
$restaurants = $api->all('/restaurants');

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' => 'web']]);

// ETag a If-Match
$r = $api->get("/customers/$id", ['withResponse' => true]);
$api->patch("/customers/$id", ['name' => 'Jana Nováková'], ['ifMatch' => $r->header('ETag')]);

// vlastní Idempotency-Key – opakované odeslání formuláře nevytvoří druhou objednávku
$order = $api->post("/restaurants/$rid/orders", $body, ['idempotencyKey' => 'order-' . $localId]);

// binární tělo a odpověď
$api->post("/restaurants/$rid/backups", file_get_contents('zaloha.zip'), ['contentType' => 'application/zip', 'timeout' => 120]);
$zip = $api->get("/restaurants/$rid/backups/$backupId/content", ['accept' => 'application/zip']);

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');                     // všechny položky
foreach ($api->pages('/restaurants/11/staff', ['query' => ['limit' => 50]]) as $page) {
    foreach ($page['data'] as $member) { /* … */ }
}

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->watchEvents([
    'restaurantId' => $rid,
    'types' => ['order.created', 'order.status_changed'],
    'onEvents' => function (array $events): void {
        foreach ($events as $event) {
            zpracuj($event);            // výjimka = kurzor se neposune a stránka přijde znovu
        }
    },
    'onReset' => fn() => nactiVseZnovu(),
    'onError' => fn(\Throwable $e) => error_log($e->getMessage()),
]);
$watcher->run();                        // proces v příkazové řádce (supervisor, systemd): živý proud, bez služby
                                        // dotazování; $watcher->isStreaming(), stop() ho ukončí
$api->watchEvents([/* … */])->once();   // nebo cron: jeden dotaz GET /v2/events

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("/restaurants/$rid/quotes", $quote);
} catch (\Profirest\Api\ApiError $e) {
    if ($e->errorCode === ErrorCode::VALIDATION_FAILED) {
        foreach ($e->errors as $f) { echo $f['pointer'], ': ', $f['message'], "\n"; }
    }
    error_log("Profirest {$e->errorCode} ({$e->requestId})");
}

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.

use Profirest\Api\Storage\LockingStorage;

final class DbStorage implements LockingStorage          // úložiště v databázi pro PHP-FPM a cron
{
    public function __construct(private \PDO $db) {}
    public function get(string $key): ?string
    {
        $q = $this->db->prepare('SELECT v FROM profirest_state WHERE k = ?');
        $q->execute([$key]);
        return $q->fetchColumn() ?: null;
    }
    public function set(string $key, string $value): void
    {
        $this->db->prepare('REPLACE INTO profirest_state (k, v) VALUES (?, ?)')->execute([$key, $value]);
    }
    public function remove(string $key): void
    {
        $this->db->prepare('DELETE FROM profirest_state WHERE k = ?')->execute([$key]);
    }
    public function withLock(string $name, callable $fn): mixed
    {
        $this->db->prepare('SELECT GET_LOCK(?, 30)')->execute([$name]);
        try { return $fn(); } finally { $this->db->prepare('SELECT RELEASE_LOCK(?)')->execute([$name]); }
    }
}

MemoryStorage (výchozí) vydrží do konce procesu, FileStorage zamyká flock na <soubor>.lock – soubor dejte mimo webroot.

MemoryStorage (default) lasts until the process ends, FileStorage locks with flock on <file>.lock – keep the file outside the web root.

Reference

Volby klienta

Client options

$api = new Client(baseUrl: …, clientId: …, storage: …);   // pojmenované parametry

Metody

Methods

Volby požadavku: query, body, contentType, idempotencyKey (false = bez klíče), ifMatch, staff ('auto', true, false, token), retries, timeout, accept, headers, auth (false = bez tokenu), withResponse (vrátí Response se stavem a hlavičkami).

Request options: query, body, contentType, idempotencyKey (false = no key), ifMatch, staff ('auto', true, false, a token), retries, timeout, accept, headers, auth (false = no token), withResponse (returns a Response with status and headers).

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