JavaScript · API v2

profirest-api.js

Klient Profirest API v2 pro JavaScript. Spáruje zařízení kódem, hlídá a obnovuje tokeny, přihlašuje zaměstnance PINem nebo čipem, opakuje, co opakovat má, a čte proud událostí. Jeden soubor bez závislostí pro prohlížeč, WebView na tabletech provozoven i Node.

The JavaScript client of Profirest API v2. It pairs devices by code, keeps the tokens fresh, signs employees in with a PIN or a card, repeats what is safe to repeat and reads the event feed. One file without dependencies for browsers, the WebViews on restaurant tablets and Node.

Verze

Version

1.1.0

Smlouva API

API contract

26.11.28

Velikost

Size

js 72 kB · gzip 18 kB / min.js 25 kB · gzip 9 kB

Prohlížeče

Browsers

Chrome/WebView 66+ · Safari 12.1+ · Firefox 57+

Node

18+

Starší prohlížeče s async/await (Chrome 55, Safari 11, Firefox 52) klient spustí, ale bez AbortController nemá časový limit ani rušení požadavků. Jednu obnovu tokenu napříč panely hlídá přes Web Locks (Chrome 69, Safari 15.4, Firefox 96); bez nich přes značku v úložišti (localStorage), která souběh dvou panelů zúží na desítky milisekund – aplikaci partnera v takovém prohlížeči přesto raději otevírejte v jednom panelu.

Older browsers with async/await (Chrome 55, Safari 11, Firefox 52) run the client, but without AbortController it has no timeout and cannot cancel requests. It guards one token refresh across tabs with Web Locks (Chrome 69, Safari 15.4, Firefox 96); without them with a mark in the storage (localStorage) that narrows a race of two tabs to tens of milliseconds – still prefer one tab for a partner application in such a browser.

Za vás udělá to, co jinak musí každá aplikace napsat a hlavně nezapomenout: Idempotency-Key u každého POST a stejný při opakování, Retry-After, obnovu tokenu jen jednou i při několika souběžných požadavcích a v několika panelech prohlížeče, hlavičku Profirest-Staff-Token a chyby podle katalogu. Cesty, těla a odpovědi jsou přesně podle reference API – klient nic nepřejmenovává.

It does what every application would otherwise have to write and, above all, not forget: an Idempotency-Key on every POST, the same one on a retry, Retry-After, refreshing the token only once even with several parallel requests and several browser tabs, the Profirest-Staff-Token header and errors from the catalog. Paths, bodies and responses are exactly as in the API reference – the client renames nothing.

Kde ho vzít

Getting the file

API ho servíruje samo, s Access-Control-Allow-Origin: *, takže ho načtete z jakékoli stránky:

The API serves it itself, with Access-Control-Allow-Origin: *, so any page can load it:

<script src="https://api.mujprofirest.cz/v2/profirest-api.min.js"></script>
<script>
  var api = new ProfirestApi({ clientId: 'profirest-dochazka' });
</script>

Aplikace na tabletech by měly mít kopii souboru u sebe, aby nastartovaly i bez sítě, a s novou verzí ji vyměnit. V Node soubor stáhněte k aplikaci a načtěte přes require (je to UMD: v prohlížeči definuje window.ProfirestApi, v Node module.exports).

Applications on tablets should keep a copy of the file so they start without a network, and replace it with a new version. In Node, download the file next to your application and require it (it is UMD: in a browser it defines window.ProfirestApi, in Node module.exports).

const ProfirestApi = require('./profirest-api.js');
const api = new ProfirestApi({ clientId: 'your-client-id', storage: fileStorage('profirest.json') });

Rychlý start

Quick start

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 a zařízení si samo vyzvedne tokeny. Zařízení pak pracuje jen pro jednu provozovnu a vedoucí ho může kdykoli odpárovat.

Registers, kitchen displays, attendance terminals and courier phones connect with a code (RFC 8628). The device shows a code, a manager enters it in the administration and the device picks up its tokens itself. The device then works for one restaurant only and the manager can unpair it at any time.

var api = new ProfirestApi({
  clientId: 'profirest-dochazka',
  onUnpaired: function () { showPairing(); }   // vedoucí zařízení odpároval
});

