Entita Bankovní účet (BankAccount)

Entita BankAccount reprezentuje bankovní účet vedený v některé z bank. Uchovává informace o číslu účtu, IBAN, credentials pro přístup k bankovnímu API, aktuální zůstatek a vazby na transakce.

Klíčové atributy

Základní informace

• Název (name): Název účtu (volitelné, lze nechat prázdné)
• Popis (description): Textový popis účtu
• Povoleno (enabled): Indikátor, zda je účet aktivní (bool, default: true)

Bankovní údaje

• Číslo účtu (bankAccountNumber): Číslo bankovního účtu (max 150 znaků)
  • Speciální typ pole: bankAccountNumber
• IBAN (iban): International Bank Account Number (max 100 znaků)
• SWIFT (swift): SWIFT/BIC kód banky (max 100 znaků)
• Typ (type): Typ účtu
  • domestic - Domácí účet (default)
  • foreign - Zahraniční účet

Finanční údaje

• Zůstatek (balance): Aktuální zůstatek na účtu (currency)

API přístup

• API Token (apiToken): Token pro přístup k bankovnímu API (max 150 znaků)
• E-mail (email): E-mail pro přístup k API (max 150 znaků)
• Credential (credential): Přihlašovací údaje (linkParent)
  • Podporované typy:
    • UniCreditCredential
    • CsobCredential
    • CeskaSporitelnaCredential
    • VubCredential

Vazby

• Banka (bank): Banka, u které je účet veden (povinné)
• E-mail banky (bankEmail): Foreign field - notifikační e-mail z banky (readonly)
• Bankovní transakce (bankTransactions): Seznam transakcí na tomto účtu

Adresa

• Adresa (adress): Adresa spojená s účtem (address type)

Systémová pole

• Vytvořeno (createdAt): Datum a čas vytvoření (readonly)
• Upraveno (modifiedAt): Datum a čas poslední úpravy (readonly)
• Vytvořil (createdBy): Uživatel, který záznam vytvořil (readonly)
• Upravil (modifiedBy): Uživatel, který záznam naposledy upravil (readonly)
• Přiřazeno (assignedUser): Přiřazený uživatel
• Týmy (teams): Týmy s přístupem k záznamu

---

Technické informace

Backend

Třída entity

• Cesta: Espo\Modules\Banking\Entities\BankAccount
• Namespace: Espo\Modules\Banking\Entities
• Konstanta: ENTITY_TYPE = 'BankAccount'

Definice entity

Soubor: backend/Resources/metadata/entityDefs/BankAccount.json

Klíčová pole:

{
  "bankAccountNumber": {
    "type": "bankAccountNumber",
    "maxLength": 150,
    "trim": true
  },
  "iban": {
    "type": "varchar",
    "maxLength": 100
  },
  "type": {
    "type": "enum",
    "options": ["domestic", "foreign"],
    "default": "domestic",
    "maxLength": 100
  },
  "balance": {
    "type": "currency"
  },
  "enabled": {
    "notNull": true,
    "type": "bool",
    "default": true
  },
  "credential": {
    "type": "linkParent",
    "entityList": [
      "UniCreditCredential",
      "CsobCredential",
      "CeskaSporitelnaCredential",
      "VubCredential"
    ],
    "view": "banking:views/bank-account/fields/credential"
  }
}

Vazby (links):

• bank: belongsTo → Bank (foreign: 'bankAccounts')
• bankTransactions: hasMany → BankTransaction (foreign: 'bankAccount')
• credential: belongsToParent (foreign: 'bankAccount')
• createdBy: belongsTo → User
• modifiedBy: belongsTo → User
• assignedUser: belongsTo → User
• teams: hasMany → Team

Indexy:

• name: columns: [name, deleted]
• assignedUser: columns: [assignedUserId, deleted]

Kolekce:

• Výchozí řazení: createdAt DESC
• Textové vyhledávání: name
• Full-text search: vypnuto
• Count: povoleno

Typ pole bankAccountNumber

Speciální typ pole pro bankovní čísla účtů. Zajišťuje:

• Validaci formátu čísla účtu
• Správné zobrazení (prefix/číslo)
• Automatické formátování

