Bankovní integrace¶

Podporovaní poskytovatelé¶

Aktivace poskytovatele¶

Aktivní poskytovatel se volí tlačítkem Aktivovat v záložce Integrace (POST /api/v1/admin/integrations/activate, tělo {"provider": "fio"}, prázdný řetězec = vypnout). Seznam povolených poskytovatelů se odvozuje z registru poskytovatelů (každý poskytovatel deklaruje svá konfigurační data), testovací dummy aktivovat nelze.

Při aktivaci se kontroluje úplnost nastavení (jen při aktivaci; již aktivní poskytovatel běží dál beze změny):

Při chybějících klíčích endpoint vrátí 400 s výčtem chybějících klíčů a nic nezapíše. Hodnoty se bere z prostředí i z databáze. Vypnutí ("") funguje vždy.

Nový poskytovatel se přidává novým souborem: RegisterProvider + RegisterProviderMeta (klíče, povinné klíče). Klíče poskytovatele musí být v registru konfigurace se skupinou payment a znovuinicializací platební služby — kontroluje to TestRegistryCompletenessPaymentProviders.

Fio Banka¶

Jednoduché napojení — stačí nastavit konfigurační klíče:

1. V administraci nastavte:

   • PAYMENT_CHECK_SERVICE_ENABLED = true
   • PAYMENT_CHECK_SERVICE_NAME = fio
   • FIO_URL = https://fioapi.fio.cz/v1
   • FIO_TOKEN = váš API token z Fio internetového bankovnictví

2. Cron úloha automaticky kontroluje transakce každých 11 minut.

Erste / Česká spořitelna (ČSAS)¶

Erste používá OAuth2 Authorization Code flow s krátkodobými přístupovými tokeny (5 min) a dlouhodobými obnovovacími tokeny (~180 dnů).

Předpoklady¶

1. Zaregistrujte se na Erste Developer Portal
2. Vytvořte aplikaci s přístupem k "Accounts" API
3. Nastavte redirect URI:
   • Produkce: https://vaše-doména.cz/bank/erste/redirectFromBank
   • Vývoj: http://localhost:8090/bank/erste/redirectFromBank
4. Poznamenejte si API Key, Client ID a Client Secret

Nastavení¶

1. V administraci nastavte:

   • PAYMENT_CHECK_SERVICE_ENABLED = true
   • PAYMENT_CHECK_SERVICE_NAME = erste
   • ERSTE_API_KEY = váš API key (WEB-API-key)
   • ERSTE_CLIENT_ID = váš OAuth2 Client ID
   • ERSTE_CLIENT_SECRET = váš OAuth2 Client Secret
   • ERSTE_IDP_URL = URL IDP (výchozí je sandbox)
   • ERSTE_API_URL = URL Accounts API (výchozí je sandbox)

2. Přejděte na záložku Integrace v administraci

3. Klikněte na Připojit u karty Erste

4. Budete přesměrováni na přihlašovací stránku banky. Přihlaste se a schvalte souhlas.

5. Po přesměrování zpět vyberte bankovní účet pro párování transakcí.

6. Hotovo! Cron úloha kontroluje transakce každých 11 minut.

Průběh OAuth2¶

Administrátor klikne "Připojit"
       |
       v
POST /api/v1/admin/bank/erste/connect
       |
       | Vrací auth_url
       v
Prohlížeč přesměruje na Erste IDP
(admin se přihlásí, schválí souhlas)
       |
       v
GET /bank/erste/redirectFromBank?code=...&state=...
       |
       | Ověří state (CSRF ochrana)
       | Vymění code za access_token + refresh_token
       | Uloží tokeny do kolekce oauth_tokens
       | Automaticky vybere účet, pokud existuje jen jeden
       v
Přesměrování na /admin?integration=erste&status=success

Správa tokenů¶