async function start() {
  if (!api.isPaired()) {
    var pairing = await api.pair({
      scope: 'restaurants:read staff:read staff:authenticate attendance:read attendance:punch',
      deviceName: 'Píchačka u vchodu',             // vedoucí název může změnit
      appVersion: '2.0.0'
    });
    showCode(pairing.userCode, pairing.verificationUriComplete);
    try {
      await pairing.connected;                     // čeká, než vedoucí kód potvrdí
    } catch (e) {
      // e.error: 'access_denied' (vedoucí odmítl) nebo 'expired_token' (10 minut bez potvrzení) – nabídněte nový kód
      return showPairingFailed(e.error);
    }
  }
  if (!api.restaurantId) {
    await api.connection();                        // provozovnu zapamatuje
  }
  showTerminal(api.restaurantId);
}

var api = new ProfirestApi({
  clientId: 'profirest-dochazka',
  onUnpaired: function () { showPairing(); }   // a manager unpaired the device
});

async function start() {
  if (!api.isPaired()) {
    var pairing = await api.pair({
      scope: 'restaurants:read staff:read staff:authenticate attendance:read attendance:punch',
      deviceName: 'Entrance terminal',             // the manager can rename it
      appVersion: '2.0.0'
    });
    showCode(pairing.userCode, pairing.verificationUriComplete);
    try {
      await pairing.connected;                     // waits until the manager confirms the code
    } catch (e) {
      // e.error: 'access_denied' (refused) or 'expired_token' (10 minutes unconfirmed) – offer a new code
      return showPairingFailed(e.error);
    }
  }
  if (!api.restaurantId) {
    await api.connection();                        // remembers the restaurant
  }
  showTerminal(api.restaurantId);
}

Zařízení se ptá podle interval ze serveru (5 s), po slow_down o 5 s déle a výpadek sítě přečká, dokud kód platí; aktuální odstup ukazuje pairing.interval. Když člověk obrazovku s kódem opustí, zavolejte pairing.cancel() – přijde-li potvrzení v dotazu, který už běží, zařízení je spárované a connected se splní. scope smí obsahovat jen oprávnění, která Profirest vaší aplikaci povolil.

The device polls at the server's interval (5 s), 5 s slower after slow_down, and rides out a network outage while the code is valid; pairing.interval shows the current gap. When the person leaves the code screen, call pairing.cancel() – if the confirmation arrives in a poll already running, the device is paired anyway and connected resolves. scope may hold only permissions Profirest allowed your application.

Docházkový terminál

Attendance terminal

Na terminálu se nikdo nepřihlašuje – každé píchnutí nese PIN nebo čip. id píchnutí vznikne na zařízení ve chvíli, kdy člověk píchl (ProfirestApi.uuid() dává UUIDv7 řazené podle času), a stejné id server nikdy nezapíše dvakrát. Chyby se rozlišují podle e.code:

Nobody signs in on a terminal – every punch carries a PIN or a card. The punch id is made on the device when the person punched (ProfirestApi.uuid() gives a time-ordered UUIDv7), and the server never records the same id twice. Errors differ by e.code:

async function punch(type, pin, employeeId) {
  var body = {
    id: ProfirestApi.uuid(),
    type: type,                                    // clock_in, clock_out, break_start, break_end
    credential: { method: 'pin', secret: pin, employee_id: employeeId || null }
  };
  try {
    var r = await api.post('/restaurants/' + api.restaurantId + '/attendance/punches', body);
    showDone(r.employee.name, r.state);            // state: working, on_break, off
  } catch (e) {
    switch (e.code) {
      case 'staff_ambiguous':                      // stejný PIN má víc lidí: e.candidates = [{id, name}]
        return chooseEmployee(e.candidates, function (id) { punch(type, pin, id); });
      case 'staff_credentials_invalid': return showWrongPin();
      case 'staff_locked': return showLocked(e.retryAfter);           // sekundy do odemčení
      case 'attendance_state_conflict': return showMessage(e.title); // např. odchod bez příchodu
      case 'network_error':
      case 'timeout': return saveOffline(body);   // pošle se později dávkou
      default: return showMessage(e.title);
    }
  }
}

