KB API

Bankovnictví bez hranic. Získejte aktuální data a informace
a ovládejte účty ve vaší aplikaci díky KB API

Partner Service

PŘÍMÝ PŘÍSTUP K ÚČTU SANDBOX
Služba vám umožní jednoduše a bezpečně stahovat transakční historii a zůstatky na vašich účtech do účetního nebo podnikového systému, který používáte.

Co to dělá?

Služba Account Direct Access API (zkr. ADAA) poskytuje bezpečný přístup k informacím:

  • Transakční historii klienta
  • Zůstatkům na bankovních účtech

Informace jsou poskytovány ke běžným účtům klienta Komerční banky.

Informace k zůstatkům jsou poskytovány v následujícím detailu:

  • Zůstatek 
  • Disponibilní zůstatek (včetně karetních blokací) 
Předpoklady používání

Nutným předpokladem pro využívání produktu Přímý přístup k účtu (ADDA) je nutné mít vystavený certifikát vydaný, který je pro Komerční Banku důvěryhodný. O certifikáty je nutné zažádat u:

Podporujeme jeden z níže uvedených typů certifikátů:

  • Komerční certifikát
  • Zaměstnanecký kvalifikovaný certifikát
  • Firemní Kvalifikovaný certifikát
  • Firemní komerční technologický serverový certifikát

Služba Přímý přístup k účtu (ADDA) vyžaduje certifikát, který musí obsahovat Název organizace a IČO. Při žádosti o certifikát je potřeba tuto skutečnost klientem explicitně uvést.

Příklady

Transakce okamžitě

Eshopy, klubové spolky, sdružení, kde se platí členské příspěvky, ti všichni potřebují aktivně a pracovat s platbami. Ideálně hned po připsání platby na účet. Služba Přímý přístup k účtu (ADAA) umožní v reálném čase získávat informace o platbách, které následné klienti použití ve svých procesech, ať je expedice zboží u e-shopů, párování faktur u účetních společností. 

Řízení finančních toků

Informace o zůstatcích klienti využívat pro aktivní řízení finančních toků, kdy je možné hlídat zůstatky na jednotlivých účtech a pak následně je podle výsledků je můžou inicializovat další akce, například upozornění, že zůstatek na běžném účtu klesl pod určitou úroveň. 

Cena

Služba Přímý přístup k účtu (ADDA) je poskytovaná bezplatně.

 

Jak služba funguje

1. Klient spustí aplikaci třetí strany, která již má implementovanou podporu služby Přímý přístup k účtu (ADAA). V této aplikaci bude klient s daty i následně pracovat. 

2. Klient v aplikaci musí udělit souhlas ke stahováním dat. Souhlas je udělován pomocí některé z dostupných bankovních autentizačních metod:

       a. Bezpečnostní heslo
       b. Osobní certifikát v souboru
       c. Osobní certifikát na čipové kartě
       d. KB Klíč

3. Souhlas se uděluje na dobu určitou. Maximální doba je 12 měsíců.

4. Po udělení souhlasu je aplikace třetí strany  připravena na stahování dat a práci s transakční historií.

Podmínky

Pro přístup ke službě je potřebné mít:

  • Vystaven platný kvalifikovaný certifikát vydaný Certifikační Autoritou, která je v KB důvěryhodná (např. I.CA, PostSignum).
  • Digitální prohlášení podepsané bankou KB (KB software statement) dle standardu RFC 7591 - OAuth 2.0 Dynamic Client Registration Protocol (vystavuje se přes bankovní API, více se dozvíte v technickém manuálu).
  • Při práci doporučujeme dodržovat obezřetného přístupu k bezpečnosti dat a systémů, naše doporučení najdete v na stránkách Pravidla obezřetného přístupu
Připravujeme

Na produktu ADDA neustále pracujeme a zlepšujeme jej. Na talíři v tuto chvíli máme tyto vylepšení:

  • 2020
    • Upozornění na novou transakci
    • Transakční historie, přírůstkově, od bodu posledního stažení
Přístup

Pro přístup k produkční verzi  služby Přímý přístup k účtu (ADAA) je nutné mít vystavený certifikát, který obsahuje Název organizace a IČO organizace pro kterou se budou stahovat data o transakční historii nebo o zůstatcích na běžném účtu.

Zhotovitel aplikace musí aplikaci registrovat, což provede následujícím způsobem:

1. Jít na API portálu Komerční banky, kde v sekci pro vývojáře, vyberte příslušnou službu (v našem případě Přímý přístup k účtu - ADDA) a klikněte a na její detail.

2. V detailu služby, v sekci Použití služby krok za krokem si vybere:

           a. Otestujte své řešení - sandbox pro neomezené experimentování 