• Access token vyprší každých 5 minut (300 s)
• Refresh token vyprší za ~180 dnů (15 552 000 s)
• Tokeny se obnovují na požádání před každým API voláním
• Když refresh token vyprší → stav se změní na "expired" → administrátor musí znovu připojit
• Všechny tokeny uloženy v kolekci oauth_tokens

Sandbox vs Produkce¶

Řešení problémů¶

Jak párování funguje¶

Systém páruje platby podle:

1. Variabilní symbol (VS) — unikátní číslo dobíjení nebo nákupu
2. Specifický symbol (SS) — hash ID uživatele
3. Částka — musí přesně odpovídat

U plateb za relaci musí částka odpovídat amount_due (kolik zbývá doplatit), ne celé ceně relace. Pokud uživatel část uhradil kreditem, QR kód i párování počítají jen se zbytkem.

Po spárování se automaticky:

• Dokončí dobíjení → připíše se kredit
• Aktivuje produkt → začne platit
• Uhradí relace → do rozpisu se zapíše úhrada ve výši zbývající částky (kredit 300 + převod 518 → úhrada −518), amount_due klesne na 0 a final_price zůstane 818

Přehled bankovních transakcí¶

Všechny načtené bankovní transakce (Fio API, Erste API i e-mailová avíza) se ukládají do jednotné auditní tabulky bank transactions v administraci (Nastavení → Integrace → Bankovní transakce). Vidíte v ní, které platby se spárovaly s dobíjením / produktem / rezervací a které zůstaly nespárované.

Jak se transakce zapisují¶

1. Orchestrátor (automatický cron, ruční „Kontrola plateb" nebo „Skenovat nyní") načte transakce z banky a všechny je zapíše jako unmatched
2. Párovací engine (stejné sezení/dobíjení/produkty jako u API providerů) vyhledá spárovatelné transakce a upgraduje je na matched se záznamem, k čemu jsou připárované (matched_to_type + matched_to_id)
3. Překrývající se načtení (Fio vrací celé dny, opakované běhy) nikdy nevytvoří duplicitní řádek — deduplikace probíhá vždy

Deduplikace a ochrana peněz¶

• Dedup klíč = provider:external_id; když API external ID neobsahuje (některé banky), použije se fingerprint provider:datum:částka:vs:ss — stejná fyzická platba se tak vždy mapuje na stejný řádek
• Unique index na dedup_key — duplikát se nikdy nevytvoří
• Stav matched je finální: jednou spárovaná transakce se nikdy nevrátí na unmatched ani se nepřepáruje na jinou entitu. I když ji příští cron běh načte znovu jako „novou", stav zůstává matched

Tabulka v UI¶

Karta Bankovní transakce obsahuje sloupce Datum, Provider, Částka, VS, SS, Protistrana, Stav a „Připárováno k" s možností:

• Filtrování — podle provideru (fio / erste / email), podle stavu (matched / unmatched) a textové vyhledávání (VS, SS, external ID, protistrana)
• Řazení — kliknutím na hlavičku sloupce (Datum, Provider, Částka, VS, SS, Stav); výchozí řazení podle Datum (nejnovější nahoře)
• Stránkování — 50 záznamů na stránku s navigací « 1 z N »
• Detail — tlačítko Detail u řádku rozbalí podrobný pohled včetně raw_data (kompletní odpověď banky / rozparsované avízo)

API¶

• GET /api/v1/admin/bank/transactions — seznam (admin only). Podporuje page, perPage (max 200), provider, status, search a sort (povolené sloupce: first_seen_at, matched_at, created, amount, status, provider, vs, ss, date, external_id; neplatné hodnoty se tiše ignorují). Seznam raw_data nevrací
• GET /api/v1/admin/bank/transactions/{id} — detail (admin only), včetně raw_data

Kolekce bank_transactions má všechna pravidla přístupu prázdná (nil) — pod data se dostanete výhradně přes admin endpointy výše.

E-mailová (IMAP) platební avíza¶