async function punch(type, pin, employeeId) {
  var body = {
    id: ProfirestApi.uuid(),
    type: type,                                    // clock_in, clock_out, break_start, break_end
    credential: { method: 'pin', secret: pin, employee_id: employeeId || null }
  };
  try {
    var r = await api.post('/restaurants/' + api.restaurantId + '/attendance/punches', body);
    showDone(r.employee.name, r.state);            // state: working, on_break, off
  } catch (e) {
    switch (e.code) {
      case 'staff_ambiguous':                      // several people share the PIN: e.candidates = [{id, name}]
        return chooseEmployee(e.candidates, function (id) { punch(type, pin, id); });
      case 'staff_credentials_invalid': return showWrongPin();
      case 'staff_locked': return showLocked(e.retryAfter);           // seconds until unlocked
      case 'attendance_state_conflict': return showMessage(e.title); // e.g. leaving without arriving
      case 'network_error':
      case 'timeout': return saveOffline(body);   // sent later in a batch
      default: return showMessage(e.title);
    }
  }
}

Bez sítě

Without a network

Píchnutí uložte i s id a časem occurred_at a pošlete později dávkou (nejvýš 100). Každá položka má vlastní výsledek. Offline záznamy přijme jen provozovna, která je v nastavení docházky povoluje, a jen do nastaveného stáří. Frontu držte jen na zařízení – nese PINy.

Store the punch with its id and occurred_at and send it later in a batch (at most 100). Every item gets its own result. Offline records are accepted only when the restaurant allows them in its attendance settings, and only up to the age set there. Keep the queue on the device only – it carries PINs.

function saveOffline(body) {
  queue.push(Object.assign({ occurred_at: new Date().toISOString() }, body));
}

async function sendQueue() {
  var batch = queue.slice(0, 100);
  var r = await api.post('/restaurants/' + api.restaurantId + '/attendance/punches/batch', { items: batch });
  r.results.forEach(function (item) {
    if (item.status === 'rejected' && item.retryable) return;          // e.g. staff_locked: send again later
    if (item.status === 'rejected') reportToManager(item.id, item.problem);
    removeFromQueue(item.id);                                          // created, duplicate or final rejection
  });
}

Pokladna

Register

Zaměstnanec se přihlásí PINem nebo čipem a klient pak posílá jeho token v hlavičce Profirest-Staff-Token u každého požadavku sám. Ceny, DPH i zaokrouhlení počítá server: náhled vrátí, co zaplatit, účtenka se vystaví se stejnými položkami. Účtenka má vlastní id ze zařízení, takže opakování nikdy nevystaví druhou. EET 2.0 eviduje server, zařízení certifikát nepotřebuje.

An employee signs in with a PIN or a card and the client then sends their token in the Profirest-Staff-Token header with every request by itself. The server computes prices, VAT and rounding: the preview returns what to pay, the receipt is issued with the same items. A receipt carries its own id made on the device, so a retry never issues a second one. The server records EET 2.0; the device needs no certificate.

var rid = api.restaurantId;
await api.signInStaff(rid, { method: 'pin', secret: pin });   // 409 staff_ambiguous → e.candidates, as on the terminal

var items = [{ product_id: '4567', quantity: 2 }];
var preview = await api.post('/restaurants/' + rid + '/receipts/preview', { items: items });

var receipt = await api.post('/restaurants/' + rid + '/receipts', {
  id: ProfirestApi.uuid(),
  number: nextReceiptNumber(),
  issued_at: new Date().toISOString(),
  items: items,
  payments: [{ method: 'cash', amount: preview.cash_amount_due }]
});

await api.signOutStaff();

Zálohu místní databáze pošlete jako binární tělo; stažení vrací Blob:

Send a backup of the local database as a binary body; a download returns a Blob:

await api.post('/restaurants/' + rid + '/backups', zipBlob, {
  contentType: 'application/zip',
  query: { type: 'automatic', app_version: '3.4.1' },
  timeout: 120000
});
var blob = await api.get('/restaurants/' + rid + '/backups/' + backupId + '/content', { accept: 'application/zip' });

Kuchyňský displej

Kitchen display

