Elektronické zpracování bankovních výpisů pomocí API bankovnictví

1. Úvod

· Účelem je napojení na API bank pro automatické stahování výpisů z účtů bez nutnosti otevírání internetového bankovnictví. Veškerá komunikace mezi bankou a IMESem probíhá pomocí oficiálních služeb těchto bank. Každá banka má svoje API (není jednotné) a své způsoby komunikace. Některá vyžaduje osobní certifikát a jiné zase stačí jednorázový token. Přístup k datům z účtu vytváří majitel nebo osoba s patřičnými právy ke zvolenému účtu. Pro stažení dat není nutné být přihlášen do internetového bankovnictví, odpovědi na požadavky se získávají prostřednictvím rozhraní API příslušné banky.

· V IS IMES je zpracování stejné jako při ručním stažení pohybů. Tedy nejprve menu Operace → Načtení bankovních výpisů, jen není nutné se přihlašovat do banky. Následně menu Operace → Zpracování bankovních výpisů je již stejné. Místo zpracování výpisů přes menu Operace → Zpracování bankovních výpisů může uživatel dát pokyn pro zpracování výpisu (vytvoření dokladu) přímo v okně pro načtení kliknutím na tlačítko Vytvoření dokladu v pravé dolní části okna. Výhodou je i automatické přiřazení dokumentu (výpisu) v .pdf a .json nebo .gpc k dokladu.

· Přístup k datům z účtu má jen osoba s patřičnými právy ke zvolenému účtu. Veškeré nastavení práv se nastavuje v elektronických bankovnictvích jednotlivých bank.

· Do budoucna je možno přidat automatické vytvoření dokladů bankovních výpisů za zvolený interval a spárování plateb (obsluha řeší jen nespárované doklady).

· Podporovanými bankami zatím jsou:

o Československá obchodní banka, a. s. (stahování výpisů z účtů v .gpc a .pdf),

o Fio Banka, a. s. (stahování výpisů z účtů v .json a .pdf)

o Česká spořitelna, a. s. (stahování transakční historie v .json a výpisů z účtů v .pdf),

o Komerční banka, a. s. (stahování transakční historie v .json a výpisů z účtů v .pdf).

o Raiffeisen bank, a. s. (stahování výpisů z účtů v .xml a .pdf)

o Moneta money bank, a. s. (stahování transakční historie v .json)

2. Bezpečnost na straně IMESu

· Oprávnění k bezpečnostním prvkům jako jsou tokeny a certifikáty má pouze ten uživatel, který je uveden jako uživatel daného bezpečnostního prvku. Bezpečnostní prvky smějí být používány pouze na databázi a serveru, který je u všech bezpečnostních prvků též uveden.

· Přístup k certifikátům a tokenům je z hlavního modulu IMESu. V hlavní nabídce vyberte Systém → Nastavení → Certifikáty.

· Podrobné informace o správě certifikátů naleznete v nápovědě Nastavení → Certifikáty → Správa certifikátů.

· Tokeny jsou umístěny pod záložkou Tokeny. Tokeny lze do tabulky přidat jednoduše pomocí přidání nového záznamu (musíte být v editačním módu), jako kód tokenu zvolte jedno písmeno následované číselným kódem (např.: T1, T2, T3, …). Také vyplňte uživatele, který bude mít k danému tokenu oprávnění.

· Po nastavení tokenů a certifikátů je třeba přiřadit tyto bezpečnostní prvky k bankovním účtům, které je budou využívat. K tomu slouží číselník C09505I a způsob vyplnění záznamu do tohoto číselníku bude popsán u každé banky zvlášť.

3. Nastavení jednotlivých bank

3.1. Fio banka, a. s.

3.1.1. Nastavení na straně internetového bankovnictví

· Pro autentizaci do Fio banky jsou potřeba dva tokeny (jeden pro stahování výpisů ve formátu .json, druhý pro stahování v formátu .pdf), které mohou mít platnost až 10 let.

· Token platí pouze k jednomu účtu, při použití více účtů je třeba vytvořit oba tokeny pro každý účet zvlášť.

· Pro získání platného tokenu je zapotřebí provést následující kroky:

o Oprávněná osoba se musí přihlásit do internetového bankovnictví.

o Administrace tokenů je přístupná po stisku tlačítka „Nastavení“ (v pravém horním rohu obrazovky). Na obrazovce „Nastavení“ poté přejděte na záložku „API“ a stiskněte tlačítko přidat nový token. Lze nastavovat tyto možnosti:

§ Každý token je platný pouze k jednomu účtu. Potřebujete-li přistupovat k více účtům, je nutné vygenerovat další token.

§ Možnost využití:

· Pouze sledovat účet – pokud chcete pouze stahovat výpisy

· Sledovat účet a zadávat platební příkazy – pokud chcete využívat i platební příkazy přes API

o Požadavek na zřízení tokenu musí být standardně autorizován. V případě, že je na příslušném účtu nastavena autorizace více osobami, musí token podepsat všechny podepisující osoby. Po úspěšné autorizaci je token zobrazen v přehledu.

o Po 5 minutách od úspěšné autorizace lze token použít v IS IMES (API)

3.1.2. Nastavení na straně IMES

· Tokeny vyplňte do modulu pro správu tokenů způsobem popsaným v kapitole 2.

· Do číselníku C09505I je třeba doplnit provázání bankovního účtu s tokeny. V nastavení číselníků otevřete číselník C09505I, přidejte nový záznam, do kterého vyplňte kód účtu, kód tokenu a kód tokenu 2. Ukázka správně vyplněné řádky číselníku pro účely zabezpečení připojení k Fio bance je vidět níže.

· Do číselníku C0402 je třeba doplnit šablonu pro příjem – FIOAPI, interval výpisu – D (denní), T (týdenní), M (měsíční), C (čtvrtletní), R (roční) a ve sloupci C09505I přiřaďte propojení s bezpečnostními prvky.

3.1.3. Řešení chyb

· Ujistěte se, zda máte vše dobře nastaveno. V číselníku C09504I musí být dva tokeny. Tyto tokeny musí být pomocí číselníku C09505I přiřazeny k danému účtu. V číselníku C0402 musí být vyplněn interval výpisu (D, T, M, C, R) a šablona FIOAPI.

· Ověřte, zda máte platný token, to můžete ověřit v modulu pro správu certifikátů a tokenů na záložce tokeny (jak se tam dostat je popsáno v kapitole 2), kde zkontrolujte údaj o platnosti tokenu. Pokud token exspiroval, přejděte svého internetového bankovnictví a pomocí postupu uvedeného v kapitole 3.1.1 vytvořte nový token, který umístěte do modulu pro správu tokenů (postup v kapitole 2). Exspirovaný token poté můžete smazat.

· Pokud obnovení tokenu nepomůže, a všechny údaje máte vyplněny správně, kontaktujte vývojáře.

3.2. Československá obchodní banka a. s.

3.2.1. Nastavení na straně bankovnictví

· Autorizace uživatele probíhá pomocí kvalifikovaného certifikátu od jedné z následujících certifikačních autorit:

1. První certifikační autorita, a. s. (I. CA)

2. Česká pošta, s. p. (PostSignum)

3. Československá obchodní banka, a. s. (ČSOB) – doporučujeme

3.2.2. Postup pro získání certifikátu od ČSOB

· Pro získání certifikátu je třeba nainstalovat aplikaci ČSOB Bussines Connector z adresy Business Connector | ČSOB (csob.cz) kde kliknete na odkaz „Stáhnout instalační balíček pro Windows“. Spusťte stažený instalační soubor a postupujte podle pokynů průvodce.

· Po instalaci se automaticky otevře okno Business Connectoru v prohlížeči.

Tam přejit do menu „Certifikáty“ a stisknout tlačítko „Požádat o certifikát“ Nyní se v okně objeví název žádosti. Žádost uložit na disk pomocí tlačítka „Stáhnout soubor“.

3.2.3. Generování certifikátu v CEB

Business connector nechat spuštěný a přejít na ČSOB CEB do menu „Nastavení“ -> „Business Connector“

Tam zmáčknout tlačítko „Požádat o certifikát“

Nyní se v okně objeví název žádosti. Žádost uložit na disk pomocí tlačítka „Stáhnout soubor“.

V dalším dialogu pomocí tlačítka „Vybrat soubor“ najit soubor se žádostí o certifikát vytvořený v předchozím bodu.

Do pole Název vyplnit libovolný název certifikátu a zmáčknout „Odeslat“

· Certifikát je vytvořen, můžete jej stáhnout, kliknutím na modrý odkaz stáhnout.

·

Instalace certifikátu do aplikace Business Connector

· Otevřít  aplikaci Business Connector.

· V menu „Certifikáty“ je řádka s žádostí o certifikát – stav = Rozpracovaný zde klik na tl. „Dokončit“

· V následujícím dialogu nalistujte pomocí tlačítka „Zvolit soubor“ uložený certifikát z bodu 3. Pak potvrdit tlačítkem „Uložit certifikát“ . Stav certifikátu se změni na „Aktivní“ .