Pro banky bez veřejného API (menší banky, stavební spořitelny) lze platby párovat z e-mailových avíz, která banka posílá na vaši schránku. Systém se připojí přes IMAP, načte e-maily, rozpozná banku podle odesílatele (a podle těla e-mailu), extrahuje variabilní symbol a částku a předá je stejnému párovacímu enginu jako API poskytovatelé.

Podporované e-mailové providery¶

Systémové parsery (registrované v kódu, v internal/bankemail/):

Banky, které v tabulce nejsou, lze přidat bez změny kódu jako vlastní regex providery (BANK_EMAIL_REGEX_PROVIDERS) — viz sekci níže.

Kdy použít¶

Předpoklady¶

1. E-mailová schránka, která přijímá avíza a podporuje IMAP
2. Přihlašovací údaje pro IMAP (heslo, případně aplikační heslo)
3. Avíza mají ve zprávě variabilní symbol a částku

Aktivace avíz u banky¶

Dřív než systém může avíza číst, musí je banka začít posílat na schránku, kterou systém sleduje. Postup se liší banka od banky a nastavuje se výhradně v internetovém bankovnictví dané banky (ne v Dverniku).

Česká spořitelna (csas)¶

Česká spořitelna zasílá avíza Přišla/Odešla platba na e-mail, který si vyberete v internetovém bankovnictví. Nastavení je dostupné pouze ve webové aplikaci — v mobilní aplikaci ho nejde aktivovat.

Postup:

1. Přihlaste se do webové aplikace České spořitelny
2. Vpravo nahoře klikněte na ikonu účtu → Nastavení
3. V nabídce zvolte Informační zprávy
4. V části Příchozí platby klikněte na Aktivovat
5. Vyberte účet, ke kterému se má avízo týkat
6. Vyberte e-mailovou adresu, na kterou se mají avíza zasílat, a doplňte ji
7. Uložte změny

Avíza pak chodí z adresy ceskasporitelna@csas.cz s předmětem Přišla platba a v těle mají vypsaný variabilní symbol (VS), specifický symbol (SS) a částku — systém je rozpoznává automaticky (parser csas). Systém podporuje přeposlané avíza.

Nastavení¶

Konfigurační klíče (záložka Integrace → karta Bankovní e-mail):

Postup:

1. Vyplňte host, port, TLS, adresu a heslo
2. Klikněte Otestovat připojení — ověří se TLS spojení i přihlášení
3. Klikněte Procházet složky — vyberte přesnou složku ze serveru
4. Klikněte Uložit
5. Klikněte Skenovat nyní pro okamžitou kontrolu
6. Automatická kontrola pak běží dle PAYMENT_CHECK_INTERVAL_MINUTES

Jak skenování funguje¶

1. Systém se připojí přes IMAP a najde e-maily, které ještě nebyly zpracovány
2. První sken projede celou schránku — najde se tak i stará avíza, která přišla ještě před nastavením integrace
3. Další skeny jsou inkrementální — systém si pamatuje pozici (UID kurzor + UIDVALIDITY) poslední zpracované zprávy a žádá server jen o novější e-maily. Schránka s tisíci starých zpráv se nikdy neprohledává celá znovu
4. Rozpozná banku podle odesílatele; když odesílatele nezná (např. přeposlané avízo), zkouší rozpoznat banku podle těla e-mailu
5. Z každého avíza extrahuje variabilní symbol, specifický symbol, částku a datum platby
6. Transakce se předá párovacímu enginu (stejný jako u API providerů)
7. Zpracované e-maily se pamatují podle Message-ID (a fallback hashe) v kolekci bank_email_messages, takže se stejné avízo nikdy nezpracuje dvakrát. E-maily se ze schránky nemazají — deduplikace probíhá v systému
8. Výsledek skenu se zobrazí v UI: kolik zpráv se naskenovalo, kolik bylo nových transakcí, kolik už bylo známých, kolik se nepodařilo rozpoznat (unmatched) a kolik selhalo při parsování (parse_failed)
9. V kartě Bankovní e-mail a v hlavičce karty Bankovní transakce je navíc trvalý souhrn: počet uložených e-mailů, pozice UID kurzoru a čas poslední úspěšné kontroly (PAYMENT_LAST_RUN_TIMESTAMP; „dosud neproběhla“, pokud kontrola ještě nikdy neproběhla)