Displej čte proud událostí a po každé změně si tabuli načte znovu. watchEvents si kurzor pamatuje v úložišti, takže po restartu pokračuje tam, kde skončil; po 30 dnech nečinnosti zavolá onReset. Změny ze staré kuchyně a pokladen v1 do proudu nejdou – tabuli proto načítejte i v pravidelném intervalu.

The display reads the event feed and reloads its board after every change. watchEvents keeps the cursor in storage, so after a restart it continues where it stopped; after 30 days of inactivity it calls onReset. Changes from the old kitchen app and v1 registers do not reach the feed – reload the board on a timer as well.

var watcher = api.watchEvents({
  restaurantId: api.restaurantId,
  types: ['kitchen.ticket_updated', 'kitchen.shift_closed', 'order.created', 'order.status_changed'],
  interval: 3000,
  onEvents: function (events) { return reloadBoard(); },     // may return a Promise
  onReset: function () { return reloadBoard(); },
  onError: function (e) { showConnection(e.code !== 'network_error' && e.code !== 'timeout'); }
});
setInterval(reloadBoard, 30000);
// watcher.stop() when leaving the screen

Aplikace partnera v prohlížeči

A partner application in a browser

E-shop nebo jiná aplikace partnera se připojuje se souhlasem majitele restaurace (authorization code s PKCE). V prohlížeči je to veřejný klient bez tajemství: adresu pro přesměrování i původ stránky (CORS) musí mít Profirest u vašeho klienta zaregistrované. Klient vyrobí code_verifier a state, uloží je do sessionStorage a po návratu ověří state i iss.

An e-shop or another partner application connects with the restaurant owner's consent (authorization code with PKCE). In a browser it is a public client without a secret: Profirest must have your redirect URI and the page's origin (CORS) registered for your client. The client makes the code_verifier and state, keeps them in sessionStorage and checks state and iss on the way back.

// one instance per connected account: accountId is the account in YOUR system (the same on the callback page)
var api = new ProfirestApi({ clientId: 'your-client-id', storageKey: 'account-' + accountId });

// the "Connect Profirest" button
location.href = await api.authorizationUrl({
  redirectUri: 'https://shop.example/profirest/callback',
  scope: 'restaurants:read catalog:read orders:write orders:read'
});

// on https://shop.example/profirest/callback
var connection = await api.completeAuthorization();   // reads code, state and iss from location.href
var restaurants = await api.all('/restaurants');

Na serveru (Node)

On a server (Node)

Aplikace s vlastním serverem je důvěrný klient: má clientSecret, který klient posílá jako HTTP Basic. V prohlížeči ho konstruktor odmítne. Tokeny ukládejte do vlastního úložiště – stačí objekt s getItem, setItem a removeItem. Pro každý připojený účet použijte vlastní instanci s vlastním storageKey odvozeným z ID účtu ve vašem systému (viz Jedna instance = jedno připojení). Na serveru leží v úložišti klienta pod tímto klíčem i rozpracovaný souhlas (<storageKey>:pkce), takže se společným klíčem by si dva souhlasy běžící současně přepsaly state i v různých prohlížečích.

An application with its own server is a confidential client: it has a clientSecret, which the client sends as HTTP Basic. In a browser the constructor refuses it. Store the tokens in your own storage – any object with getItem, setItem and removeItem will do. Use one instance per connected account with its own storageKey derived from the account ID in your system (see One instance = one connection). On a server the consent in progress (<storageKey>:pkce) sits under this key in the client's storage too, so with a shared key two consents running at the same time would overwrite each other's state even in different browsers.

const fs = require('fs');
const ProfirestApi = require('./profirest-api.js');

function fileStorage(path) {
  let data = {};
  try { data = JSON.parse(fs.readFileSync(path, 'utf8')); } catch (e) { /* first start */ }
  const save = () => fs.writeFileSync(path, JSON.stringify(data), { mode: 0o600 });
  return {
    getItem: (k) => (k in data ? data[k] : null),
    setItem: (k, v) => { data[k] = String(v); save(); },
    removeItem: (k) => { delete data[k]; save(); }
  };
}

