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.

Co to dělá?

Služba Přímý přístup k účtu (ADAA) poskytuje bezpečný přístup k informacím:

  • Transakční historii účtů klienta, ke kterým má přístup (i jako zmožněná osoba
  • Zůstatkům na bankovních účtech

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

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

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

Předpokladem pro využívání produktu Přímý přístup k účtu (ADAA) 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ů:

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

Služba Přímý přístup k účtu (ADAA) 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žijí 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ů. Je možné hlídat zůstatky na jednotlivých účtech a pak následně podle výsledků mohou 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 (ADAA) je poskytovaná bezplatně.

 

Jak služba funguje

1. Klient se přihlásí do aplikace, 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 aplikaci a 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á (I.CA, PostSignum).
  • Při práci doporučujeme dodržovat pravidla obezřetného přístupu k bezpečnosti dat a systémů, naše doporučení najdete na stránkách Pravidla obezřetného přístupu
Připravujeme

Na službě Přímý přístup k účtu (ADAA) neustále pracujeme a zlepšujeme jej. 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í
    • PDF výpisy k účtu
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 - ADAA) 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

5. 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 (verze 1)
           b. Oauth2-Software-statements (verze 1)
           c. Account-Direct-Access-API (verze 1)

7. a postup je následující: 

           a. vybrat záložku "Subscriptions"
           b. vybrat konkrétní aplikaci, kterou si chci zaregistrovat
           c. potvrdit registraci

8. 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í

Prostředí

Popis

Aktualizace

Sandbox

https://openbanking.kbcloud.cz/

3. 2. 2020

Produkce

https://api.kb.cz/open/apim/store

3. 2. 2020

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
Schéma volání API

Popis funkčnosti

Poté je nutné provázat (subscribe) aplikaci s API:

  • Account Direct Access API
  • OAUTH2
  • Client registration

Swagger pro zmíněné služby obsahuje detailní popis všech atributů a měl by postačovat k pochopení funkčnosti. Swagger dokumentace je obecně psaná v anglickém jazyce.

1. Vydání bakou podepsaného software statementu

Cíl

Získat Komerční Bankou podepsaný sw statement.

Typ

REST API služba

Volané API

[POST] https://api.kb.cz/open/api/client-registration/v1/software-statements

Zabezpečení

API klíč

Požadavky

Platný kvalifikovaný certifikát vydaný certifikační autoritou

Request data

Certifikát

Response data

Podepsaný statement ve formě JWT tokenu

 

Statement má platnost 6 měsíců. 

URI parameter

Description

x-client-cert

Fill “valid-certificate” (sandbox accepts this value as a valid client certificate)

 

2. Registrace OAUTH2 agenta - aplikace třetí strany 

Cíl

Zaregistrovat do banky aplikaci třetí strany, jako OAUTH2 agenta pro schopnost komunikace mezi aplikaci a bankou.

Typ

Volání (SSL) HTTP POST (SAML)

Volaná URI

https://openbanking.kb.cz/client-api-management/saml/register

Zabezpečení

HTTPS, SSL, Software statement

Požadavky

Podepsaný statement ve formě JWT tokenů, podpora šifrování RSA-256, podpora embedovaného prohlížeče výhodou

Request data

Statement ve formě JWT tokenu, návratová URI pro získání authorisation code. Šifrovací klíč, šifrovací algoritmus (viz definice parametrů)

Response data

Zašifrované registrační údaje (clientId, clientSecret) jako (encryptedData, salt)

 

Doporučením je, aby vaše aplikace podporovala embedovaný prohlížeč.
Na podnět klienta se musí otevřít registrační URI, přes kterou se klient přihlásí do banky, pojmenuje si svou instanci aplikace a podepíše tuto operaci.
Registrační parametry se posílají na bankovní URI přes HTTP POST v parametru (registrationRequest) jako JSON formulář ve formátu BASE64URL, příklad viz níže.

Po dokončení operace a úspěšném zaregistrování budou do prohlížeče na zvolenou adresu (uvedena ve vašem software statementu z kroku 1 - redirectUris) vrácené zašifrované registrační údaje (client_id, client_secret) šifrovacím klíčem (encryptionKey) a algoritmem (encryptionAlg). Data budou vrácená v parametrech (encryptedData, salt).

Definice parametrů formuláře voláné URI

Parametr

Povinné

Datový typ

Validace

Popis

applicationType

A

String

„web“ | „native”

Typ aplikace:

  • web
  • native

clientName

A

String

4 - 255 znaků

Název registrovaného OAUTH2 agenta