Stavy zpráv (interní)¶

Rozlišení mezi rozpoznaným avízem a „nepořádkem" se stále ukládá interně:

Řešení problémů¶

Testování celého toku v UI¶

Nejjednodušší ověření, že e-mailové avízo opravdu dobije kredit:

1. Přihlaste se jako běžný uživatel → stránka Dobití → vyberte částku (např. 100 Kč) → vytvořte dobíjení
2. Poznamenejte si Variabilní symbol a Specifický symbol, které systém pro dobíjení vygeneroval (zobrazí se v detailu dobíjení spolu s QR)
3. Pošlete na schránku testovací e-mail — buď přes skutečný bankovní převod, nebo prostě odešlete e-mail s tělem avíza s těmito přesnými VS/SS a částkou na adresu, kterou systém sleduje přes IMAP
4. Administrace → Integrace → Bankovní e-mail → Skenovat nyní
5. Ověřte v odpovědi skenu, že se transakce načetla (VS/SS/částka sedí)
6. Uživatel → Dobití → dobíjení je Dokončeno a kredit se navýšil

Pro rychlé otestování parseru bez IMAP je k dispozici endpoint POST /api/v1/admin/bank/parser/test (tělo: sender, subject, date, text) — vrátí, který parser se chytil a co z e-mailu rozparsoval.

Přehled všech parserů (routingová kritéria + vzory polí) vrací GET /api/v1/admin/bank/email/parsers — stejná data, která se zobrazují v administraci v „Přehled parserů".

Vlastní regex providery (BANK_EMAIL_REGEX_PROVIDERS)¶

Pokud banka nemá systémový parser (Go kód v internal/bankemail/), lze ji přidat bez změny kódu — definováním vlastního regex providera v JSON. Vlastní regex providery mají přednost před systémovými parsery: sken nejdřív projde je (v pořadí v poli) a teprve když žádný nechytí, zkusí systémové parsery.

Kdy použít¶

Struktura JSON¶

JSON je pole objektů Provider. Povinné je jen code; ostatní pole mají smysl jen v kombinaci s regex parserem (parser_type: "regex"):

Všechny regex vzory jsou case-insensitive a odolné vůči diakritice (zkouší se originál i ASCII varianta bez diakritiky). Adresa odesílatele v sender_whitelist se porovnává přesně (case-insensitive), včetně podpory přeposlaných avíz.

Pole v field_patterns¶

Každý klíč = název pole, hodnota = regex s pojmenovanou skupinou (?P<value>...) (povinná). Nepovinné pole, jehož vzor nesedí, se prostě přeskočí — povinné je 5 klíčů, bez nichž Parse vrátí chybu: variable_symbol, amount, currency, posted_at, recipient_account.

* specific_symbol není v seznamu povinných klíčů pro Parse — ale pro párování plateb je praktická nutné ho definovat: akce (VS = datum, SS = čas začátku akce), dobíjení (VS+SS+částka) i produkty (VS+SS+částka) se párují pouze, když sedí VS i SS i částka.

Všech 10 systémových parserů má vzor specific_symbol vždy definovaný (viz přehled parserů v UI). U bank, jejichž avízo SS neuvádí, jde o „záložní" vzor, který na reálném e-mailu prostě nematchuje → SS zůstává prázdné a parser není rozbitý. To je záměr: bez SS se žádná platba nespáruje, takže při výpadku párování je první kontrola, jestli formát banky SS skutečně posílá.

recipient_account je povinný jako součást formátu avíza (Parse ho od konfigurovaného providera vyžaduje), ale jeho hodnota se nikdy neporovnává s účtem instalace — párování plateb pracuje čistě s VS + SS + částkou.