const api = new ProfirestApi({
  clientId: 'your-client-id',
  clientSecret: process.env.PROFIREST_CLIENT_SECRET,
  storage: fileStorage('/var/lib/shop/profirest.json'),
  storageKey: 'account-7'
});

Připojení majitele proběhne stejně jako v prohlížeči: authorizationUrl() při přesměrování a completeAuthorization(adresaZpětnéhoVolání) na zpětném volání. code_verifier je mezitím v úložišti klienta. Když už tokeny máte odjinud, předejte accessToken: klient ho pošle a neobnovuje.

Connecting an owner works as in a browser: authorizationUrl() for the redirect and completeAuthorization(callbackUrl) on the callback, with the code_verifier kept in the client's storage meanwhile. When you already have tokens from elsewhere, pass accessToken: the client sends it and never refreshes it.

Jak to funguje

How it works

Požadavky

Requests

Cesty se píšou relativně k /v2, přesně jako v referenci. Objekt v těle se pošle jako JSON; Blob, ArrayBuffer nebo pole bajtů jako binární tělo s contentType. Odpověď JSON přijde jako objekt, 204 jako null a jiný obsah jako Blob.

Paths are relative to /v2, exactly as in the reference. An object body is sent as JSON; a Blob, ArrayBuffer or byte array as a binary body with contentType. A JSON answer comes back as an object, 204 as null and any other content as a Blob.

var catalog = await api.get('/restaurants/11/catalog', { query: { channel: 'pos' } });
var quote = await api.post('/restaurants/11/quotes', { fulfillment: { type: 'pickup' }, items: items });

// ETag and Location: withResponse
var r = await api.get('/customers/' + id, { withResponse: true });
await api.patch('/customers/' + id, { name: 'Jana Nováková' }, { ifMatch: r.headers.get('ETag') });

// nothing changed since the last read: 304 comes back as null (withResponse: status 304)
var fresh = await api.get('/restaurants/11/catalog', { ifNoneMatch: catalogEtag, withResponse: true });
if (fresh.status !== 304) { catalog = fresh.data; catalogEtag = fresh.headers.get('ETag'); }

// your own Idempotency-Key, e.g. kept with an order in your database
await api.post('/restaurants/11/orders', order, { idempotencyKey: order.localId });

U POST klient přidá Idempotency-Key sám (UUIDv7) a při automatickém opakování pošle stejný. Když požadavek po chybě opakujete vy, třeba po restartu aplikace, předejte vlastní klíč uložený u záznamu – jen tak server pozná, že jde o tentýž požadavek. Účtenky a píchnutí se místo klíče řídí vlastním id v těle.

On a POST the client adds an Idempotency-Key itself (UUIDv7) and sends the same one on an automatic retry. When you repeat a request yourself, for example after the application restarted, pass your own key stored with the record – only then does the server know it is the same request. Receipts and punches go by their own id in the body instead of the key.

// 1. before sending: create the key and store it with the order in your database
order.idempotencyKey = ProfirestApi.uuid();
await saveOrder(order);
// 2. send it; 3. after a restart send the stored order again – the same key and the same body
var created = await api.post('/restaurants/11/orders', order.body, { idempotencyKey: order.idempotencyKey });

Chyby

Errors

Každá chyba API přijde jako ProfirestApi.ApiError s kódem z katalogu chyb. Rozhodujte se podle code, ne podle HTTP stavu – kódy se nikdy nemění. title je česky nebo anglicky podle volby language.

Every API error comes as a ProfirestApi.ApiError with a code from the error catalog. Branch on code, not on the HTTP status – codes never change. title is Czech or English according to the language option.

Kódy jen z klienta

Client-only codes

Chyby párování a připojení partnera jsou ProfirestApi.OAuthError s kódem OAuth v error (access_denied, expired_token, invalid_request…) a popisem v description.

Errors of pairing and of connecting a partner are ProfirestApi.OAuthError with the OAuth code in error (access_denied, expired_token, invalid_request…) and the text in description.

Opakování a výpadky

Retries and outages

Klient zopakuje jen to, co opakovat jde, nejvýš retrieskrát (výchozí 3), se stejným tělem a Idempotency-Key. Odstup se zdvojnásobuje od retryDelay (1 s) do 30 s a má rozptyl ±25 %, aby se zařízení po výpadku nevrátila všechna najednou. Retry-After má přednost; delší než maxRetryWait (30 s) klient nečeká a vrátí chybu s retryAfter.