·  Nyní je certifikát nainstalován i do úložiště Windows včetně privátního klíče.

· Více o certifikátu vydávaným ČSOB naleznete v tomto dokumentu: https://www.csob.cz/portal/documents/10710/15532355/bc-postup-pro-tvorbu-komunikacniho-certifikatu.pdf.

3.2.4. Nastavení na straně IMES

· Spustit Imes pod uživatelem, který se bude připojovat do banky

· Jít do menu : Systém – Nastavení – Certifikáty.

· Přepnout se do záložky „Osobní“ a použít tlačítko „Načíst certifikát“ – „Z Windows“ Doporučujeme!!!

· Pokud by jste zvolili ze souboru, tak si musíte vyexportovat certifikát včetně privátního klíče do formátu pfx. Ve Windows to provedete následovně

· Do vyhledávacího pole napsat cert + vybrat „Správa certifikátů počítačů“ viz.:

· V okně pro správu certifikátů vybrat Osobní, najít příslušný certifikát na něm:

 „Pravá myš“ – Všechny úkoly – Exportovat

· Následuje průvodce exportem certifikátu :

V dalším okně zaškrtnout „Ano, exportovat privátní klíč“ !!!  + tlačítko další + nové okno nechat beze změny + tlačítko další. V dalších krocích zadat heslo k certifikátu a zvolit cestu a jméno souboru pro uložení na disk.

3.2.5.  Postup na straně Imesu

· Nový certifikát se nyní objeví se v seznamu certifikátů. Ve sloupci „Vystaven pro“ je název PC z krerého se žádalo o certifikát a v sloupci

„Vystavil“ je „CEB Business“.

· Přepnout se do záložky „Tokeny“ – přidat řádek.

V novém řádku do sloupce :

1. „Token/CEB Kontrakt“

zadat Id (číslo) – nachází se u názvu firmy/uživatele po přihlášení do CEB (nahoře - uprostřed)

· Ve sloupci „C09505I“ klepnout na tlačítko, otevře se číselník C09505I. Tam přidat řádku a vyplnit:

„Kód účtu“ (z C0402)

„Kód tokenu“ - je stejný jako z bodu d)1.

„Kód tokenu 2“ - je prázdný

„Kód certifikátu“ (nalistovat) - je to osob.cert. viz. bod 6.d)

„Kód kořen. Certifikátu“ – nalistovat cert. S názvem „CEB Business connector CA“

3.2.6. Řešení chyb

· Program stahuje výpisy z účtů ve formátu .gpc (datové) a .pdf (lidsky čitelné, pro tisk) od doby posledního stažení. Dokumenty, které zatím nebyly pro stažení poptány, jsou k dispozici pro stažení 45 dní - pokud už byly jednou staženy tak tam zůstávají už jen 15 dní.

· Nejprve zkontrolujte, zda máte vše nastaveno podle výše uvedeného postupu. V číselníku C0402 musí být vyplněny sloupce Šablona pro příjem – CSOBAP, Interval výpisu (D, T, M, C, R) a musí být vytvořena vazba účtu na token, kód osobního certifikátu a kód kořenového certifikátu. Certifikáty a token (CEB kontrakt) musí být nahrány v IMESu.

· Může se stát, že skončila platnost certifikátu (osobního či kořenového). Jestliže se tak stane, vygenerujte nový certifikát podle postupu v kapitole 3.2.1 a nahrajte jej do IMESU a ve vazebním číselníku C09505I vyměňte příslušný kód certifikátu.

· V případě, že vyjmenované způsoby řešení nepomohly, kontaktujte vývojáře.

3.3.  Česká Spořitelna, a. s.

· Na straně elektronického bankovnictví se nenastavuje nic.

· Při prvním spuštění Načtení bankovního výpisu přes API si IMES automaticky stáhne token. Platnost tokenu je 180 dní. Po vypršení platnosti tokenu by měl uživatel být automaticky přesměrován na opětovné přihlášení do banky. Po autorizaci program stáhne všechny transakce od posledního stažení a k tomu stáhne i výpisy z účtu ve formátu .pdf.

· V číselníku C0402 je třeba ručně vyplnit šablonu pro příjem – CSAPI, interval výpisu – D (denní), T (týdenní), M (měsíční), C (čtvrtletní), R (roční) a IBAN, vše ostatní vyplní program automaticky.

