Dokumentace
Dativery Payments API umožňuje unifikovat API napříč bankami, platebními bránami a vším, co Dativery v oblasti plateb a úhrad podporuje. Data jsou vždy cachovaná v Dativery, protože musíme být schopni garantovat unikátnost dat (viz technologie Dativery TrustyID).
Postup napojení na Dativery Payments API vypadá tak, že klient aktivuje příslušný scénář propojení. Po aktivaci a získá část URL, které lze použít pro načítání dat:
https://app.dativery.com/api/v1/hooks/flow/xxx/xxx/get-payments?fromDate=2025-04-22&toDate=2025-05-22
Následně lze volat načtení plateb z jednotlivých dní. Alternativou je použití metody Push, kdy přenos dat iniciuje Dativery. Jde o to, že některé systémy předávají platby i zpětně (např. na základě e-mailu).
Při použití Payments API doporučujeme vždy v noci přenést znovu poslední týden. Tento krok zajistí přenesení plateb, které některé banky zařazují do poskytovaných dat zpětně.
- API pro stahování seznamu plateb dle data lze využívat u již používaných napojení (do účetnictví) i lze založit nezávislé napojení.
- Parametry fromDate a toDate jsou povinné, jsou akceptovány formáty detekovatelné knihovnou Moment.js, ovšem doporučovaný datový formát je YYYY-MM-DD.
- Je-li položen dotaz na platby, které proběhly dříve, než je termín zpracovávání plateb s využití technologie TrustyID, zobrazí se chybové hlášení:
Příklad dat:
{
"key": "0c6db43fc66d177562d6",
"com.dativery.model.sharedFields.outgoing@outgoing": true,
"com.dativery.model.sharedFields.incoming@incoming": false,
"com.dativery.model.entities.payments@amountSC": -5708.2,
"com.dativery.model.entities.bankAccountTransactions@amountAC": -5708.2,
"com.dativery.model.entities.currencies@currencyCode": "CZK",
"com.dativery.model.entities.bankAccountTransactions@accountCurrencyCode": "CZK",
"com.dativery.model.entities.bankAccountTransactions@bookingDate": "2024-04-23T00:00:00.000+02:00",
"com.dativery.model.entities.bankAccountTransactions@instructedAmountSC": -5708.2,
"com.dativery.model.components.czSkDomesticPaymentsSymbols@constantSymbol": "1178",
"com.dativery.model.entities.bankAccountTransactions@instructedAmountCurrencyCode": "CZK",
"cz.csas.databanking2.transactions@transactionDescription2": "US HTTPSSENTRY.I SENTRY",
"cz.csas.databanking2.transactions@transactionDescription3": "USD 234.00 d.přep.22.04.2024",
"cz.csas.databanking2.transactions@item": "PLATBA KARTOU OBCHODNÍK",
"cz.csas.databanking2.transactions@transactionDescription1": "XXXXXXXXXXXX3188 d.tran.22.04.2024",
"cz.csas.databanking2.transactions@transactionDescription4": "234.00 kurz USD 24.394",
"cz.csas.databanking2.transactions@valueDate": "2024-04-23T00:00:00.000+02:00",
"com.dativery.model.entities.payments@dateOfPayment": "2024-04-23T00:00:00.000+02:00",
"cz.csas.databanking2.transactions@effectiveForeignCurrencyDate": "2024-04-23T00:00:00.000+02:00",
"com.dativery.model.components.czSkDomesticPaymentsSymbols@variableSymbol": "22042024",
"com.dativery.model.components.czSkDomesticPaymentsSymbols@specificSymbol": "4907293188",
"com.dativery.model.entities.bankAccounts@bankNumberCode": "0800",
"com.dativery.model.entities.bankAccounts@bankAccountNumber": "33126726",
"com.dativery.model.entities.bankAccounts@bankAccountPrefix": "150199",
"cz.csas.databanking2.transactions@transactionTypeDescription": "PLATBA KARTOU OBCHODNÍK XXXXXXXXXXXX3188 d.tran.22.04.2024 US HTTPSSENTRY.I SENTRY USD 234.00 d.přep.22.04.2024 234.0",
"com.dativery.model.entities.bankAccounts@bankAccountPrefixAndNumber": "150199-33126726",
"com.dativery.model.entities.bankAccountTransactions@unifiedDateOfPayment": "2024-04-23T00:00:00.000+02:00",
"cz.csas.databanking2.transactions@dativeryTransactionIdSource": "1680011953|22042024|-5708.2|CZK|2024-04-23T00:00:00+02:00|22042024|4907293188|150199-33126726/800|",
"cz.csas.databanking2.transactions@dativeryTransactionId": "0c6db43fc66d177562d6",
"cz.csas.databanking2.transactions@itemIdentification": "68574616a0d4b25c5566",
"cz.csas.databanking2.transactions@transactionId": "22042024",
"com.dativery.model.components.document.numbers@documentInternalNumber": "22042024",
"com.dativery.model.entities.bankAccountTransactions@noteForReceiver": "PLATBA KARTOU OBCHODNÍK XXXXXXXXXXXX3188 d.tran.22.04.2024 US HTTPSSENTRY.I SENTRY USD 234.00 d.přep.22.04.2024 234.0",
"origKey": "0c6db43fc66d177562d6",
"transactionId": "0c6db43fc66d177562d6",
"shortKey": "9ed3006"
}Key je unikátní identifikátor platby v rámci dne.
Zahrnutá jsou jak obecná pole, které naleznete napříč různými zdroji dat, tak i pole specifická pro daný zdroj dat. Je-li některé pole stejného významu uvedeno duplicitně, doporučujeme použít obecný sloupec (tj. com.dativery.model….).
Příklad samostatného scénáře: https://app.dativery.com/s/csas-databanking-statements-to-dativery-universal-api/
Dokumentace položek
| Položka | Typ | Název | Popis |
|---|---|---|---|
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. |
amount | number | Částka | Záporné hodnoty jsou považovány za odchozí platby, kladné za příchozí. Některé zdroje dat uvádějí jen absolutní částku a proto je vhodné využíti i booleanové hodnoty v polích incoming a outgoing=true, měla by částka být kladná (záporná má stejný význam jako kladná). |
transactionalFeeAmount | number | Poplatek | Částka poplatku. Pokud je součástí platby i poplatek, uveďte jej zde. Pokud je celá platba poplatkem, použijte isTransactionalFee |
isTransactionalFee | boolean | Je celá platba poplatkem? | Pokud je celá platba poplatkem, bude tak i zaúčtována. Částka je v amount. Nelze kombinovat s transactionalFeeAmount |
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, ... |
dateOfPayment | datetime | Datum a čas platby | Dativery u platby rozlišuje několik kalendářních dat datumů, ale pro účetnictví stačí obvykle zvolit jedno z těchto dat. |
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. |
specificSymbol | string | Specifický symbol | Specifický symbol platby používaný v Česku a na Slovensku. |
constantSymbol | string | Konstantní symbol | Konstantní symbol platby používaný v Česku a na Slovensku. |
bankAccountNumber | string | Číslo protiúčtu bez banky | Číslo protiúčtu včetně předčíslí, ale bez číselného kódu banky. Číslo není povinné. |
bankNumberCode | string | Kód banky protiúčtu | Čtyřmístný číselný kód banky protiúčtu používaný v Česku. Není povinné |
transactionType | string | Způsob platby | Popsání způsobu provedení platby, např. karta, převodem. |
iban | string | IBAN protiúčtu | Mezinárodní číslo protiúčtu. Může být vyplněné současně s číslem protiúčtu, není povinné. |
bic | string | BIC kód protiúčtu (SWIFT kód) | Kód BIC banky protiúčtu, není povinné. |
bankAccountName | string | Název účtu protistrany. | |
privateNote | string | Můj popis | Popis platby. |
description | string | Popis protistrany | Popis platby protistranou. |
transactionId | string | Identifikace platby | Unikátní identifikace platby, unikátní minimálně v kontextu bankovního účtu. Důvodem je potřeba určit, zda byla platba do cílového systému již zapsána či nikoliv. |
originalAmount | 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. |
originalAmountCurrencyCode | 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. |
exchangeRate | number | Směnný kurz. | Koeficient směnného kurzu použitého pro automatickou konverzi. |
isRefund | boolean | Jedná se o refund? | Pokud se jedná o refund, platba vrací dříve získané peníze. Např. refund příchozí platby je označen jako incoming=false a současně isRefund=true. Pro některé systémy (např. Pohoda) se potom mění ukládaná částka z odchozí na příchozí a částka se převede na zápornou. |