Download the PHP package vs-point/kb-adaa without Composer

On this page you can find all versions of the php package vs-point/kb-adaa. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Example code of vs-point/kb-adaa

Informations about the package kb-adaa

vs-point/kb-adaa

PHP knihovna pro komunikaci s Komerční banka Account Direct Access API v2. Typovaný interface pro účty, zůstatky, transakce, výpisy v PDF a notifikace o pohybech.

Pokrývá všech 5 vrstev integrace:

Vrstva Co dělá Třída
Runtime ADAA čte účty, zůstatky, transakce, výpisy, spravuje notifikační subscriptions KbAdaaClient->accounts, ->balances, ->transactions, ->statements, ->eventSubscriptions
OAuth2 vyměňuje authorization code za tokeny, refreshuje access token, sestavuje login URL KbAdaaClient->oauth2
Client Registration (mTLS) žádá KB o software statement JWT pro tvou aplikaci KbAdaaClient->clientRegistration
Application Registration builduje redirect URL a dešifruje AES-256-GCM odpověď z callbacku KbAdaaClient->applicationRegistration
Event API receiver server-side helpery pro implementaci tvého webhook endpointu KbAdaaClient->eventApi

Instalace

Vyžaduje PHP ≥ 8.2 a rozšíření openssl, json, curl (curl ≥ 7.71 pro inline certifikát).

Architektura konfigurace

ADAA má tři různé apiKey (Client Registration, OAuth2, ADAA) a každý se získává zvlášť v developer portálu. Proto má knihovna tři oddělené config objekty:

Při inicializaci KbAdaaClient jsou OAuth2Config a ClientRegistrationConfig volitelné — předáš jen ty, které potřebuješ pro aktuální use-case.

Sandbox vs produkce

Token storage

Access token žije pouze 3 minuty, refresh token 12 měsíců. Knihovna vyžaduje TokenStorageInterface:

Pro lokální vývoj / CLI použij InMemoryTokenStorage. Pro produkci napiš vlastní implementaci nad svou DB / Redisem / secret managerem.

Auto-refresh: Pokud klientovi předáš OAuth2Config, automaticky před každým voláním zkontroluje expiraci tokenu, sám refreshne a uloží nový. Pokud OAuth2Config nepředáš, používá se uložený access token jak je (chování pro „manuální“ režim).

Quick start — runtime ADAA

Předpokládá, že už máš access token + refresh token získaný OAuth2 flow (viz dál).

Konfigurace mTLS (Client Registration)

