Konektory

Konektor je vaše vlastní aplikace napojená na API jenQR. Umí tři věci: vystavit platbu a dostat k ní variabilní symbol, přečíst si, které platby čekají na zaplacení, a nahlásit k nim přijatou částku.

K čemu slouží dnes: je to doplněk k oznámení banky nad tímtéž připojeným účtem. Hlásí tytéž platby, jen se o nich obvykle dozví dřív, takže zaplaceno naskočí rychleji. Nic jiného než platby na připojený účet přes něj hlásit nemůžete: hotovost a karta patří do pokladny, ne sem. Píšeme to natvrdo schválně, protože na tom stojí i to, jak jenQR obě čísla porovnává (níže).

Kdo ho napíše, je na vás: skript na vašem serveru, pokladní systém, účetní program, aplikace v telefonu. jenQR od něj přijme jen číslo platby a přijatou částku, nic dalšího.

K čemu je

Základ je pořád stejný: banka pošle jenQR oznámení o příchozí platbě a jenQR z něj pozná, že je QR kód zaplacený (kapitola První kroky). Oznámení chodí zpravidla do 15 sekund od připsání (Raiffeisenbank) nebo do 5 sekund (Fio). Konektor je doplněk pro tři případy:

Rychlejší potvrzení. Konektor nahlásí platbu, jakmile o ní ví, a jenQR ji označí zaplacenou v tom okamžiku; zelená obrazovka pak naskočí dřív, než dorazí oznámení.
Provozovna bez oznámení. Když si zasílání oznámení v bance nastavit nechcete nebo nemůžete, potvrzuje platby jen konektor. Pak zapněte přepínač Konektor potvrzuje i vstupenky a webhooky (níže).
Vystavování z vlastního systému. Konektor platby i vystavuje, takže přes něj jde napojit pokladnu nebo e-shop celý, ne jen potvrzování.

QR kód míří vždy na účet, který má provozovna připojený; jiné číslo účtu z API zadat nejde. Jedna provozovna = jeden účet, takže kdo chce přijímat na dva, založí si dvě provozovny (klidně „Firma Fio" a „Firma RB").

Do telefonu na tomhle rozhraní chystáme i vlastní pokladní aplikaci.

Klíč konektoru

Správce v nabídce provozovny otevře Konektory a vytvoří klíč; začíná jq_conn_ a zobrazí se jen jednou. Klíč umí vystavit platbu, číst otevřené platby a hlásit k nim přijaté částky. Klíč e-shopu (kapitola API pro e-shopy) umí jen vystavit a číst; potvrzovat nemůže. O každém novém klíči dostanou všichni správci provozovny e-mail. Klíč se nemaže, jen deaktivuje; sloupec Naposledy se ozval ukazuje poslední čtení seznamu nebo hlášení (vystavení platby se nepočítá).

Dávejte ho jen aplikaci, které věříte: kdo ho má, může v jenQR označit platbu za zaplacenou. A oprávnění, které té aplikaci vydáte ve své bance, omezte tak, aby z něj šlo jen číst a nešlo zaplatit. Přihlášení do banky si nechte u sebe; jenQR ho nechce a nemá kam uložit.

Rozhraní

Vystavení platby je stejné jako u e-shopu (kapitola API pro e-shopy): POST s částkou, odpověď nese id, vs, spayd pro QR kód a payment_url. K tomu má konektor dvě další volání:

GET /api/v1/payment_requests
Authorization: Bearer jq_conn_…

{ "open": [ { "id": 123, "vs": "1000000123", "amount": 250.0, "received_amount": 0.0,
              "status": "pending", "created_at": "…", "expires_at": "…",
              "connector_received_total": 0 } ],
  "truncated": false, "server_time": "…" }

PATCH /api/v1/payment_requests/123
{ "received_total": 25000, "paid_at": "2026-08-25T14:02:31+02:00" }

→ { "id": 123, "accepted": true, "status": "paid",
    "received_amount": 250.0, "final": false }

Pozor na jednotky. amount a received_amount jsou v korunách, received_total a connector_received_total v haléřích (250 Kč = 25000). jenQR pracuje jen v korunách českých, proto se u částek měna neposílá.

Seznam obsahuje čekající QR kódy a ještě hodinu ty, které mezitím vypršely, byly zrušené nebo odepsané: na ty pořád může dorazit pozdní platba, stejně jako u oznámení. Krátce v něm zůstanou i platby, které už potvrdilo oznámení banky, ať je konektor stihne potvrdit taky a jenQR pozná, že mlčí, místo aby si myslel, že je neviděl. Pořadí neřešte, žádné negarantujeme; jen když by plateb bylo přes 200, odřízne se konec seznamu a odpověď má truncated: true. U každé platby je i connector_received_total: součet, který k ní jenQR od konektoru zatím zná.

