Přeskočit na hlavní obsah

Entita Bankovní transakce (BankTransaction)

Entita BankTransaction reprezentuje bankovní transakci (příchozí nebo odchozí platbu) na bankovním účtu. Uchovává informace o částce, datu, protiúčtu, symbolech platby a automaticky se páruje s fakturami v systému.

Klíčové atributy​

Základní informace​

  • Název (name): Automaticky generovaný název transakce (readonly)
  • Popis (description): Textový popis/poznámka transakce (readonly)
  • Typ transakce (type): Směr transakce (readonly)
    • Incoming - Příchozí platba (zelená)
    • Outgoing - Odchozí platba (červená)
  • Datum transakce (transactionDate): Datum a čas provedení transakce (readonly)

Finanční údaje​

  • Částka (amount): Částka transakce v měně (currency, required, readonly)

Bankovní účet​

  • Bankovní účet (bankAccount): Účet, na kterém byla transakce provedena (required, readonly)

Protiúčet​

  • Název protiúčtu (counterAccountName): Název majitele protiúčtu (max 150 znaků, readonly)
  • Číslo protiúčtu (counterBankAccountNumber): Číslo protiúčtu (bankAccountNumber type, max 30 znaků)
  • Banka protiúčtu (counterBank): Banka protiúčtu (link, readonly)

Symboly platby​

  • Variabilní symbol (variableSymbol): VS pro párování s fakturami (max 150 znaků, readonly)
  • Konstantní symbol (constantSymbol): KS (max 10 znaků, readonly)
  • Specifický symbol (specificSymbol): SS (max 15 znaků, readonly)

Typ transakce​

  • Typ transakce (transactionType): Způsob platby (default: Bank)
    • Bank - Bankovní převod
    • Card - Kreditní karta

Kartové platby​

  • Číslo karty (cardNumber): Číslo platební karty (max 20 znaků, readonly)
  • Držitel karty (cardHolder): Jméno držitele karty (max 150 znaků, readonly)

Propojení s fakturami​

  • Vydaná faktura (invoice): Propojení s vydanou fakturou (Invoice)
  • Přijatá faktura (supplierInvoice): Propojení s přijatou fakturou (SupplierInvoice)
  • Vydaná zálohová faktura (proformaInvoice): Propojení s proformou (ProformaInvoice)
  • Přijatá zálohová faktura (receivedProformaInvoice): Propojení s přijatou proformou (ReceivedProformaInvoice)
  • Je přiřazena faktura (isInvoiceAssigned): Indikátor, zda je transakce spárovaná (bool, notStorable, readonly)
  • Faktura nenalezena (invoiceNotFound): Označení, že faktura nebyla nalezena (bool, default: false)
    • Tooltip: "Označuje transakce, pro které nebyla nalezena nebo jednoznačně určena odpovídající faktura"

Systémová pole​

  • Foreign ID (foreignId): ID z bankovního systému (max 150 znaků, readonly)
  • Z e-mailu (fromEmail): Propojení se zdrojovým e-mailem (pokud importováno z mailu)
  • 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\BankTransaction
  • Namespace: Espo\Modules\Banking\Entities
  • Konstanta: ENTITY_TYPE = 'BankTransaction'

Definice entity​

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

Klíčová pole:

{
  "type": {
    "style": {
      "Incoming": "success",
      "Outgoing": "danger"
    },
    "type": "enum",
    "readonly": true,
    "options": ["Incoming", "Outgoing"],
    "displayAsLabel": true,
    "default": "Outgoing"
  },
  "amount": {
    "type": "currency",
    "readonly": true,
    "required": true
  },
  "bankAccount": {
    "type": "link",
    "readonly": true,
    "required": true
  },
  "variableSymbol": {
    "type": "varchar",
    "readonly": true,
    "maxLength": 150
  },
  "transactionType": {
    "type": "enum",
    "options": ["Bank", "Card"],
    "default": "Bank",
    "audited": true,
    "notNull": true
  },
  "invoiceNotFound": {
    "type": "bool",
    "default": false,
    "tooltip": true,
    "notNull": true
  },
  "isInvoiceAssigned": {
    "type": "bool",
    "default": false,
    "notStorable": true,
    "readOnly": true
  }
}

Vazby (links):

  • bankAccount: belongsTo → BankAccount (foreign: 'bankTransactions')
  • counterBank: belongsTo → Bank (foreign: 'bankTransactions')
  • fromEmail: belongsTo → Email (foreign: 'bankTransactions')
  • invoice: belongsTo → Invoice
  • supplierInvoice: belongsTo → SupplierInvoice
  • proformaInvoice: belongsTo → ProformaInvoice
  • receivedProformaInvoice: belongsTo → ReceivedProformaInvoice
  • 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

Frontend​

Překlady (cs_CZ)​

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

{
  "fields": {
    "invoice": "Vydaná faktura",
    "proformaInvoice": "Vydaná zálohová faktura",
    "supplierInvoice": "Přijatá faktura",
    "receivedProformaInvoice": "Přijatá zálohová faktura",
    "isInvoiceAssigned": "Přiřazeno",
    "transactionDate": "Datum transakce",
    "constantSymbol": "Konstantní symbol",
    "amount": "Celkem bez DPH",
    "variableSymbol": "Variabilní symbol",
    "counterAccountName": "Název protiúčtu",
    "counterBank": "Banka protiúčtu",
    "specificSymbol": "Specifický symbol",
    "counterBankAccountNumber": "Číslo protiúčtu",
    "type": "Typ",
    "transactionType": "Typ transakce",
    "invoiceNotFound": "Faktura nenalezena"
  },
  "options": {
    "type": {
      "Incoming": "Příchozí",
      "Outgoing": "Odchozí"
    },
    "transactionType": {
      "Bank": "Bankovní převod",
      "Card": "Kreditní karta"
    }
  },
  "tooltips": {
    "invoiceNotFound": "Označuje transakce, pro které nebyla nalezena nebo jednoznačně určena odpovídající faktura"
  }
}