Frontend

View

Soubor: client/src/views/bank-account/fields/credential.ts

• Custom view pro zobrazení a výběr credentials

Překlady (cs_CZ)

Soubor: backend/Resources/i18n/cs_CZ/BankAccount.json

Klíčové překlady:

{
  "fields": {
    "bankAccountNumber": "Číslo účtu",
    "iban": "IBAN",
    "swift": "SWIFT",
    "balance": "Zůstatek",
    "type": "Typ účtu",
    "enabled": "Aktivní",
    "credential": "Přihlašovací údaje",
    "bank": "Banka",
    "bankEmail": "E-mail banky"
  },
  "options": {
    "type": {
      "domestic": "Domácí",
      "foreign": "Zahraniční"
    }
  }
}

Použití

Vytvoření bankovního účtu

Při vytváření účtu je nutné:

1. Vybrat banku (povinné)
2. Zadat číslo účtu nebo IBAN
3. Pro zahraniční účty vyplnit SWIFT
4. Pro automatické stahování transakcí nastavit credentials

Napojení na bankovní API

Pro automatické stahování výpisů:

1. Vytvořit příslušné credentials (např. CeskaSporitelnaCredential)
2. Vyplnit přihlašovací údaje do credentials
3. Propojit credentials s bankovním účtem přes pole credential
4. Naplánovat pravidelné stahování (scheduled job)

Credentials podle banky

Česká spořitelna

• Typ: CeskaSporitelnaCredential
• Vyžaduje: API token, client ID
• View: Custom formulář pro Českou spořitelnu

ČSOB

• Typ: CsobCredential
• Vyžaduje: API token, certifikát
• View: Custom formulář pro ČSOB

UniCredit

• Typ: UniCreditCredential
• Vyžaduje: Přihlašovací údaje k API
• View: Custom formulář pro UniCredit

VÚB

• Typ: VubCredential
• Vyžaduje: API credentials
• View: Custom formulář pro VÚB

Sledování zůstatku

Pole balance se automaticky aktualizuje při:

• Importu nových transakcí
• Ruční aktualizaci přes API
• Synchronizaci s bankou

Workflow

Proces stahování transakcí

1. Scheduled Job se spustí
2. Načte všechny aktivní BankAccount (enabled = true)
3. Pro každý účet s credentials:
   a. Ověří přihlašovací údaje
   b. Zavolá bankovní API
   c. Stáhne nové transakce
   d. Vytvoří BankTransaction záznamy
   e. Aktualizuje zůstatek (balance)
4. Pokud jsou zapnuté notifikace, upozorní uživatele

Doporučené postupy

1. Používejte správný formát čísla účtu:

   • Domácí: 123456-1234567890/0800
   • Zahraniční: Vyplňte IBAN a SWIFT

2. Zabezpečení credentials:

   • Credentials jsou uloženy odděleně od účtu
   • Přístup k credentials je omezen ACL
   • API tokeny by měly mít omezená oprávnění

3. Aktivní/Neaktivní účty:

   • Neaktivní účty (enabled = false) se přeskakují při stahování
   • Použijte pro uzavřené nebo dočasně nepoužívané účty

4. Typ účtu:

   • Pro domácí účty je vždy vyžadováno číslo účtu
   • Pro zahraniční účty používejte IBAN a SWIFT

Příklady

Příklad domácího účtu

Název: Hlavní běžný účet
Banka: Česká spořitelna, a.s.
Typ účtu: Domácí
Číslo účtu: 123456-1234567890/0800
IBAN: CZ6508000000001234567890
Povoleno: ✓
Credential: [CeskaSporitelnaCredential #1]

Příklad zahraničního účtu

Název: EUR účet
Banka: UniCredit Bank
Typ účtu: Zahraniční
IBAN: SK3112000000198742637541
SWIFT: UNCRSKBX
Povoleno: ✓
Credential: [UniCreditCredential #2]

Poznámky

• Optimistic concurrency control je vypnuté
• Záznamy podporují týmový přístup
• Smazané záznamy jsou soft-delete
• Pole bankEmail je foreign field - automaticky se načítá z entity Bank