· Program se snaží řešit potíže automaticky, pokud je nevyřeší, zkontrolujte, zda máte vyplněny správně všechny údaje uvedené o bod výše a případně kontaktujte vývojáře.

3.4. Komerční Banka, a. s.

· Na straně internetového bankovnictví se nenastavuje nic. Při prvním spuštění Načtení bankovního výpisu přes API si IMES sám stáhne token. Platnost tokenu je 365 dní. Po vypršení platnosti se uživatel musí znovu přihlásit, aby byl vygenerován nový token.

· Program stahuje seznam transakcí od posledního stažení ve formátu .json a výpisy z účtu ve formátu .pdf.

· V číselníku C0402 je třeba ručně vyplnit šablonu pro příjem – KBAPI, interval výpisu – D (denní), T (týdenní), M (měsíční), C (čtvrtletní), R (roční) a IBAN, vše ostatní vyplní program automaticky.

· Program se snaží řešit potíže automaticky, pokud je nevyřeší, zkontrolujte, zda máte vyplněny správně všechny údaje uvedené o bod výše a případně kontaktujte vývojáře.

· Výpisy a transakce lze stahovat pouze jednou za deset minut.

· Další informace KB o API naleznete zde

3.5. Raiffeisen Bank, a. s.

3.5.1. Nastavení na straně elektronického bankovnictví

· Pro připojení na API Raiffeisen Bank a. s. je potřeba vygenerovat komunikační certifikát. V internetovém firemním bankovnictví přejděte do nastavení a v menu v levé části obrazovky vyberte Správa certifikátů – Nový certifikát.

· Vymyslete název a heslo k certifikátu.

· Pro účely stahování výpisů zaškrtněte oprávnění „Transakční historie“ a „Účty a zůstatky“. V případě, že budete chtít využívat i převodní příkazy přes API zaškrtněte oprávnění „Hromadné platby“. Následně můžete certifikát vygenerovat a stáhnout.

3.5.2. Nastavení na straně IMESu

· V menu Systém → Nastavení → Certifikáty → Osobní nahrajte certifikát vygenerovaný v předchozích krocích

· Do číselníku C0402 vyplňte šablonu pro příjem – RFAPI, dále vyplňte interval výpisu – D (denní), T (týdenní), M (měsíční), C (čtvrtletní), R (roční) a vazbu mezi účtem a certifikátem do číselníku C09505I. Příklad správného vyplnění číselníku C09505I je uveden na následujícím obrázku.

3.5.3. Řešení chyb

· Pokud dojde k chybě, nejprve zkontrolujte, zda bylo vše vyplněno způsobem uvedeným v kapitole 3.5.2.

· Zkontrolujte, zda není exspirovaný certifikát. Pokud vypršela platnost, vygenerujte nový postupem uvedeným v kapitole 3.5.1, nahrajte jej do IMESu a změňte kód certifikátu ve vazebním číselníku C09505I.

· Pokud žádná z oprav nepomohla, kontaktujte vývojáře.

3.6. Moneta money bank, a. s.

3.6.1. Nastavení na straně internetového bankovnictví

· API Moneta dosud (29. 08. 2023) neumí posílat výpisy z účtů ve formátu .pdf spolu s transakcemi a neumí platební příkazy.

· Podmínky pro přístup k API Monety naleznete zde

· O přístupový token se žádá elektronickou instrukcí v internetovém bankovnictví v sekci Nastavení → API. Někteří uživatelé nemají možnost podat žádost přes elektronické bankovnictví (sekce API v nastavení není viditelná ani přístupná), ti musí požádat o přístup na email QAAPI@moneta.cz.

3.6.2. Nastavení na straně IMESu

· Ve správě tokenů (Hlavní modul → Správa → Nastavení → Certifikáty, záložka Tokeny) přidejte token získaný v předchozím kroku.

· V číselníku C0402 v sekci API vyplňte šablonu pro příjem – MOAPI, interval výpisu – D (denní), T (týdenní), M (měsíční), C (čtvrtletní), R (roční) a do číselníku C09505I přidejte vazbu na přidaný token. Ukázka možného vyplnění řádky v číselníku C09505I je na následujícím obrázku.

3.6.3. Řešení chyb

· V případě chyby zkontrolujte, zda je vše správně nastaveno. Ve správě tokenů musí být vyplněn token. V číselníku C0402 musí být vyplněna šablona pro příjem – MOAPI, interval výpisu (D, T, M, C, R) a v číselníku C09505I musí být vyplněna vazba tokenu na účet.

· Pokud je vše vyplněno správně a chyba přetrvává, kontaktujte vývojáře.