Česká spořitelna API (CZ)
Submodul Česká spořitelna API je možné aktivovat pouze v případě již aktivního modulu Fakturace.
Zjednodušeně se jedná o možnost automatizovaného stahování informací o platbách (avíz) z bankovního serveru České spořitelny do systému ISPadmin a jejich následné automatické nebo ruční zpracování.
Postup pro zprovoznění
Pro korektní připojení na API České spořitelny je nutné splnit několik následujících kroků k získání přihlašovacích parametrů:
- Registrace a přihlášení na Erste Developer Portal (dále jen EDP) – Chci si API vyzkoušet sám – https://developers.erstegroup.com/register
2. V EDP vytvořit novou aplikaci:
Vyplnit formulář a nahrát ikonu aplikace (stáhnout ISPadmin logo).
Důležité je zadat všechny možnosti včetně obrázku (později je v nastavení možné všechny parametry upravit). Na závěr je nutné zvolit jako použití aplikace – Final API Consumer (aplikace bude spravovat jen Vaše účty).
3. Nyní máte vytvořenou aplikaci, která ještě není připojena k žádnému API (chybí přístupové údaje do banky atp.).
K vytvořené aplikaci připojte banku – Česká spořitelna a.s. tlačítkem Připojit k bance (
) pod vytvořenou aplikací:
Bezpečnost komunikace zajišťuje standart OAuth 2.0.
4. V dalším kroku je nutné vybrat API tlačítkem Přidat API (
) a zvolit Accounts API.
Dole ve formuláři potvrdit tlačítkem Připojit vybraná API (
).
- V záložce SCOPES nastavit požadované scope (siblings.accounts) na možnost (pokud již není vybraná) – Povinně
- Zapněte sliderem možnost OAuth2
5. Nastavit v následujícím okně:
Nastavení Redirect URIs – URI (Uniform Resource Identifier) pro přesměrování do aplikace ISPadmin (pro zpracování kódu nebo tokenu) je pro testovací prostředí (sandbox) i ostrý provoz (produkce) stejné viz:
URI pro přesměrování – https://[adresa_ISPadmin]/billing-bank-cs-api-endpoint/complete
Nutné je použít absolutní URL s doménovým jménem. Pokud přistupujete v prohlížeči přes IP adresu je nutné zadat výše místo [adresa_ISPadmin] IP adresu serveru se systémem ISPadmin.
Po udělení přístupu tlačítkem Udělit přístup (
) v (Fakturace –> Nastavení –> Banka –> ČS API) v API dojde k přesměrování na tuto zadanou adresu.
Nastavení doby platnosti pro refresh token
Doba platnosti pro refresh token (přístup ze strany ČS) je max. 90 dnů (možnost nastavení menší doby platnosti ve formuláři na obrázku níže). Po uplynutí této doby je potřeba udělit přístup (Fakturace –> Nastavení –> Banka –> ČS API) k účtu znovu.
Systém Vás na tento stav (blížící se vypršení doby platnosti) upozorní 10 dní před koncem (v dashboardu, v přehledu stažených plateb, emailem a systémovým upozorněním).
Z upozornění (widgetu) v dashboardu je možné se prokliknout přímo do příslušné záložky pro obnovení nastavení přístupu tlačítkem Upravit (
).
Nastavení typu Grantu – nastavit na možnost Code. Je ideální pro situaci, kdy je potřeba přistupovat k API ve jménu bankovního klienta (Vás) dlouhodobě a nechcete při každém pokusu o přístup autorizovat (možnost Implicit).
Stisknutím na tlačítko Uložit (
) pod formulářem dojde k uložení nastavených hodnot.
6. Tlačítkem Vygenerovat přístupové údaje pro Sandbox (
), vygenerujete testovací údaje pro nastavení do systému ISPadmin.
Hodnoty pro nastavení do systému ISPadmin – API klíč, Client ID, Client Secret je možné zadat v nastavení pro ČS API (Fakturace –> Nastavení –> Banka –> ČS API).
Tlačítkem Udělit přístup () v (Fakturace -> Nastavení -> Banka -> ČS API) dojde v testovacím režimu k simulaci udělení přístupu aplikaci do banky. Zobrazí se tzv. consent screen pro možnost zadat/vybrat testovací přihl. údaje (viz obrázek níže).
Pokud tento proces proběhne v pořádku (vidíte obrazovky na obr. níže) včetně informační hlášky o úspěšném udělení přístupu, můžete pokračovat dále k povolení přístupu pro produkci (ostrý provoz).
7. Pro možnost přepnout na produkční prostředí je nutné zapnout dvoufázové ověřování a nainstalovat mobilní aplikaci Google Authenticator. Tato aplikace generuje kódy dvoufázového ověření na Vašem mobilním zařízení.
Aplikaci Google Authenticator pro mobilní zařízení je možné stáhnout (ZDARMA):
- pro Android z Google Play
- pro iOS na App Store
Po nainstalování aplikace do mobilního zařízení můžete tlačítkem Pokračovat (
) přejít k dalšímu kroku.
Nainstalovanou aplikaci Google Authenticator je potřeba na mobilním zařízení otevřít.
Po splnění kroku je možné pokračovat dále kliknutím na tlačítko Pokračovat ().
V mobilní aplikaci naskenujte zobrazený QR kód nebo manuálně vyplňte zobrazený klíč.
Následně si zobrazený klíč v oranžovém rámečku zazálohujte. Tento klíč umožňuje obnovit dvoufázové ověření v případě, že ztratíte mobilní zařízení.
- Vaše heslo – zadané heslo pro přístup do Erste Developer Portalu z prvního kroku
- Opište kód z aplikace – opište zobrazený kód v aplikaci Google Authenticator na mobilním zařízení (tento kód si nemusíte pamatovat, protože se často mění)
Tlačítkem Zapnout Google Authenticator (
) dokončíte nastavení dvoufázového ověření.
8. Přepnutí na produkční prostředí. Z testovacího prostředí je potřeba přidanou aplikaci v EDP povolit/spustit/přepnout na produkční prostředí.
Možné to je kliknutím na záložku Produkce (prostředí):
Po vyřešení všech nutných závislostí a vyplnění vyžadovaných informací (např. nastavení DIČ), se kliknutím na možnost Schválení bankou (klikněte pro vyřešení) zobrazí informace se shrnutím zadaných údajů. V tomto okně je možné odeslat žádost bance o přístupové údaje pro aplikaci – ISPadmin (pro ostrý provoz) tlačítkem Odeslat.
DŮLEŽITÉ:
Přihlašovací údaje pro produkční prostředí (ostrý provoz) jsou jiné než pro Sandbox (testovací prostředí) – API klíč, Client ID, Client Secret. Ty je potřeba v nastavení systému ISPadmin změnit (Fakturace –> Nastavení –> Banka –> ČS API).
Zobrazení Client Secret je v produkčním prostředí podmíněno dvoufázovým ověřením (přes mobilní aplikaci GA) viz body výše.
Přes tlačítko Udělit přístup ( ) v (Fakturace –> Nastavení –> Banka –> ČS API) dojde k udělení přístupu aplikaci (ISPadmin) v produkčním prostředí. Zobrazí se tzv. consent screen pro možnost zadat přihl. údaje, udělit souhlas (povolit přístup k bank. účtu).
V případě nejasností kontaktujte prosím podporu ISPadmin (support@ispadmin.eu).
Práva
Zobrazení záložky s nastavením ČS API je podmíněno nastavením práv pro tuto záložku konkrétním a kompetentním uživatelům.
V Nastavení -> Administrátoři -> Administrátoři povolit konkrétnímu uživateli/skupině práva pro záložku hlavního menu Fakturace / Nastavení / Banka / ČS API případně i pro zobrazení stažených plateb Fakturace / Banka / ČS API.
Stahování a párování plateb
Správa a přehled získaných avíz o provedených platbách je možná v (Fakturace -> Banka -> ČS API).
Stažené platby se budou automaticky stahovat a párovat pomocí nastavených pravidel v (Fakturace -> Nastavení -> Banka -> Pravidla). Je možné je i dopárovat ručně na více faktur, do kreditu apod.
Stahování avíz o provedených platbách probíhá pravidelně každých 5 minut. Některé platby se však objeví k dispozici ke stažení přes API až později a z tohoto důvodu se dostahují do systému ISPA i zpětně za poslední 3 dny. V případě chybějících plateb, je možné je za vybrané období (od–do) stáhnout ručně v (Fakturace –> Banka –> ČS API).