clientNameEn

N

String

4 - 255 znaků

Anglická verze názvu

redirectUris

A

List<String>

Not empty

Návratová adresa, na kterou se bude vracet autorizační kód z kroku 3.

scope

A

List<String>

Not empty

Rozsah oprávnění. Plní se hodnota „adaa

encryptionKey

A

String

-

Šifrovací klíč, kterým bude client_id, client_secret zašifrované.

encryptionAlg

A

String

„AES-256“

Šifrovací algoritmus, aktuálně podporovaný algoritmus je pouze AES-256.

softwareStatement

A

String

-

Bankou podepsaný statement ve formě JWT tokenu.

 

Příklad vyplněného JSON formuláře


   "clientName":"Nejlepsi Produkt",
   "clientNameEn":"Best Product",
   "applicationType":"web",
   "redirectUris":[ 
      "https://client.example.org/callback",
      "https://client.example.org/callback2"
   ],
   "scope":[ 
      "adaa"
   ],
   "softwareStatement":"eyJhbGciOiJSUzI1NiJ9"
}

 

Finální request registrace OAUTH2 agenta

Vyplněný formulář se provede do formátu BASE64 pro URL a pošle se v requestu v parametru registrationRequest.

https://openbanking.kb.cz/client-apimanagement/saml/registerregistrationRequest=eyAKICAgImNsaWVudE5hbWUiOiJOZWpsZXBzaSBrbGllbnQiLAogI
CAiY2xpZW50TmFtZUVuIjoiQmVzdCBjbGllbnQiLAogICAiYXBwbGljYXRpb25UeXBlIjoid2ViIiwKICAgInJlZGlyZWN0VXJpcyI6WyAKICAgICAgIm
h0dHBzO
i8vY2xpZW50LmV4YW1wbGUub3JnL2NhbGxiYWNrIiwKICAgICAgImh0dHBzOi8vY2xpZW50LmV4YW1wbGUub3JnL2NhbGxiYWNrMiIKICAgXSwKICA
gInNjb3BlIjpbIAogICAgICAiYWRhYSIKICAgXSwKICAgInNvZnR3YXJlU3RhdGVtZW50IjoiZXlKaGJHY2lPaUpTVXpJMU5pSjkiCn0

 

Výsledek úspěšné registrace
Pokud dojde k úspěšné registraci OAUTH2 agenta, vrátí se HTTP 302 redirect s přesměrováním na registrační redirectUri s parametry salt a encryptedData. Parametry jsou ve formátu BASE64 pro URL a je nutné je před dešifrací dekódovat z BASE64URL.

https://client.example.org/callback?salt=yMzQ1NiIsImVtYWlsOiBleGFtcGxlQGdvb2Rzb2Z0Lm&encryptedData=VlciIsInNvZnR3YXJlT
mFtZSI6Ik5lamxlcHNpIFByb2R1a3QiLCJzb2Z0d2FyZU5hbWVFbiI6IkJlc3QgUHJvZHVjdCIsInNvZnR3YXJlSWQiOiJmNjRiZjJlNDQ3ZTU0NTIyO

 

Dešifrovaná struktura dat úspěšné registrace
Výsledkem jsou JSON data, která byla pro daného OAUTH2 agenta registrována v bance. Pro další kroky bude potřeba si bezpečně uchovat hodnoty client_id a client_secret, které slouží pro identifikaci OAUTH2 agenta


   "client_id":"NejlepsiProdukt-7427",
   "client_secret":"6dBtcLp27Q0UXrvfoXOSug",
   "api_key":"NOT_PROVIDED",
   "application_type":"web",
   "redirect_uris":[ 
      "https://client.example.org/callback",
      "https://client.example.org/callback2"
   ],
   "client_name":"Nejlepsi Produkt",
   "client_name#en-US":"Best Product",
   "logo_uri":"https://client.example.org/logo.png",
   "contact":"example@goodsoft.com",
   "bin":"45317054"
}

 

a

URI parameter

Description

response_type

Type of return value, always fill „code“.

client_id

OAuth2 agent ID – TPP application name, always fill „kbSandboxUser”.

redirect_uri