Software statement endpoint vyžaduje kvalifikovaný certifikát od I.CA nebo PostSignum (KB ho sama nevydává). Certifikační autority ho typicky dávají jako .p12 (PKCS#12). Knihovna nabízí tři cesty, vyber si podle toho, kde certifikát žije:

Třída Vstup Kdy použít
ClientRegistrationP12Config .p12 soubor nebo bytes + heslo Máš .p12 přímo od I.CA / PostSignum, nechceš konvertovat
ClientRegistrationConfig cesta k .pem souboru Po jednorázové konverzi P12→PEM, certifikát žije na disku
ClientRegistrationInlineConfig PEM string Certifikát ze secret manageru / env proměnné

Z .p12 souboru (přímo od certifikační autority)

Nejjednodušší — knihovna provede openssl_pkcs12_read() interně:

Pokud máš .p12 už načtený v paměti (typicky ze secret manageru):

OpenSSL 3.x heads-up: openssl_pkcs12_read() selže na .p12 šifrovaných legacy algoritmy (RC2 / 3DES) — časté u starších Windows exportů z I.CA. Pokud konstruktor vyhodí výjimku, proveď jednorázovou konverzi openssl pkcs12 -legacy ... a použij ClientRegistrationConfig nebo ClientRegistrationInlineConfig.

Z PEM souboru na disku

Konverze .p12 → .pem:

Inline (PEM string ze secret manageru)

Žádný dočasný soubor se nezapisuje — používá CURLOPT_SSLCERT_BLOB (curl 7.71+).

Kompletní onboarding flow

KB onboarding je jednorázový proces na začátku integrace. Pak už jen průběžně refreshuješ token a voláš ADAA.

1. Software statement (jednou za 12 měsíců na aplikaci)

2. Application registration (jednou za 12 měsíců na klienta — provede uživatel přes browser)

Po dokončení se uživatel vrátí na tvůj registrationBackUri s ?salt=…&encryptedData=…. Dešifruj:

3. OAuth2 — získání access tokenu (uživatel se přihlásí do KB)

redirect_uri se vždy bere z OAuth2Config::$redirectUri — KB ho vyžaduje shodný napříč authorize / token-exchange / refresh.

Callback handler:

Od této chvíle můžeš volat ADAA endpointy. Pokud máš OAuth2Config připojený na klientovi, refresh probíhá automaticky.

Použití runtime API

Účty

Zůstatky

Transakce

Throughput limit KB: 1 stažení / hodinu. Pro vyšší frekvenci použij Event API subscriptions níže.

Výpisy v PDF

Notifikace (subscription management)

KB volá tvůj endpoint z IP 194.50.202.179 a 194.50.226.179 — povolit ve firewallu.

Event API receiver (serverová strana webhooku)

KB vyžaduje, aby tvůj endpoint implementoval dvě cesty:

Knihovna ti dává helper, který je framework-agnostický:

KB při 401/403/404 odpovědi subscription trvale zastaví (status STOPPED). Při 500 nebo timeout circuit breaker (SUSPENDED), opakování → STOPPED. Nereaguj 5xx kvůli své interní chybě — vrať 204 a process asynchronně.

Symfony DI integrace

Knihovna sama není Symfony bundle (žádný DI extension). Stačí YAML wiring:

Výjimky

Všechny API výjimky dědí z KbAdaaApiException. getHttpStatus(), getResponseBody(), getErrorCode() (parsovaný kód z {"errors":[{"code":"…"}]}).

HTTP / důvod Třída Typické error codes
400 InvalidRequestException DATE_IN_FUTURE, INVALID_DATE_INTERVAL, INVALID_ACCOUNT_ID, INVALID_CORRELATION_ID, INVALID_CURRENCY
401 UnauthorisedException INVALID_TOKEN, 900900
403 ForbiddenException ACCOUNT_ACCESS_DENIED, ACCOUNT_NOT_CONFIGURED, 900908
404 NotFoundException ACCOUNT_NOT_FOUND, STATEMENT_NOT_FOUND, SUBSCRIPTION_NOT_FOUND
429 RateLimitException REQUEST_IS_THROTTLED (1 stažení/hod limit), getRetryAfterSeconds()
(refresh) TokenRefreshFailedException Refresh token expiroval → uživatel musí re-authorize
(callback) ApplicationRegistrationDecryptionException Špatný klíč / poškozený ciphertext
(webhook) InvalidEventApiKeyException x-api-key z KB neodpovídá uložené hodnotě

Přehled endpointů

Service Metoda HTTP Path
accounts list() GET /adaa/v2/accounts
balances list(accountId) GET /adaa/v2/accounts/{accountId}/balances
transactions list(accountId, ?TransactionQuery) GET /adaa/v2/accounts/{accountId}/transactions
statements list(accountId, StatementListQuery) GET /adaa/v2/accounts/{accountId}/statements
statements download(accountId, statementId) GET /adaa/v2/accounts/{accountId}/statements/{statementId}
eventSubscriptions create(accountId, CreateSubscriptionPayload) POST /adaa/v2/accounts/{accountId}/transactions/event-subscriptions
eventSubscriptions get(accountId, subscriptionId) GET /adaa/v2/accounts/{accountId}/transactions/event-subscriptions/{id}
eventSubscriptions delete(accountId, subscriptionId) DELETE /adaa/v2/accounts/{accountId}/transactions/event-subscriptions/{id}
oauth2 buildAuthorizationUrl(scopes, ?state) — (browser redirect) login.kb.cz nebo sandbox UI
oauth2 exchangeAuthorizationCode(code) POST /oauth2/v3/access_token
oauth2 refresh(refreshToken) POST /oauth2/v3/access_token
clientRegistration issue(SoftwareStatementPayload) POST /client-registration/v3/software-statements
applicationRegistration buildRedirectUrl(env, RegistrationRequest) — (browser redirect) client-registration-ui
applicationRegistration decryptResponse(salt, encrypted, key) — (lokální AES-GCM dešifrování) —
eventApi handleEvent(body, expected, provided) — (server-side helper) —

Headless bootstrap v sandboxu

Sandbox OAuth2 obrazovka autorizační kód generuje čistě v JavaScriptu — žádné přihlašování, žádný backend roundtrip. Algoritmus je base64(JSON({userId, scopes})) bez = paddingu. Knihovna ho reprodukuje v PHP, takže integrační testy nemusí klikat v prohlížeči.

Pro plný integrační test stačí jen dva apiKey z developer portálu (KB_ADAA_API_KEY + KB_ADAA_OAUTH2_API_KEY); client_id a client_secret jsou KB-dokumentované sandbox defaults (ExampleClient-6303 / bUfDQ1fMmfaSlZBZXlxBOQ). Viz tests/Integration/SandboxBootstrapTest.php jako referenční E2E příklad — udělá code → token → accounts->list() proti reálnému KB sandboxu bez jakékoliv ruční interakce.

Pouze sandbox. Produkční token endpoint tento kód odmítne. V produkci musí uživatel projít opravdovým KB loginem na https://login.kb.cz/autfe/ssologin — viz OAuth2Service::buildAuthorizationUrl().

Canary test sandboxového JS

Sandbox algoritmus je závislý na tom, že ho KB nezmění. Unit test testSandboxJavascriptStillImplementsKnownAlgorithm stáhne živý JS a ověří přítomnost klíčových tokenů. Defaultně se skipuje; aktivuj přes:

Pokud canary spadne, znamená to, že KB algoritmus změnili a je třeba aktualizovat SandboxAuthorizationCodeFactory.

Vývoj

composer není na hostu — všechno přes Docker:

Integrační testy

Helper bin/test-integration.sh načte sandbox apiKeys z .secrets/, exportuje je jako env proměnné a spustí integration testy uvnitř Dockeru. Stačí mít dva JWT soubory:

Plný návod (kde získat klíče, jaký mít obsah) je v .secrets/README.md. Pozor — .secrets/ je gitignored, klíče tam neházej do commitů.

V GitLab CI je k dispozici stage integration, který se aktivuje automaticky, pokud jsou v project Settings → CI/CD → Variables nastavené (Masked + Protected) proměnné KB_ADAA_API_KEY a KB_ADAA_OAUTH2_API_KEY. Forky / unprotected branches stage tiše přeskočí.

Pokud chceš testovat s předem získaným access/refresh tokenem (bez sandbox bootstrap), nastav místo KB_ADAA_OAUTH2_API_KEY proměnné KB_ADAA_ACCESS_TOKEN + KB_ADAA_REFRESH_TOKEN (volitelně + KB_ADAA_ACCESS_TOKEN_EXPIRES_AT, KB_ADAA_SCOPE, KB_ADAA_ACCOUNT_ID).

Kompatibilita

Licence

MIT

All versions of kb-adaa with dependencies

PHP Build Version
Package Version
Requires php Version >=8.2
ext-openssl Version *
ext-json Version *
symfony/serializer Version ^6.4|^7.0|^8.0
symfony/property-access Version ^6.4|^7.0|^8.0
symfony/property-info Version ^6.4|^7.0|^8.0
phpdocumentor/reflection-docblock Version ^5.4
brick/math Version ^0.12.0
brick/date-time Version ^0.7.0
brick/money Version ^0.10.0
guzzlehttp/guzzle Version ^7.9
ramsey/uuid Version ^4.7
psr/http-message Version ^1.1|^2.0
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package vs-point/kb-adaa contains the following files

Loading the files please wait ...