The client repeats only what can be repeated, at most retries times (3 by default), with the same body and Idempotency-Key. The delay doubles from retryDelay (1 s) up to 30 s with ±25 % jitter, so devices do not all come back at once after an outage. Retry-After wins; longer than maxRetryWait (30 s), the client does not wait and returns the error with retryAfter.

Každý pokus má limit timeout (30 s) na celou odpověď, i na přečtení těla. Požadavek zrušíte přes signal (AbortController); zrušený požadavek se neopakuje a vyhodí AbortError.

Every attempt has a timeout (30 s) for the whole answer, reading the body included. Cancel a request with signal (AbortController); a cancelled request is not repeated and throws an AbortError.

Tokeny a úložiště

Tokens and storage

Access token platí 30 minut. Klient ho obnoví minutu před koncem (refreshMargin), a když server odpoví 401 invalid_token dřív, obnoví ho a požadavek jednou zopakuje. Souběžné požadavky čekají na jednu obnovu; v prohlížeči i mezi panely přes Web Locks, a když panel obnoví token, ostatní použijí jeho.

An access token lives 30 minutes. The client refreshes it a minute before it ends (refreshMargin), and when the server answers 401 invalid_token earlier, it refreshes and repeats the request once. Parallel requests wait for one refresh; in a browser also across tabs through Web Locks, and when one tab refreshed, the others use its token.

Spárované zařízení smí obnovu se stejným refresh tokenem zopakovat, dokud nový refresh token nepoužije, nejdéle 24 hodin – když se odpověď ztratí ve výpadku Wi-Fi, zařízení zůstane spárované. Mimo tuto lhůtu a u aplikací v prohlížeči ukončí opětovné použití celé připojení. Když obnova selže s invalid_grant (zařízení někdo odpároval nebo refresh token vypršel po 90 dnech bez použití), klient tokeny smaže, zavolá onUnpaired a požadavky končí not_paired. invalid_client a unauthorized_client jsou přechodné (třeba zámek po chybných tajemstvích) – tokeny zůstanou a chyba přijde volajícímu.

A paired device may repeat a refresh with the same refresh token until it has used the new refresh token, at most 24 hours – when the answer is lost in a Wi-Fi outage, the device stays paired. Outside this window, and for applications in a browser, reuse ends the whole connection. When a refresh fails with invalid_grant (someone unpaired the device or the refresh token expired after 90 days unused), the client deletes the tokens, calls onUnpaired and requests end with not_paired. invalid_client and unauthorized_client are temporary (for example a lock after wrong secrets) – the tokens stay and the error goes to the caller.

Vše leží pod jedním klíčem profirest-api:<clientId> (volba storageKey) v localStorage; bez něj (anonymní okno) jen v paměti do zavření stránky. Token zaměstnance se neukládá nikdy. api.unpair() vše zapomene a refresh token na serveru zneplatní.

Everything sits under one key profirest-api:<clientId> (the storageKey option) in localStorage; without it (a private window) only in memory until the page closes. The staff token is never stored. api.unpair() forgets everything and revokes the refresh token on the server.

Přihlášený zaměstnanec

Signed-in employee

signInStaff() vrátí relaci z POST …/staff-sessions a token si drží jen v paměti. Volba staff u požadavku říká, co s ním: 'auto' (výchozí) ho pošle, když je někdo přihlášený, true přihlášení vyžaduje, false ho nepošle a řetězec pošle jako token. Relace vyprší po nečinnosti (idle_timeout_seconds, každý požadavek ji prodlouží) a nejpozději v max_expires_at. Když server odpoví staff_session_expired nebo staff_session_required, nebo relace skončí podle hodin zařízení, klient relaci zapomene a zavolá onStaffExpired. staff: true funguje jen u adres API – u cizí adresy je to chyba.