3. Pro registraci aplikace pro testovací účely je nutné se nejdříve registrovat (anebo přihlásit, pokud už na API portálu KB máte uživatelský účet). Pro registraci potřebujete:

           a. e-mailový účet
           b. heslo pro přístup

4. Po úspěšné registraci / přihlášení je následně vyberete "Add Application" kde udělá registraci svojí aplikaci. K registraci stačí pouze: 

           a. Název aplikace
           b. Popis aplikace

7. Následně si vývojář vybere záložku "Sandbox Key" vygeneruje si svůj klíč pro aplikaci.

6. Po vygenerování klíče je  dále potřeba zaregistrovat 3 aplikace:

           a. Oauth2-Sandbox - (verze 1)
           b. Oauth2-Software-statements-Sandbox - (verze 1)
           c. Account-Direct-Access-API-Sandbox - (verze 1)

a postup je následující: 

           1. vybrat záložku "Subscriptions"
           2. vybrat konkrétní aplikaci, kterou si chci zaregistrovat
           3. potvrdit registraci

7. A máme hotovo!

Autentizace

Služba je zabezpečená dle OAuth 2 standardu a poskytuje tak vysokou úroveň zabezpečení. Pro použití služby se tedy vyžaduje souhlas klienta.

 

Prostředí
Environment Description Last Update
Sandbox

https://openbanking.kbcloud.cz/

12. 12. 2019

Limity

Limity jsou nastaveny per API klíč a to na volání v rámci jedné minuty a dále v rámci jednoho dne. Hodnoty jsou následující: 

Volání za minutu

   Volání za den

60    3600 x 24 (86 400) 
Příklady volání API
  • Příklad github
  • transakční historie (k danému účtu)

  • ​zůstatek na účtu

 

Schéma volání API

Vydání bankou podepsaného softwarového statementu 

  • Podepisování statementu vychází z OAUTH2 standardu dle RFC 7591 o dynamické registraci oauth2 klientů.
  • Statement je potřebný k automatické registraci klientovy aplikace, aby byla zaručená důvěryhodnost a bezpečnost registrace.
  • Po úspěšném provolání API v odpovědi obdržíte bankou podepsaný statement ve formě JWT tokenů, kterým se bude klientova aplikace registrovat do banky.
  • JWT token je nutné bezpečně naimplementovat/uložit do vaší aplikace, nebo jejích instancí, aby se pak dokázali zaregistrovat do banky. Detailní popis API naleznete ve swagger dokumentaci.

Registrace OAUTH2 agenta – klientové aplikace

  • Proces registrace klientovi aplikace do banky, je podmíněn udělením klientova souhlasu k této operaci.
  • Na podnět klienta se mu musí otevřít registrační URI, přes kterou se přihlásí do banky, pojmenuje si svou registraci instance aplikace a podepíše tuto operaci.

Udělování klientova souhlasu se stahováním dat přes klientovou aplikaci a získávání authorization code (5.)

  • Proces udělení souhlasu k stahování klientovi transakční historie, je podmíněn udělením klientova souhlasu k této operaci.
  • K tomuto účelu slouží voláni bankovní webové služby, přes kterou klient uděluje svůj souhlas ke přístupu k jeho účtům.
  • Na podnět klienta se mu musí otevřít URI (parametry) pro udělování souhlasu, přes kterou se přihlásí do banky a podepíše tuto operaci.
  • Po dokončení operace bude do prohlížeče na zadanou redirectUri navrácen autorizační kód pro vyzvednutí refresh a access tokenů, které slouží k stahování klientských dat.

Získáváni tokenů 

  • Po získání autorizačního kódu, který byl vydán na základě udělení souhlasu klienta k stahování transakční historie, je nutné ho vyměnit za refresh a acces token. 
  • Endpoint také slouží k získání access tokenu pomocí refresh tokenu. Pomocí přístupového tokenu (access_token) lze provolávat veškeré Endpointy služby ADAA. Detailní popis API naleznete ve swagger dokumentaci.

Výměna IBAN za identifikační číslo účtu

  • Kvůli zvýšené bezpečnosti je nutné žádat o informace pro daný IBAN, pomocí jeho identifikačního čísla, které lze obdržet přes tento endpoint.
  • Stahování transakční historie nebo informací o účtu se volá pomocí identifikačního čísla IBANu - accountId. Detailní popis API naleznete ve swagger dokumentaci.

Stahování transakční historie 

  • Endpoint slouží pro stahování transakční historie pro požadovaný účet. Detailní popis API naleznete ve swagger dokumentaci.

Stahování zůstatku na účtu

  • Endpoint slouží pro stahování informací o účtu. Detailní popis API naleznete ve swagger dokumentaci.

 

2019-12-12

Vydání sandboxů

Bude pro vás toto API užitečné?

5 lidí 
hlasovalo