Současná verze Fidoo API je umístěna na https://api.fidoo.com/v2/ a obsahuje:
- sledování karetních transakcí,
- přehledy o uživatelích aplikace,
- přehled o Fidoo kartách,
- orientace v parametrech a zůstatcích na Fidoo kartách,
- vytvoření nového uživatele a objednání osobní Fidoo karty,
- dobití a odbití osobní a týmové karty.
Generování API klíče
API klíč vygeneruje Hlavní správce v aplikaci Fidoo, API klíč je nutné vložit do hlavičky X-Api-Key v provolávaných dotazech.
Popis jednotlivých public API volání
Lidé
/v2/user/get-user /v2/user/get-user-by-email| Hodnota | Popis |
| userId | Unikátní identifikátor uživatele ve Fidoo |
| firstName | Jméno uživatele |
| lastName | Příjmení uživatele |
| Emailová adresa uživatele | |
| phone | Telefon uživatele (který slouží pro ověření) |
| userState | Nabývá hodnot PRAVDA /NEPRAVDA. Pravda značí, že je aplikace pro tohoto uživatele aktivní. |
| employeeNumber | Zaměstnanecké číslo uživatele, pokud je vyplněno v profilu uživatele |
| kycStatus | Nabývá hodnot ověřený/neověřený/ uživatel v závislosti na jeho stavu. |
| language | Vybraný jazyk uživatele (pro aplikaci) |
| position | Pole „Pozice“ na detailu uživatele |
| Hodnota | Popis |
| userId | Unikátní identifikátor uživatele ve Fidoo |
| firstName | Jméno uživatele |
| lastName | Příjmení uživatele |
| Emailová adresa uživatele | |
| phone | Telefon uživatele (který slouží pro ověření) |
| companyId | Unikátní ID společnosti uživatele |
| employeeNumber | Zaměstnanecké číslo uživatele, pokud je vyplněno v profilu uživatele |
| position | Pole „Pozice“ na detailu uživatele |
| userState | Nabývá hodnot ACTIVE / DELETED / NEW. ACTIVE znamená, že je aplikace pro tohoto uživatele aktivní. NEW nově vytvořený |
| deactivated | Nabývá hodnot PRAVDA / NEPRAVDA dle toho, zda je uživatel deaktivovaný |
| lastModified | Datum poslední změny na uživateli |
Karty
| Hodnota | Popis |
| cardId | Unikátní identifikátor každé karty v systému Fidoo |
| maskedNumber | Maskovaný PAN karty – viditelné je prvních 6 čísel a poslední 4 čísla (jde o čísla vytištěné na přední straně karty) |
| expiration | Datum expirace karty |
| embossName | Zadaný název karty v systému Fidoo |
| cardState | Aktuální stav karty k momentu vzniku exportu. Například Objednaná, aktivní atp. |
| cardType | Dle typu karty nabývá hodnot Osobní nebo Týmová |
| userId | Unikátní identifikátory současných uživatelů spojených s kartou – v případě vícero uživatelů jsou odděleny středníkem |
| connectedUserIds | jména současných uživatelů spojených s kartou – v případě vícero uživatelů jsou odděleni středníkem |
| accountingBalance | Současný účetní zůstatek karty |
| availableBalance | Současný disponibilní zůstatek karty |
| blockedBalance | Součet hodnot nezaúčtovaných (blokovaných) transakcí |
| alias | Volitelný název karty pro snadné hledání v systému |
| deliveryEstimate | Odhad doručení karty |
/v2/card/load-card
/v2/card/unload-card
| Hodnota | Popis | Příklad dat |
| cardId | Unikátní identifikátor karty, která má být nabita/vybita | b16d2df4-5c28-4b90-9a8a-a88c3258fa53 |
| amount | Částka, která má být z/na kartu vybita/nabita | 1000 |
| message | (Nepovinná) zpráva zobrazovaná uživateli při nabíjecí/vybíjecí transakci | Peníze na nákup materiálu |
Karetní transakce
/v2/transaction/get-card-transactions
| Hodnota | Popis |
| id | Unikátní identifikátor transakce v systému Fidoo |
| cardId | Unikátní identifikátor karty v systému Fidoo |
| cardEmbossName | Název konkrétní karty |
| cardMaskedNumber | Maskovaný PAN karty – viditelné je prvních 6 čísel a poslední 4 čísla (jde o čísla vytištěné na přední straně karty) |
| transactionDate | Časové razítko vzniku transakce |
| settlementDate | Časové razítko zaúčtování transakce (pokud bylo již zaúčtováno) |
| originalAmount | Částka platební operace |
| originalCurrency | Měna transakce |
| signedAmount | Částka která byla zaúčtovaná (pokud již bylo zaúčtováno) – tato hodnota má opačné znaménko než pole částka transakce |
| serviceFee | Obsahuje údaj o výši poplatku v Kč |
| transactionStatus | Dle aktuální stavu transakce |
| transactionType | Obsahuje informaci o povaze platby – např. platba u obchodníka, výběr hotovosti atp. |
| merchanName | Název obchodníka |
| merchantLocation | Adresa obchodníka |
| merchantCountry | Identifikátor země, na jejímž území k transakci došlo. |
| categoryName | Pokud je vyplněno, obsahuje parametr z pole kategorie obchodníka na kartě spárovaného výdaje |
| expenceID | Unikátní identifikátor připojeného výdaje v systému Fidoo |
| cardType | Typ karty |
Výdaje
/v2/expense/get-expenses| Hodnota | Popis |
| expenseID | Unikátní ID výdaje v systému Fidoo |
| shortId | Zkrácený unikátní identifikátor výdaje |
| name | Název výdaje |
| cardId | Unikátní ID platební karty v systému Fidoo |
| travelReportId | V případě přiřazení výdaje k cesťáku obsahuje unikátní identifikátor daného cesťáku |
| receiptIds | Unikátní Ids připojených účtenek k výdaji (jsou-li připojeny) |
| amount | Hodnota výdaje v původní měně |
| currency | Měna výdaje |
| vatAmount | Výše DPH |
| vatRate | Sazba DPH |
| accountCode | Kód předkontace |
| accountDebit | Hodnota MÁ DÁTI |
| accountCredit | Hodnota DAL |
| vatAccountCode | Kód DPH dané předkontace |
| vatAccountDebit | Hodnota DPH pro MÁ DÁTI |
| vatAccountCredit | Hodnota DPH pro DAL |
| companyExpense | Hodnota firemního výdaje |
| privateAmount | Hodnota soukromého výdaje |
| dateTime | Datum vzniku výdaje |
| taxableDate | Datum zdanitelného plnění |
| classState | Status schvalování |
| merchantIdentificationNumber | IČ obchodníka |
| merchantVatId | DIČ obchodníka |
| merchantName | Název obchodníka |
| merchantCategory | Kategorizace obchodníka |
| merchantAddress | Adresa obchodníka |
| costCenterIds | Kódy nákladových středisek |
| projectIds | Kódy projektů uvedených ve výdaji |
| vatBreakDownId | Členění DPH |
| ownerUserId | Unikátní ID uživatele v systému Fidoo |
| lastEditDateTime | Časové razítko poslední úpravy výdaje |
| type | Typ výdaje (manuální, karetní transakce) |
| closed | True/False, určuje, zda je výdaj uzavřený |
| receiptUrls | URL souborů s účtenkami |
| originalTaxDocumentNumber | Původní číslo daňového dokladu |
| pairingKey | Párovací klíč výdaje |
| Description | Poznámka |
| State | Stav výdaje ve Fidoo (viz Stavy výdajů ve Fidoo) |
Stavy výdajů ve Fidoo
| Systémový stav | Stav ve Fidoo | Popis stavu |
| prepare | Otevřený | Nový výdaj doposud nezpracovaný nebo vrácený zpět uživateli |
| approve | Ke schválení | Odeslaný ke schválení |
| accountantApprove | K uzavření | Čeká na zpracování ze strany účetního |
| personalBill | Uzavřený | Schválený ze strany účetního |
| export | Vyúčtovaný | Osobní vyúčtování s tímto výdajem bylo uzavřeno |
| exported | Exportovaný | Exportovaný v účetní agendě |
Jednotlivé položky výdaje
Na základě unikátního ID výdaje vrací položky tohoto výdaje a následující hodnoty.
| Hodnota | Popis |
| expenseId | Unikátní ID výdaje v systému Fidoo |
| name | Položka – název |
| amount | Položka – hodnota |
| vatAmount | Položka – výše DPH |
| vatRate | Položka – sazba DPH |
| type | Položka – typ (firemní, soukromá) |
| accountCode | Položka – kód předkontace |
| accountCredit | Položka – kód MÁ DÁTI |
| accountDebit | Položka – kód DAL |
| costCenterIds | Položka – nákladové sředisko |
| projectIds | Položka – projekty |
| vatBreakDownId | Položka – kód členění DPH |
| vatAccountCode | Položka – kód předkontace DPH |
| vatAccountDebit | Položka – kód MÁ DÁTI pro DPH |
| vatAccountCredit | Položka – kód DAL pro DPH |
Hotovostní transakce
/v2/cash-transactions/get-cash-transactions| Hodnota | Popis |
| transactionID | ID hotovostní transakce (GUID) |
| shortExpenseId | krátké ID výdaje (pro zachování vazby na výdaj) |
| user | vlastník peněženky, text struktury „firstName lastName“ |
| walletName | název peněženky |
| createTransactionDate | datum vytvoření transakce |
| amountOriginalCurrency | částka transakce v původní měně |
| currency | měna transakce / výdaje |
| transactionType | typ transakce – v úvahu brát pouze hodnoty „expense“, „withdrawal“, „balanceAdjustment“ |
| companyName | název obchodníka (dotahuje se z výdaje) |
| address | adresa obchodníka |
| category | kategorie obchodníka |
| receiptUrls | URL souborů s doklady o nabití/vybití peněženky |
Cesťáky – zprávy
| Hodnota | Popis | Příklad dat |
| travelReportId | Systémové ID zprávy o služební cestě | 27fe8798-07e3-11eb-adc1-0242ac120002 |
| travelReportShortId | ID zprávy o služební cestě | TR-1 |
| travelReportName | Název zprávy o služební cestě | My testing travel order |
| travellerId | Systémové ID cestovatele | 27fe8798-07e3-11eb-adc1-0242ac120002 |
| journeyType | Typ služební cesty | „domestic“ / „foreign“ |
| closed | Uzavřeno | „true“ / „false“ |
| journeyStartDate | Začátek služební cesty | 2018-09-17T13:28:35.382Z |
| journeyEndDate | Konec služební cesty | 2018-09-17T13:28:35.382Z |
| journeyStartPoint | Místo začátku služební cesty | Prague |
| journeyEndPoint | Místo konce služební cesty | Brno |
| mealAllowanceCzk | Náhrady za stravné v CZK | 706.6 |
| pocketMoneyCzk | Peníze na cestu v CZK | 2500 |
| carAllowanceCzk | Náhrada za soukrové vozidlo v CZK | 1354.8 |
| fuelAllowanceCzk | Náhrada za palivo v CZK | 4023 |
| journeyNote | Poznámka | Note |
| reportCreated | Časové razítko vytvoření zprávy o služební cestě | 2018-09-17T13:28:35.382Z |
| createdBy | Systémové ID uživatele, který zprávu vytvořil | 27fe8798-07e3-11eb-adc1-0242ac120002 |
| travelRequestShortId | ID žádosti o služební cestu | TQ-2 |
| projectId | Systémové ID projektu | 0b20bf11-9282-4a98-97e7-85b3d02daa82 |
| costCenterId | Systémové ID nákladového střediska | d4a7fbfb-0531-4ff4-81a7-cf0a3315a975 |
| depositRequested | Výše peněz na cestu, o které uživatel žádal v žádosti | 2000 |
| depositType | Způsob výplaty peněz na cestu: Card – dobití na kartu Cash – výplata hotovosti | Card / Cash |
| travelReportState | Stav zprávy ve Fidoo | viz Stavy cesťáků – zpráv ve Fidoo |
Stavy cesťáků – zpráv ve Fidoo
| Systémový stav | Stav ve Fidoo | Popis stavu |
| prepare | Otevřená | Nová zpráva doposud nezpracovaná nebo vrácená zpět uživateli |
| approve | Ke schválení | Odeslaná ke schválení |
| accountantApprove | K uzavření | Čeká na zpracování ze strany účetního |
| personalBill | Uzavřená | Schválená ze strany účetního |
| export | Vyúčtovaná | Osobní vyúčtování s touto zprávou bylo uzavřeno |
| exported | Exportovaná | Exportovaná v účetní agendě |
Osobní vyúčtování
/v2/personal-billing/get-billings
Pole prvního sheetu – obsahuje souhrnné informace za každé vyúčtování (jeden řádek = jedno vyúčtování)
| Hodnota | Popis |
| userId | unikátní ID uživatele |
| userFirstname | křestní jméno uživatele |
| userLastname | příjmení uživatele |
| employeeNumber | zaměstnanecké číslo |
| personalBillingShortId | unikátní ID vyúčtování |
| personalBillingName | název vyúčtování |
| dateFrom | vyúčtování datum od |
| dateTo | vyúčtování datum do |
| expenseSumCzk | suma výdajů k vyúčtování v CZK (součet za všechny měny) |
| privateExpenseSumCzk | suma soukromých výdajů v CZK (součet za všechny měny) |
| travelAllowanceSumCzk | suma náhrad cest v CZK (součet za všechny měny) |
| cashSettlementSumCzk | suma vyrovnání hotovosti v CZK (součet za všechny měny) |
| giveMoneySumCzk | vyplatit uživateli celkem v CZK (součet za všechny měny) |
| takeMoneySumCzk | strhnout uživateli celkem v CZK (součet za všechny měny) |
| closingDate | datum uzavření vyúčtování |
| closedByUserId | unikátní ID uživatele, které vyúčtování uzavřel |
| closedByUserFirstname | křestní jméno uživatele, který vyúčtování uzavřel |
| closedByUserLastname | příjmení uživatele, který vyúčtování uzavřel |
Pole z druhého sheetu – obsahuje vyúčtování rozpadlé po měnách
| Hodnota | Popis |
| personalBillingShortId | unikátní ID vyúčtování (1 vyúčtování zde může mít více záznamů) |
| currency | měna jednotlivého záznamu |
| privateExpenseSum | suma soukromých výdajů |
| travelAllowanceSum | suma náhrad cest |
| exchangeRateCash | kurz převodu měny |
| cashSettlementSum | suma vyrovnání hotovosti |
| giveMoneySum | vyplatit uživateli celkem |
| takeMoneySum | strhnout uživateli celkem |
Fidoo účet
/v2/mvc-transaction/get-transactions
Poskytuje informace k jednotlivým transakcím na Fidoo účtu (dobití a vybití Fidoo účtu, dobití a vybití karet, poplatky, uhrazená fakturace a další).
| Hodnota | Popis | Příklad dat |
| transactionId | Systémové ID transakce | 567ac61d-11cc-4596-844f-214721b2a4dc |
| transactionCreateDate | Časové razítko vytvoření transakce | 2020-10-15T09:38:59Z |
| transactionType *) | Typ transakce | card-creation-fee |
| transactionOriginalAmount | Původní částka | 99 |
| transactionOriginalCurrency | Původní měna | CZK |
| transactionSettledAmount | Účtovaná částka | -99 |
| transactionSettlementDate | Datum zaúčtování | 2020-10-15T09:39:03Z |
| cardId | Systémové ID platební karty (pouze u transakcí souvisejících s kartami) | 042ca2da-6614-4a10-a575-526fd084f201 |
| cardMaskedNumber | Maskované číslo platební karty | 549546******6231 |
| cardEmbossName | Embosované jméno na kartě | UZIVATELTESTOVACI |
| transactionInitiatedUserEmail | Email uživatele, který transakci inicioval | test@fidoo.com |
| transactionInitiatedUserName | Označení uživatele, který transakci inicioval | Jan Novak |
| transactionNote | Poznámka k transakci | Loading money to the account |
| clientAccountNumber | Číslo protiúčtu | 21312312312/1234 |
| variableSymbol | Variabilní symbol | 123456 |
| specificSymbol | Specifický symbol | 123456 |
*) Popis typů transakcí na Fidoo účtu
| Transaction type | Popis hodnoty |
| atm-fee | Poplatek za výběry z bankomatu |
| balance-adjustment | Doúčtování transakce |
| card-renewal-fee | Poplatek za obnovu Fidoo karty |
| card-creation-fee | Poplatek za výrobu Fidoo karty |
| card-load | Dobití karty |
| card-unload | Odbití prostředků z karty na Fidoo účet |
| fee-balance-adjustment | Bonus |
| insurance-fee | Poplatek za Direct cestovní pojištění |
| monthly-service-fee | Poplatek za vedení Fidoo karty |
| mvc-load | Převod na Fidoo účet |
| mvc-unload | Převod z Fidoo účtu |
| online-account-fee | Poplatek za služby Fidoo |
| other | Ostatní transakce |
| refund | Bonus |
Nastavení
Nákladová střediska
/v2/settings/get-cost-centers – výpis seznamu nákladových středisek
/v2/settings/add-cost-center – vytvoření nákladového střediska
/v2/settings/delete-cost-center – smazání nákladového střediska (přepnutí do stavu „deleted“)
/v2/settings/update-cost-center – aktualizace dat nákladového střediska
Jednoznačným identifikátorem je hodnota v poli „code“.
| Hodnota | Popis | Vzor dat |
| id | Systémové ID položky | d4a7fbfb-0531-4ff4-81a7-cf0a3315a975 |
| code | Kód nákladového střediska ve Fidoo | NS001 |
| name | Název nákladového střediska ve Fidoo | Název střediska nový 1 |
| state | Stav nákladového střediska ve Fidoo – active – aktivní a zobrazuje se uživatelům | active / inactive / deleted |
Projekty
/v2/settings/get-projects – výpis seznamu projektů
/v2/settings/add-project – vytvoření projektu
/v2/settings/delete-project – smazání projektu (přepnutí do stavu „deleted“)
/v2/settings/update-project – aktualizace dat projektu
Jednoznačným identifikátorem je hodnota v poli „code“.
| Hodnota | Popis | Vzor dat |
| id | Systémové ID položky | 3d161bfd-e46e-4afe-ba35-874e4f912db9 |
| code | Kód projektu ve Fidoo | projekt1 |
| name | Název projektu ve Fidoo | Název projektu 1 |
| state | Stav projektu ve Fidoo – active – aktivní a zobrazuje se uživatelům | active / inactive / deleted |
Předkontace
/v2/settings/get-account-assignments – výpis všech zadaných předkontací
/v2/settings/add-account-assignment – vytvoření předkontace
/v2/settings/delete-account-assignment – smazání předkontace (přepnutí do stavu „deleted“)
/v2/settings/update-account-assignment – aktualizace dat předkontace
Jednoznačným identifikátorem předkontace je kombinace hodnot v polích „code“, „debit“, „credit“.
| Hodnota | Popis | Vzor dat |
| id | Systémové ID položky | 87e39a08-8c73-11eb-8dcd-0242ac130003 |
| code | Kód předkontace ve Fidoo | Předkontace1 |
| name | Název předkontace ve Fidoo | Název předkontace 1 |
| description | Popis předkontace | Detailní popis předkontace 1 |
| debit | Číslo účtu „na vrub“ | 518001 |
| credit | Číslo účtu „ve prospěch“ | 321000 |
| type | Typ předkontace (předkontace/dph) | Normal / VAT |
| state | Stav předkontace ve Fidoo – active – aktivní a zobrazuje se uživatelům | active / inactive |
Vozidla
/v2/settings/add-vehicle – vytvoření vozidla
/v2/settings/get-vehicles – výpis všech zadaných vozidel
/v2/settings/update-vehicle – aktualizace dat vozidla
Jednoznačným identifikátorem vozidla je jeho RZ (registrační značka).
| Hodnota | Popis | Vzor dat |
| vehicleid | Systémové ID vozidla | 11ca5afd-deaf-4578-97d5-5c82bffc0e99 |
| ownerid | Systémové ID uživatele vozidla | 0f7a31d9-c2a8-43f8-99db-a3affe0f6163 |
| brand | Značka vozidla | Tesla |
| model | Model vozidla | S |
| registrationNumber | Registrační značka | TA86576 |
| vin | VIN kód vozidla | JDKUKJ849489080 |
| type | Typ vozidla (auto/motocykl/nákladní automobil) | car |
| ownership | Druh vozidla (soukromé/firemní) | private |
| usage | Používání vozidla (vozidlo na uživatele/poolové) | individual |
| engineVolume | Objem motoru | 1.00 |
| fuelConsumption | Spotřeba (kombinovaná) | 22.00 |
| fuelType | Typ paliva | Electric |
| state | Stav vozidla ve Fidoo
| active |
Členění DPH
/v2/settings/get-vat-breakdowns – výpis seznamu členění DPH
/v2/settings/add-vat-breakdown – vytvoření členění DPH
/v2/settings/delete-vat-breakdown – smazání členění DPH (přepnutí do stavu „deleted“)
/v2/settings/update-vat-breakdown – aktualizace dat členění DPH
Jednoznačným identifikátorem je hodnota v poli „code“.
| Hodnota | Popis | Vzor dat |
| id | Systémové ID položky | 9aea73a4-4403-40f4-9352-33bc2c68df9f |
| code | Kód členění DPH ve Fidoo | PDB2 |
| name | Název členění DPH ve Fidoo | DPH vstup 10% |
| state | Stav členění DPH ve Fidoo – active – aktivní a zobrazuje se uživatelům | active / inactive / deleted |
PSD2 API
K využívání PSD2 API musíte být držiteli certifikátu. O ten můžete požádat u I. Certifikační autority, pokud jste držitelem příslušné licence vydávané Českou národní bankou. Kompletní návod, jak začít využívat naše PSD2 API, najdete na https://psd2.fidoo.com a obsahuje:
- Informace o platebních účtech (AISP API) – zůstatek Fidoo účtu, historie a detaily dobití a odbití Fidoo účtu
Testovací data
Pokud máte zájem o testovací prostředí, pošlete žádost na info@fidoo.com. Ochotně vám zřídíme testovací prostředí Fidoo, které bude schopno komunikovat s testovacím API z úložiště: https://api-preprod.fidoo.com/v2.