Příklad: ČSOB CEB jako vlastní regex provider¶

Avízo „CEB Info: Zaúčtování platby" (formát podle skutečného e-mailu, údaje jsou smyšlené):

Dne 6.8.2026 byla na účtu 987654321 zaúčtována transakce typu: Příchozí úhrada okamžitá.
Účet: 987654321, CZK, OBEC DOBROVICE
Částka: +250,00 CZK
Účet protistrany: 670100-1234567890/6210
Název protistrany: JAN NOVÁK
Variabilní symbol: 1234567890
Konstantní symbol: 1234
Specifický symbol: 1234567890
Zpráva příjemci: Platba test
Zůstatek na účtu po zaúčtování transakce: +125 000,00 CZK.

Odpovídající JSON do BANK_EMAIL_REGEX_PROVIDERS:

[{
  "code": "csob_ceb_regex",
  "name": "ČSOB CEB (regex)",
  "parser_type": "regex",
  "enabled": true,
  "sender_whitelist": "notification@csob.cz",
  "subject_pattern": "CEB\\s+Info\\s*:\\s*Za[úu]čtov[áa]n[íi]\\s+platby",
  "body_pattern": "Za[úu]čtov[áa]n[íi]\\s+transakce",
  "field_patterns": {
    "variable_symbol": "(?i)Variabilní\\s+symbol\\s*:\\s*(?P<value>[0-9]+)",
    "specific_symbol": "(?i)Specifický\\s+symbol\\s*:\\s*(?P<value>[0-9]+)",
    "constant_symbol": "(?i)Konstantní\\s+symbol\\s*:\\s*(?P<value>[0-9]+)",
    "amount": "(?i)Částka\\s*:\\s*(?P<value>[+\\-]?[0-9 ]+,[0-9]{2})",
    "currency": "(?i)Částka\\s*:\\s*[+\\-]?[0-9 ]+,[0-9]{2}\\s*(?P<value>[A-Z]{3})",
    "posted_at": "(?i)Dne\\s*(?P<value>\\d{1,2}\\.\\d{1,2}\\.\\d{4})",
    "recipient_account": "(?i)Účet\\s*:\\s*(?P<value>[0-9\\-]+)",
    "counterparty_account": "(?i)Účet\\s+protistrany\\s*:\\s*(?P<value>[0-9\\-]+\\/[0-9]{4})",
    "counterparty_name": "(?i)Název\\s+protistrany\\s*:\\s*(?P<value>[^\\r\\n]+)",
    "message": "(?i)Zpráva\\s+příjemci\\s*:\\s*(?P<value>[^\\r\\n]+)",
    "balance": "(?i)Zůstatek\\s+na\\s+účtu\\s+po\\s+zaúčtování\\s+transakce\\s*:\\s*(?P<value>[+\\-]?[0-9][0-9 .]*,[0-9]{2})",
    "direction": "(?i)transakce\\s+typu\\s*:\\s*(?P<value>Příchozí|Odchozí|Výdej|Výdaj)"
  }
}]

Poznámky k příkladu:

• sender_whitelist: "notification@csob.cz" — regex provider routuje podle přesné adresy odesílatele (na rozdíl od systémových parserů, které kontrolují doménu). Uvádí se úplná adresa; prázdná hodnota povolí vše. Spoofing falší neprojde, protože adresa se porovnává celá
• Více adres odesílatele: pokud banka posílá avíza z více adres, stačí je uvést do sender_whitelist oddělené mezerou, čárkou nebo středníkem — např. "sender_whitelist": "notification@csob.cz, avizo@csob.cz". Obě adresy jsou pak povolené (avíza z jakékoli jiné adresy se nezpracují)
• Vzory s (?i) jsou case-insensitive; diakritika se toleruje (zkouší se i varianta bez diakritiky, takže Zaúčtování i Zauctovani chytí)
• amount zachytí +0,01 i záporné částky; direction podle typu transakce určí, jestli jde o příchozí/odchozí platbu — odchozí dostane zápornou částku (jako systémový parser)
• specific_symbol je definovaný → párují se akce (VS = datum, SS = čas začátku akce), dobíjení i produkty (VS+SS+částka). Bez SS by se nespárovala žádná platba
• Ověřte si vzory v UI Parser test (tlačítko „Parser test" v kartě Bankovní e-mail) před uložením — vyplníte odesílatele, předmět a tělo a systém ukáže, co rozparsoval

Přidání nového e-mailového parseru banky (postup)¶

Každá banka s e-mailovými avízy má vlastní parser (např. csob, csob_ceb, fio, unicredit, raiffeisenbank). Parser se sám zaregistruje přes init() — stačí jeden nový soubor, žádné změny stávajícího kódu.

Postup (příklad pro novou banku):

1. Vytvořte soubor internal/bankemail/banks_<banka>.go
2. Definujte parser — struktura s metodami:
3. Key() — unikátní kód provideru (např. kb), píše se do bank_email_messages.provider_code
4. DefaultProvider() — odesílatel, subject/body vzor (jen pro UI přehled)
5. Supports(m Message, p Provider) bool — rozpoznání e-mailu:
   • nejdřív senderMatchesDomain(m, "kb.cz") (chrání před spoofingem — csob.cz.evil.com neprojde)
   • pak kontrola subjectu a těla (bez diakritiky + s diakritikou)
6. Parse(m Message, p Provider) (ParsedPayment, error) — extrakce polí:
   • VS → VariableSymbol, SS → SpecificSymbol, KS → ConstantSymbol (každé volitelné, required() jen pro kritická pole)
   • částka + měna, datum (parseDate), účty (splitAccount), zůstatek
7. func init() { registerSystemParser(BankaParser{}) }
8. Napište unit test internal/bankemail/<banka>_test.go s přesnou kopií reálného e-mailu (odesílatel, subject, tělo) + spoofing test
9. Napište integrační test — vzor: TestIntegration_CsobCebEmailFullFlow v internal/app/bankemail_integration_test.go:
10. seedTopupWithVSSS — pending dobíjení s VS/SS/částkou z e-mailu
11. bankemail.Message s tělem avíza → ep.FetchTransactions
12. a.TopupService.MatchBankTransactions(ctx, txs) → dobíjení dokončeno, kredit připsán
13. Spusťte testy a build: make all (+ go test -tags integration ./internal/app/)

E2E testy s reálnými payloady bank API¶

Pro provider API (Fio REST / Erste PSD2) jsou uloženy přesné kopie reálných odpovědí v internal/payment/providers/testdata/ (fio_transactions.json, erste_accounts.json, erste_transactions.json), automaticky zabudované do integration buildů přes //go:build integration (fixtures_loader.go). Slouží jako pojistka proti tiché změně formátu API.

Vzory testů v internal/app/payment_providers_e2e_integration_test.go:

• TestIntegration_E2E_FioRealtimePayload_Parse / TestIntegration_E2E_ErsteRealtimePayload_Parse — reálný payload projde provider parserem beze změny (VS/SS/částka, external ID, provider name, stránkování u Erste)
• TestIntegration_E2E_FioRealtimePayload_SessionPaid / TestIntegration_E2E_ErsteRealtimePayload_SessionPaid — reálná struktura payloadu přes reálný provider → CheckPayments → session zaplacená + bank_transactions s matched stavem

Při nahrávání reálné odpovědi od banky zachovejte konvenci vzorových emailů (viz výše): čísla účtů/IBAN/BIC/ID a VS/SS posuňte o konstantu (např. +7), jména nahraďte fiktivními. Hodnoty VS/SS/částky v E2E testech se přepisují z reálné struktury na hodnoty seedované session — testuje se, že struktura payloadu projde celým řetězcem a věrně se naparsuje.