Dokumentace k Dativery Payment API

  • Nejprve je potřeba aktivovat scénář integrace takto:
    • Vyberete banku v seznamu https://app.dativery.com/apps/dativery-universal-api/
    • Aktivujete scénář a dokončíte konfiguraci
    • Na stránce flow zcela dole zkopírujete URL API rozhraní: https://app.dativery.com/prod/api/v1/hooks/flow/31dff1ed-ab62-4ce3-8cd1-891a3b94d9ff/0863f4cb-421e-4775-8f0a-c5fe75690e63/get-payments/?fromDate=YYYY-MM-DD&toDate=YYYY-MM-DD
  • Parametry fromDate a toDate jsou povinné a ve formátu
    YYYY-MM-DD. Doporučujeme stahovat spíše kratší období (např. jeden nebo více dnů).
  • Pro použití musí být aktivováno Dativery TrustyID.
  • Doporučujeme stahovat platby pro dnešní den a pak následně v noci posledních 7 dní, protože u některých bank se objevují platby zpětně.
  • Je-li položen dotaz na platby, které byly provedené dříve než začátek jejich zpracování, zobrazí se chyba.

Struktura poskytnutých dat

Název pole v API Typ pole Název Popis
key string ID transakce Unikátní ID v rámci jednoho dne
shortKey string (7) Zkrácené ID transakce Unikátní zkrácené ID v rámci jednoho dne
com.dativery.model.sharedFields.incoming@incoming boolean Příchozí platba Hodnota určuje, zda jde z pohledu bankovního účtu o příchozí či odchozí platbu (resp. kreditní či debetní operaci). Hodnota může být nahrazena uvedením znaménka u částky.
com.dativery.model.entities.payments@amountSC number Částka Záporné hodnoty jsou považovány za odchozí platby, kladné za příchozí. Pokud je ovšem nastaveno incoming=true nebo outgoing=true, měla by částka být kladná (záporná má stejný význam jako kladná). Pokud se jedná o vrácení platby, mělo by být nastaveno isRefund=true.
com.dativery.model.entities.bankAccountTransactions@transactionFeeSC number Poplatek Částka poplatku. Pokud je součástí platby i poplatek, uveďte jej zde. Pokud je celá platba poplatkem, použijte isTransactionalFee.
com.dativery.model.entities.bankTransactionDocuments@paymentStatementNumber string Číslo výpisu Pokud nám zdrojový systém poskytne číslo výpisu, vyplníme jej. Ve většině případů jej nedostáváme.
com.dativery.model.entities.payments@isFee boolean Je celá platba poplatkem? Pokud je celá platba poplatkem, bude tak i zaúčtována. Částka je v amount. Nelze kombinovat s transactionalFeeAmount.
com.dativery.model.entities.currencies@currencyCode string Kód měny účtu Odpovídá měně účtu, resp. v jakých měnách lze účet vést v případě multiměnových účtů. V tříznakovém formátu dle ISO, např. CZK, EUR, USD, …
com.dativery.model.entities.bankAccountTransactions@unifiedDateOfPayment datetime Datum a čas platby Dativery u platby rozlišuje několik kalendářních dat, ale pro účetnictví stačí obvykle zvolit jedno z těchto dat.
com.dativery.model.components.czSkDomesticPaymentsSymbols@variableSymbol string Variabilní symbol Variabilní symbol platby používaný v Česku a na Slovensku. Při případném párování jsou ignorovány všechny úvodní nuly, tj. hodnota je uvažována jako číslo a nikoliv jako řetězec.
com.dativery.model.components.czSkDomesticPaymentsSymbols@specificSymbol string Specifický symbol Specifický symbol platby používaný v Česku a na Slovensku.
com.dativery.model.components.czSkDomesticPaymentsSymbols@constantSymbol string Konstantní symbol Konstantní symbol platby používaný v Česku a na Slovensku.
com.dativery.model.entities.bankAccounts@bankAccountPrefixAndNumber string Číslo protiúčtu bez banky Číslo protiúčtu včetně předčíslí, ale bez číselného kódu banky. Číslo není povinné.
com.dativery.model.entities.bankAccounts@bankNumberCode string Kód banky protiúčtu Čtyřmístný číselný kód banky protiúčtu používaný v Česku. Není povinné
com.dativery.model.entities.bankAccounts@iban string IBAN protiúčtu Mezinárodní číslo protiúčtu. Může být vyplněné současně s číslem protiúčtu, není povinné.
com.dativery.model.entities.bankAccounts@bic string BIC kód protiúčtu (SWIFT kód) Kód BIC banky protiúčtu, není povinné.
com.dativery.model.entities.bankAccounts@bankAccountName string Název účtu protistrany.
com.dativery.model.sharedFields.privateNotes@privateNotes string Můj popis Popis platby.
com.dativery.model.sharedFields.description@description string Popis protistrany Popis platby protistranou.
com.dativery.model.entities.bankAccountTransactions@instructedAmountSC number Částka v jiné měně Částka v jiné měně než je měna účtu. Bude prázdné v případě, že měna platby je shodná s měnou účtu.
com.dativery.model.entities.bankAccountTransactions@instructedAmountCurrencyCode string Kód jiné měny platby Kód měny platby, pokud je jiná než měna účtu. Bude prázdné v případě, že měna platby je shodná s měnou účtu.
com.dativery.model.components.document.currencyAndExchange@exchangeRate number Směnný kurz Koeficient směnného kurzu použitého pro automatickou konverzi.
com.dativery.model.entities.payments@isRefund boolean Jedná se o vratku? Pokud se jedná o vratku (refund), vrací se peníze. Např. vratka příchozí platby je označena jako incoming=false a současně isRefund=true. Pro některé systémy (např. Pohoda) se potom mění z odchozí na příchozí a částka se převede na zápornou.