Hlášení nese číslo požadavku v adrese a v těle received_total: kumulativní součet k dané platbě, tedy všechno, co k ní zatím přišlo, v haléřích. Ne přírůstek od minula. Volitelně paid_at, čas platby podle konektoru (ISO 8601); čas přijetí hlášení si jenQR ukládá vždy sám. Nic dalšího: stav (zaplaceno, částečně zaplaceno) si jenQR dopočítá z částky a jiné pole v těle odmítne (422 unknown_keys). Opakované nebo zpožděné hlášení nic nezapočítá dvakrát: stejný součet podruhé nic nezmění, nižší součet vrátí accepted: false s důvodem total_lower a platba, na kterou už peníze přijít nemohou, closed. Seznam se čte nejvýš 60× za minutu na klíč a hlášení se přijímá nejvýš pětkrát za sekundu; obojí je jen strop mimo obecný limit 120 volání za minutu, žádné zdržení. Rytmus si konektor určuje sám.

Zaplaceno je v okamžiku přijetí hlášení: naskočí zelená obrazovka a vystaví se doklad. Jestli v tu chvíli smíte expedovat, říká pole final v odpovědi (viz Dva kanály, jedno potvrzení níže); ve výchozím nastavení je false, dokud nedorazí oznámení banky.

Dva kanály, jedno potvrzení

Zaplacení může přijít z oznámení banky i z konektoru, klidně obojí k téže platbě. Protože oba kanály koukají na tentýž účet, jsou obě čísla součty téhož: všeho, co na daný variabilní symbol přišlo. Nejsou to přírůstky, které by se sčítaly, ale dva nezávislé odhady jednoho čísla, proto jenQR bere vyšší z nich. Když zákazník zaplatí dvakrát, napočítají obě strany obojí a maximum je správně; když se konektor doslechne o platbě dřív, je jeho číslo vyšší a oznámení ho za chvíli dorovná. Stav se nikdy nevrací zpět.

Zelená obrazovka, živý stav na platební stránce a doklad se ukážou po prvním potvrzení z kteréhokoli kanálu; nikdy dřív. U platby pak vidíte, kdo ji potvrdil a kdy (Potvrdil konektor v 14:02:31 · oznámení banky v 14:02:40).

Nevratné kroky (vydání vstupenek, webhook do e-shopu, u nás aktivace předplatného) ve výchozím nastavení čekají na oznámení banky: platí, až když oznámení potvrdí všechno, co se započítalo (i doplatek, který konektor nahlásil jako první). Kdo má klíč konektoru, může totiž platby potvrzovat; oznámení banky ověřujeme podle podpisu DKIM domény banky. Přepínač Konektor potvrzuje i vstupenky a webhooky na stránce Konektory tohle mění: po zapnutí se vstupenky a webhooky pouštějí hned po potvrzení konektorem. Zapněte ho, když provozovna oznámení nemá vůbec, nebo když věříte konektoru stejně jako bance. Změna se zapisuje do historie akcí.

Když oznámení nedorazí a je jasné, že už nepřijde (zrušené zasílání v bance, porucha), správce platbu uvolní ručně: v historii plateb ji otevře a klikne na Vydat vstupenky a odeslat zprávu. Nejdřív si v bankovnictví ověřte, že peníze opravdu dorazily; zpět to nevezmete. Kdo a kdy to udělal, jde do historie akcí.

V odpovědi API a ve webhooku k tomu patří pole notification_confirmed_at, connector_confirmed_at a final; e-shop si podle final pozná, jestli už smí expedovat.

Když se kanály rozejdou

Když oba kanály běží, mají se shodnout. jenQR je proto jednou za minutu porovná a když se dlouho rozcházejí, zapíše to k platbě do historie akcí, ať si to můžete sami prohlédnout. Stav platby se tím nemění a nic se nezahazuje; je to poznámka, ne zásah. Zapisuje se v obou směrech:

Konektor napřed a oznámení nikde. Konektor započítal víc, než oznámení banky do minuty potvrdilo. Buď se pokazilo zasílání oznámení v bance, nebo hlásí konektor něco, co na účet nedorazilo.
Oznámení přišlo a konektor mlčí. Platbu potvrdila banka, ale běžící konektor, který takové platby dřív hlásil, tuhle do několika minut nenahlásil. Typicky mu přestal fungovat přístup k tomu, odkud čerpá.

Ke každé platbě nejvýš jednou, ať z toho není lavina. Vidět je to rovnou v historii plateb: platba, která čeká na oznámení, má značku Čeká na oznámení a zmizí sama, jakmile oznámení dorazí; když přestane hlásit konektor, je nad seznamem pruh. Správci k tomu dostanou i e-mail, ten nejvýš jednou za hodinu na druh potíže: když se zasílání oznámení pokazí, jde o desítky plateb a jedna zpráva stačí.