signInStaff() returns the session from POST …/staff-sessions and keeps the token in memory only. The staff option of a request says what to do with it: 'auto' (default) sends it when somebody is signed in, true requires a sign-in, false leaves it out and a string is sent as the token. The session expires after inactivity (idle_timeout_seconds, every request extends it) and at max_expires_at at the latest. When the server answers staff_session_expired or staff_session_required, or the session ends by the clock of the device, the client forgets the session and calls onStaffExpired. staff: true works only for addresses of the API – elsewhere it is an error.

try {
  await api.signInStaff(rid, { method: 'card', secret: cardNumber });
} catch (e) {
  if (e.code === 'staff_locked') return showLocked(e.retryAfter);
  throw e;
}
api.staff;   // { employee: { id, name, roles, … }, restaurantId, expiresAt: Date|null, maxExpiresAt: Date|null } or null

Proud událostí

Event feed

watchEvents() čte živý proud GET /v2/events/stream (Server-Sent Events), když služba proudu běží – události přijdou pár sekund po změně bez dotazování a po výpadku spojení se doženou podle kurzoru (Last-Event-ID). Když proud neběží (503, starší server, prostředí bez čtení odpovědi po kouscích), čte GET /v2/events dokola a o proud se pokusí znovu později; kurzor je v obou stejný. isStreaming() řekne, co právě běží.

Kurzor posune a uloží až po úspěšném onEvents – když obsluha vyhodí chybu, stejné události přijdou znovu (aspoň jednou), proto je zpracovávejte tak, aby opakování nevadilo. Plnou stránku dožene hned, jinak čeká interval. Bez uloženého kurzoru začne na konci proudu (staré události nečte). Při chybě čeká déle, až 60 s; ztráta spárování čtení ukončí.

watchEvents() reads the live stream GET /v2/events/stream (Server-Sent Events) while the stream service runs – events come a few seconds after the change without polling, and after a lost connection they are caught up by the cursor (Last-Event-ID). When the stream is not running (503, an older server, an environment that cannot read a response in pieces), it reads GET /v2/events over and over and tries the stream again later; the cursor is the same in both. isStreaming() tells which one runs.

It moves and stores the cursor only after onEvents succeeded – when your handler throws, the same events come again (at least once), so handle them so that a repeat does no harm. A full page is caught up at once, otherwise it waits interval. Without a stored cursor it starts at the end of the feed (no old events). After an error it waits longer, up to 60 s; losing the pairing stops it.

Seznamy po stránkách

Paged lists

Seznamy vrací { data, next_cursor }. all() projde všechny stránky a vrátí položky, pages() dává stránky po jedné – v prohlížečích s for await i v cyklu.

Lists return { data, next_cursor }. all() walks every page and returns the items, pages() yields the pages one by one – in browsers with for await also in a loop.

var staff = await api.all('/restaurants/11/staff', { query: { limit: 100 } });

for await (var page of api.pages('/restaurants/11/attendance/presence')) {
  render(page.data);
}

Reference

Volby klienta

Client options

var api = new ProfirestApi(options);

Metody

Methods

Volby požadavku

Request options

Bezpečnost

Security

• Tokeny v localStorage přečte každý skript na stránce. Na stránky zařízení nevkládejte cizí skripty (reklamy, měření) a nastavte Content-Security-Policy.
• clientSecret patří jen na server. Konstruktor ho v prohlížeči odmítne.
• Token zaměstnance zůstává jen v paměti a končí s nečinností. PIN klient nikam neukládá – posílá ho jen v těle požadavku přes HTTPS.
• Tokeny zařízení patří zařízení a jen jeho provozovně. Ztracené nebo ukradené zařízení odpárujte v administraci – jeho tokeny přestanou platit hned.
• Offline fronta docházkového terminálu nese PINy; držte ji jen na zařízení a po odeslání ji smažte.

• Any script on the page can read tokens in localStorage. Do not put third-party scripts (ads, analytics) on device pages and set a Content-Security-Policy.
• clientSecret belongs on a server only. The constructor refuses it in a browser.
• The staff token stays in memory only and ends with inactivity. The client never stores a PIN – it only sends it in the request body over HTTPS.
• Device tokens belong to the device and its restaurant only. Unpair a lost or stolen device in the administration – its tokens stop working at once.
• The offline queue of an attendance terminal carries PINs; keep it on the device only and delete it once sent.

Změny

Changes