csob/documentation/overview.md

ČSOB PSD2 služba – přehled

Tato služba je tenký, bezstavový multi-tenant proxy mezi klientskými aplikacemi a produkčním ČSOB PSD2 (Open Banking) API (Czech Open Banking Standard – COBS). Vystavuje vlastní REST endpointy a každý request 1:1 přeloží na odpovídající ČSOB volání, přičemž doplní povinné COBS hlavičky a naváže mutual TLS pomocí certifikátu předaného v hlavičce.

Klíčové principy

• Žádné uložené secrets. Certifikát, OAuth client id/secret, access token, APIKEY i TPP name přicházejí per-request v hlavičkách (viz authentication.md). V env jsou jen ne-secret URL a metadata.
• Věrný průchod dat. Čtecí (GET) odpovědi a méně stabilní těla (consent, direct-debit, sign) se předávají jako surové JSON (JsonNode), takže se neztrácí žádné pole. Typovaná těla mají jen platba a trvalý příkaz (pro kvalitní Swagger), s additionalData pro forward-kompatibilitu.
• mTLS per-request. Certifikát z X-CSOB-Certificate (Base64 PFX) se načte do paměti (nikdy na disk) a použije pro TLS handshake. HttpClient se cachuje podle thumbprintu certifikátu kvůli znovupoužití spojení.
• Reverse proxy. OpenAPI servers se nastavuje z ROOT_PATH, takže Swagger „Try it out“ volá přes /apps/csob/... (Caddy handle_path prefix předtím odstraní).

Mapování na ČSOB

Tato služba	ČSOB PSD2 (relativně k CSOB_API_BASE_URL)
GET /accounts	GET /my/accounts
GET /accounts/{id}/balance	GET /my/accounts/{id}/balance
GET /accounts/{id}/transactions	GET /my/accounts/{id}/transactions
GET /accounts/{id}/transactions/awaiting	GET /my/accounts/{id}/transactions/awaiting
GET /accounts/{id}/standing-orders	GET /my/accounts/{id}/standingorders
GET /accounts/{id}/direct-debits	GET /my/accounts/{id}/directdebits
POST /payments	POST /my/payments
GET /payments/{id} / /status	GET /my/payments/{id} / /status
`POST	GET
…/standing-orders…	…/my/standingorders…
…/direct-debits…	…/my/directdebits…
`POST	GET

Cesty jsou centralizované v Client/CsobApiPaths.cs.

Co je vědomě mimo rozsah (zatím nenapojeno)

V souladu s philosophy sesterské služby idoklad (dokumentovat, co není napojeno):

• Batch payments (/batchpayments) a co-signing list (/authorizations) z COBS PISP.
• PIISP balance check (/balanceCheck).
• Šifrování hlavičkových credentials (jako v microsoft-365-service) – odloženo, spoléháme na TLS.

Ověření a rizika

• Build je čistý (0 warnings). Lokálně ověřeno: /health, /docs, OpenAPI servers=/apps/csob, 401 bez credentials, 400 při neplatném certifikátu, dokumentace credential hlaviček per operace.
• Reálné ČSOB volání vyžaduje platnou PSD2 licenci + eIDAS QWAC certifikát, takže ho nelze otestovat bez produkčních údajů klienta.
• OAuth authorize/token URL a přesný tvar sign sub-cest pocházejí z výzkumu COBS + ČSOB portálu; URL jsou env-konfigurovatelné a cesty centralizované – při odchylce ČSOB portálu je oprava jednoho místa.