Back URL for sending an authorization code (i.e. „https://mycompany.cz“).

scope

Authority scope, for ADAA always fill „adaa“.

Note: Unsupported parameters route to bad request.

KB OAUTH2 TEST login page:

3. Udělování klientova souhlasu se stahovaním dat přes aplikaci třetí strany a získávání authorisation code

Cíl

Udělit souhlas k stahování transakční historie z banky do aplikace a získat authorisationCode.

Typ

Volání (SSL) HTTP POST (OAUTH2)

Volané URI

https://login.kb.cz/autfe/ssologin

Zabezpečení

HTTPS, SSL, OAUTH2

Požadavky

Zaregistrovaná aplikace v bance jako OAUTH2 agent.

Request data

client_id, redirect_uri, scope, response_type

Response data

authorisation_code

Proces udělení souhlasu k stahování transakční historie do aplikace třetí strany, 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 souhlas k přístupu ke svým účtům. Na podnět klienta se mu musí otevřít URI (viz definice parametrů) pro udělování souhlasu, přes které se přihlásí do banky a podepíše tuto operaci. Po dokončení operace bude do prohlížeče na zadanou redirect_uri vrácen autorizační kód (authorisation_code) pro vyzvednutí refresh a acces tokenů, které se používají k stahování klientských dat.

Definice parametrů voláné URI

URI parametr

Popis

redirect_uri

URI adresa pro vrácení authorisation_code uvedená při registraci OAUTH2 agenta (validace, zda jsou identické).

client_id

ID OAUTH2 agenta, přiděleno bankou po registraci z předchozího kroku.

scope

Rozsah planosti, plní se hodnota „adaa“.

response_type

Typ návratové hodnoty. Plní se hodnota „code“.

 

Finální request udělení souhlasu

https://login.kb.cz/autfe/ssologin?scope=adaa&client_id=NejlepsiProdukt-7427&redirect_uri=https://client.example.org/callback&response_type=code


Výsledek úspešného udělení souhlasu
Pokud dojde k úspěšnému udělení souhlasu pro stahování TH pro OAUTH2 agenta vrátí se HTTP 302 redirect s přesměrováním na redirectUri s parametrem code který obsahuje autorizační kód.

https://client.example.org/callback?code=ZnR3YXJlTmFtZSI6Ik5lamxlcHNp

 

4. Ziskání tokenu

Cíl

Získat autorizační kód pro výměnu za přístupový a obnovovací token, pro stahování transakční historie.

Typ

REST API služba

Volané API

https://api.kb.cz/open/api/oauth2/v1/access_token

Požadavky

Klientem udělen souhlas, mít authorisation_code

Request data

client_id, client_secret, authorisation_code

Response data

refresh_token, access_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 access token. K tomu slouží tento endpoint. 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 API služby ADAA. Detailní popis API naleznete ve swagger dokumentaci.

Definice tokenů:

Token

Popis

Platnost

access_token

Slouží jako autorizační parametr voláni API služby ADAA

Pozn.: Token lze po dobu platnosti opakovaně používat.

3 minuty

refresh_token

Slouží k vydání nového Access tokenu, používá se jako parametr volání API služby OAUTH2.

Pozn.: Token lze po dobu platnosti opakovaně používat.

12 měsíců

 

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

Cíl

Získat accountID pro daný IBAN.

Typ

REST API služba

Volané API

https://api.kb.cz/open/api/adaa/v1/account-ids 

Požadavky

Znalost IBAN čísla a měny účtu.

Request data

IBAN, currency, access_token

Response data

account_id

 

Kvůli zvýšené bezpečnosti není možné IBAN posílat v hlavičce v otevřené forma, ale je nutné zažádat o tzv. identifikační číslo (jedná se o zašifrovaný IBAN). Stahování transakční historie nebo informací o účtu se volá pomocí tohoto identifikačního čísla - account_id. Detailní popis API naleznete ve swagger dokumentaci k službě ADAA.

Banka doporučuje:

  • Uchovat v aplikaci account_id pro opětovné použití. Není potřeba opakovaně volat endpoint.

6. Stahování transakční historie

Cíl

Stáhnout transakční historií.

Typ

REST API služba

Volané API

https://api.kb.cz/open/api/adaa/v1/transactions

Požadavky

Platný access_token, account_id

Request data

account_id, access_token

Response data

transakční historie

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

7. Stahování zůstatku na účtu

Cíl

Stáhnout zůstatek na účtu.

Typ

REST API služba

Volané API

https://api.kb.cz/open/api/adaa/v1/balances

Požadavky

Platný access_token, account_id

Request data

account_id, access_token

Response data

zůstatek na účtu

Endpoint slouží pro stahování zůstatku na účtu pro požadovaný účet. Detailní popis API naleznete ve swagger dokumentaci.

 

 

2020-03-01

Pilotní režim

 

2019-12-12

Vydání sandboxů

 

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

79 lidí 
hlasovalo