Jsou obsažená jak obecná pole (používaná napříč různým zdroji plateb), tak i pole specifická pro konkrétní systémy. Je-li nějaké pole stejného významu duplicitně, doporučujeme výhradně použít obecný sloupec (tj. com.dativery.model….).

Identifikátor záznamů

Banky mají obecně velký problém s jednoznačnou identifikací záznaml transakcí. Proto jsme vytvořili Dativery TrustyID, který přiděluje vlastní identifikátory transakcím v případě, kdy jsou duplicitní. Snažíme se zachovat původní identifikátor, ale někdy je potřeba jej změnit. Identifikátor je platný pouze společně s kalendářním datem. Stejné ID se tedy může opakovat například následující rok. Banky v tomto směru neposkytují žádnou záruku.

Máte přístupné dva identifikátory:

  • key – dlouhý identifikátor (klidně 100 znaků)
  • shortKey – krátký 7 znaký identifikátor. Vychází z „key“, ale někdy může být jiný, protože by došlo k duplicitě.

Datum záznamu

Každá platba má přidělené datum. Může se ovšem stát, že se toto datum ve zdroji plateb změní nebo se platba objeví v minulosti.
Příklady:

  • Platba se objeví několik dní zpětně. Proto z bank v noci stahujeme 7 dní zpětně. Doporučujeme to i vám.
  • Platba se posune do budoucnosti – sobotní platba se zaúčtuje v pondělí. V takovém případě stále vracíme sobotní datum, i když aktuálně už je platba pondělní. A současně zabráníme zapsání duplicitní platby (má jiné datum).

Postup zpracování poplatků

Existují 3 typy plateb:

  • Běžná platba – isFee=false a transactionFeeSC buď není nebo je 0.
  • Platba s poplatkem – isFee=false, ale částka poplatku je uvedena v transactionFeeSC.
  • Poplatek – isFee=true a částka je v amountSC.

Zpracování vratek

Vratka je vrácení platby, refund. Tj. platba přišla, ale následně byla vrácena a tak se nepočítá do obratu. Pro některé systémy (např. Pohoda) je nutné vratku účtovat jako záporný příjem a nikoliv výdej. Proto vratky zpracováváme takto: isRefund=true a incoming=false. Pak se jedná o odchozí platbu vratky.

Pokud pro váš systém není nutné pracovat s vratkami, tak lze toto zcela ignorovat a prostě zapsat incoming=false.

Měny a platby

Vždy platí, že měna platby musí být shodná s měnou účtu. Pokud máte multiměnový účet, je potřeba zapisovat je do více účtů. Pokud peníze dorazí v jiné měně, než je vedený účet, provede bance automatický převod. Např. na EUR účet dorazí USD a dojde k přepočtu na EUR a do platby je zapsáno EUR.

V určitých případech jsme schopni uvést původní přikázanou částku i s měnou. Tyto hodnoty jsou pak uvedené v instructedAmountCurrencyCode a instructedAmountSC. A kurz je uvedený v exchangeRate.