Použití​

Automatické vytváření transakcí​

Transakce se vytvářejí automaticky při:

  1. Stahování z bankovního API: Scheduled job stahuje nové transakce z banky
  2. Import z e-mailu: Zpracování bankovních výpisů zaslaných e-mailem
  3. Manuální import: Ruční import z CSV nebo jiného formátu

Párování s fakturami​

Systém automaticky páruje transakce s fakturami podle:

Variabilní symbol (VS)​
  • Pokud VS transakce odpovídá VS na faktuře, transakce se automaticky propojí
  • Pro příchozí platby (Incoming):
    • Hledá se v Invoice (vydané faktury)
    • Hledá se v ProformaInvoice (vydané zálohové faktury)
  • Pro odchozí platby (Outgoing):
    • Hledá se v SupplierInvoice (přijate faktury)
    • Hledá se v ReceivedProformaInvoice (přijaté zálohové faktury)
Pokud faktura není nalezena​
  • Pole invoiceNotFound se nastaví na true
  • Transakce se zobrazí ve filtru "Faktura nenalezena"
  • Uživatel může manuálně přiřadit správnou fakturu

Workflow párování​

1. Nová transakce je importována
2. Systém zkontroluje typ (Incoming/Outgoing)
3. Pokud je vyplněn variableSymbol:
   a. Hledá faktury s odpovídajícím VS
   b. Kontroluje částku (měla by odpovídat)
   c. Kontroluje stav faktury (měla by být vystavena)
4. Pokud je nalezena jediná shoda:
   a. Transakce se propojí s fakturou
   b. isInvoiceAssigned = true
   c. invoiceNotFound = false
5. Pokud není nalezena žádná nebo více shod:
   a. invoiceNotFound = true
   b. isInvoiceAssigned = false
6. Faktura se označí jako uhrazená (pokud je uhrazena celá částka)

E-mailový import​

Pokud je transakce importována z e-mailu:

  • Pole fromEmail obsahuje odkaz na zdrojový e-mail
  • Umožňuje zpětné dohledání původního výpisu
  • Užitečné pro audit a řešení sporů

Readonly vs Editable​

Většina polí je readonly, protože:

  • Transakce reprezentují data z banky
  • Manuální úpravy by mohly způsobit nesoulad s bankovními výpisy
  • Ochrana před nechtěnými změnami

Editovatelná pole:

  • invoiceNotFound - může být manuálně upraveno
  • Propojení s fakturami - lze manuálně přiřadit/odpojit
  • assignedUser - lze přiřadit uživatele
  • teams - lze upravit týmy

Doporučené postupy​

  1. Nenechávejte transakce bez faktury:

    • Pravidelně kontrolujte filtr "Faktura nenalezena"
    • Manuálně přiřaďte faktury, kde se nepodařilo automatické párování

  2. Kontrolujte částky:

    • Částka na transakci by měla odpovídat částě faktury
    • Rozdíly mohou indikovat problém s VS nebo fakturou

  3. Používejte konzistentní VS:

    • VS na fakturách by měl být unikátní
    • Používejte stejný formát VS napříč systémem

  4. Sledujte typ transakce:

    • Příchozí = peníze přišly na náš účet = vydané faktury
    • Odchozí = peníze odešly z našeho účtu = přijaté faktury

  5. Kartové transakce:

    • Pro kartové transakce je k dispozici číslo a držitel karty
    • Sledujte typ transactionType pro reporting

Příklady​

Příklad příchozí platby​

Typ: Příchozí
Datum transakce: 2024-11-19 10:30:00
Částka: 12,100 CZK
Bankovní účet: Hlavní běžný účet
Variabilní symbol: 2024001
Číslo protiúčtu: 987654-3210987654/0100
Název protiúčtu: ACME s.r.o.
Banka protiúčtu: Komerční banka

Vydaná faktura: #2024001 (automaticky spárováno)
Je přiřazena faktura: ✓
Faktura nenalezena: □

Příklad odchozí platby bez faktury​

Typ: Odchozí
Datum transakce: 2024-11-19 14:15:00
Částka: 5,500 CZK
Bankovní účet: Hlavní běžný účet
Variabilní symbol: 123456
Číslo protiúčtu: 111111-2222222222/0800
Název protiúčtu: Dodavatel XYZ

Přijatá faktura: (nepřiřazeno)
Je přiřazena faktura: □
Faktura nenalezena: ✓

Příklad kartové transakce​

Typ: Odchozí
Typ transakce: Kreditní karta
Datum transakce: 2024-11-18 18:45:00
Částka: 1,250 CZK
Bankovní účet: Firemní karta
Číslo karty: **** **** **** 1234
Držitel karty: Jan Novák
Popis: Nákup kancelářských potřeb

Poznámky​

  • Transakce jsou readonly pro zachování integrity dat z banky
  • Foreign ID umožňuje prevenci duplicit při opakovaném importu
  • Všechny vazby na faktury jsou volitelné (žádná není required)
  • Pole isInvoiceAssigned je vypočítané (notStorable) - vrací true, pokud existuje jakékoli propojení s fakturou