Fidoo API
Propojte si data z Fidoo a získejte tak komplexní přehled o firemních financích. Díky Fidoo API můžete mít data o výdajích, karetní transakcích, zůstatcích na účtu a uživatelích přímo ve vaším systému. Práce s účetnictvím se tak stává jednodušší, rychlejší a efektivnější.
Komplexní Fidoo API
- 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
PSD2 API
Testovací prostředí
Napište nám a zřídíme vám testovací prostředí Fidoo, které bude schopno komunikovat s testovacím API z úložiště.
Chci využít Fidoo API
Chcete se nás k API něco zeptat, nebo chcete využít našeho testovacího prostředí? Vyplňte formulář a my se vám ozveme.
FAQ
O jaký typ komunikace se jedná?
Jedná o synchronní obousměrnou REST komunikaci.
Jsou data během komunikace šifrována?
Veškerá komunikace je chráněna HTTPS šifrováním (TLS v1.3, šifrovací sada: TLS_AES_128_GCM_SHA256) a je uplatňován request throttling s maximálním počtem 6000, resp. 12000 dotazů pro jednoho zákazníka na den. O zabezpečení se taktéž stará vygenerovaný API klíč, který si generujete přímo v aplikaci. Je možné mít více API klíčů s výběrem, zda umožní data pouze číst nebo navíc zapisovat.
Jaká data jsou mezi napojenými systémy vyměňována?
Záleží, které endpointy budete využívat. Nabízíme informace o Fidoo účtu (sběrný účet pro nabíjení karet), karetních účtech a transakcích, výdajích, user managementu, nastavení aplikace a dalších součástí Fidoo aplikace. Podrobněji rozepsáno v dokumentaci Fidoo public API zde: https://api.fidoo.com/v2/.
Prochází Fidoo aplikace vč. public API penetračními testy?
Ano, Fidoo aplikace pravidelně prochází penetračním testováním.
Mohu přes public API změnit e-mail nebo telefonní číslo existujícího uživatele?
Bohužel, telefonní číslo uživatele přes API volání měnit nelze, ale ve Fidoo aplikaci ano. E-mail uživatele nelze měnit ani přes public API ani ve Fidoo aplikaci.
Mohu přes public API pomocí zaměstnaneckého (osobního) čísla (employeeNumber) měnit atributy konkrétního uživatele?
/v2/user/update-user vyžaduje parametr id, který je ve Fidoo aplikaci unikátní (UUID). Nicméně při dodržení pravidla jedinečnosti zaměstnaneckého (osobního) čísla v rámci jedné firmy, lze použít endpoint /v2/user/get-user-by-employee-number, který na základě zaměstnaneckého (osobního) čísla (parametr employeeNumber) umožňuje dohledat uživatelovo id pod parametrem userId. Následně již lze navázat voláním, které má uživatelovo id mezi povinnými parametry.
Provolal jsem dotaz s vygenerovaným API klíčem, ale vrací se mi chybový stav 401 Unauthorized se zprávou “Pernament public API key is invalid". Jak je to možné?
Pakliže jste si jisti, že vámi zadaný API klíč je správný a úplný (není to pouze zkrácená maskovaná verze), pak si překontrolujte, zda provoláváte prostředí shodné s prostředím, kde jste si vygenerovali API klíč. Pokud jste si vygenerovali klíč na produkčním prostředí aplikace https://www.fidoo.com/app/, pak volaná URL musí začínat https://api.fidoo.com/v2/. Pro testovací prostředí aplikace https://preprod.fidoo.com/app/ musí volaná URL začínat https://api-preprod.fidoo.com/v2/. Pro demo prostředí aplikace https://demo.fidoo.com/app/ musí volaná URL začínat https://api-demo.fidoo.com/v2/.
Zautomatizoval jsem firemní procesy, jenže po pár hodinách se mi začne objevovat chybový stav 429 Too many requests. Co to znamená?
Vámi nastavená API volání probíhají v příliš velké intenzitě a dosáhla svého limitu, který činí 6000 dotazů pro jednoho zákazníka na den. Zkuste si překontrolovat frekvenci vašich API volání, zda neprobíhají příliš často.
Mohu přes public API zjistit, zda nějaký výdaj má nebo nemá položky? Nebo musím pro všechny výdaje volat endpoint /v2/expense/get-expense-items?
Endpoint /v2/expense/get-expenses vrací parametr hasItems, který slouží jako indikátor, zda výdaj obsahuje položky. Pokud parametr nabývá hodnoty true, pak výdaj obsahuje položky. V opačném případě nabývá hodnoty false a položky neobsahuje.
Mohu přes public API vytvořit uživatele s telefonním číslem (parametr phone) bez uvedení předčíslí? Mohu použít stejné telefonní číslo u více uživatelů současně?
Bohužel ne, předčíslí je vyžadováno kvůli kontrole národního formátu, např. česká telefonní čísla musí začínat +420, jinak se uživatel nevytvoří. Telefonní čísla jedinečná být nemusí, nicméně pokud se uživatel bude chtít přihlásit do aplikace, tak bude potřebovat zadat ověřovací SMS kód, který v tomto případě nedorazí (Přístup a přihlášení do Fidoo | Fidoo). SMSka také slouží k potvrzování plateb kartou on-line.
Jak mám přes public API rozeznat transakce a výdaje uskutečněné pomocí karty Komerční banky?
Ve Fidoo aplikaci evidujeme pouze transakce uskutečněné našimi Fidoo kartami, z tohoto důvodu se nezobrazí ani v odpovědi na volání endpointu /v2/transaction/get-card-transactions. Na základě transakce uskutečněné kartou Komerční banky však vytvoříme výdaj, který obsahuje unikátní parametr pairingKey, např. “205-14032022 1086001141482”. Pakliže výdaj nebyl placený kartou Komerční banky, pak parametr pairingKey odpovídá hodnotě parametru shortId, např. “EX-38”. Uvedené parametry lze nalézt v endpointu /v2/expense/get-expenses, kde jednotlivé výdaje jsou rovněž charakterizovány parametrem type, který nabytím stavu “card-transaction” označuje karetní transakci.
Mohu mít aktivních více API klíčů současně?
Ano, na každého oprávněného uživatele v roli Hlavního správce lze vytvořit a používat více API klíčů současně. Při vytváření samotného API klíče lze také rozhodnout, zda daný klíč bude umožňovat pouze čtení, nebo čtení a zápis.
Fungují dále API klíče vystavené na uživatele, který svoji roli Hlavního správce pozbyl či byl z Fidoo aplikace smazán?
Ne, vytvořené API klíče jsou vázané na oprávněného uživatele. Pokud dojde u uživatele, na kterého jsou vytvořené API klíče, k odebrání role Hlavního správce či bude z aplikace např. z personálních důvodů odebrán, pak se trvale deaktivují (zneplatní) na něj vytvořené API klíče a nastavená spojení přestanou fungovat. Je třeba míti na paměti, že ještě před odchodem daného zaměstnance je nezbytné vyměnit jeho API klíče zanesené do automatizovaných procesů za API klíče nové, které budou náležet zaměstnanci s dále trvající rolí a přístupem do Fidoo aplikace.
Nezobrazuje se mi kompletní výpis dat z volaného API endpointu. Jak je to možné?
limit s nějakou nižší hodnotou (nejčastěji s výchozí hodnotou odpovídající právě 100). Zkuste parametr limit volat s navýšenou hodnotou, avšak maximálně do hodnoty 1000. Při volání vyšší hodnoty limit než je maximální, je použita výchozí hodnota.
Čím vyšší limit nastavíte, tím vzroste nejen množství vrácených dat, ale také se prodlouží doba na dokončení API volání, které bude trvat delší než standardní dobu.
V jakém formátu se používají časové hodnoty v našem public API?
Data a časy by měly být volány a budou vždy vráceny ve formátu ISO 8601.
Data o výdajích, karetních transakcích a uživatelích mohou být přesná až na milisekundy. V tomto případě se data vrátí ve formátu yyyy-mm-ddThh:mm:ss.sssZ, např. 2023-08-29T17:52:34.321Z. Ostatní data zatím vracíme s přesností na sekundy, nicméně to se může v budoucnosti změnit, proto doporučujeme zaimplementovat formát obsahující milisekundy.
S libovolnou přesností umožňujeme filtrování v API voláních podporovaných endpointů (např. karetní transakce). Nicméně je vždy nezbytné zadat časové pásmo, které lze zadat jak ve formátu +hh, tak ve formátu +hh:mm. Tuzemské časové pásmo se v letním čase značí +02 (např. 2023-07-19T14:50+02) a pro zimní čas se využívá +01 (např. 2024-01-19T13:50+01). Je také možné celoročně používat greenwichský čas (GTM) značený +00 nebo ekvivalentním písmenem Z (např. 2023-07-19T12:50Z). Pakliže chceme vyjádřit např. čas 14:50 dne 19. července 2023, pak lze zadat jednu z následujících možností: 2023-07-19T14:50+02, 2023-07-19T13:50+01, 2023-07-19T12:50+00 nebo 2023-07-19T12:50Z.
U některých API endpointů je v dokumentaci uveden parametr offsetToken a nextOffsetToken. Co znamenají a jak fungují?
limit.
Pakliže je daného limitu dosaženo a stále nejsou vypsány všechna volaná data, tak je na počátku odpovědi (response) vrácen stav false u parametru complete a současně je také vrácený parametr nextOffsetToken s klíčem pro navazující API volání, díky kterému lze pokračovat v bodu, kde se na základě limitu API volání zastavilo a přeskočit tak předcházející výsledky. V navazujících API voláních se poté vrácená hodnota parametru nextOffsetToken vkládá mezi další volané parametry do těla (body) volání jako hodnota parametru offsetToken. Parametry nextOffsetToken jsou vráceny vždy dokud nenabude vrácený parametr complete stavu true.
Např. volám API endpoint s limitem 100, avšak výsledků je 250. Po prvním volání je mi vráceno prvních 100 řádků dat a parametr nextOffsetToken s hodnotou “T2”, který vložím do druhého volání jako hodnotu parametru offsetToken. Po druhém volání je mi vráceno následujících 100 řádků dat a opět parametr nextOffsetToken ale s hodnotou “T3”, kterou vložím do třetího volání jako hodnotu parametru offsetToken. Po třetím volání je mi vráceno zbývajících 50 řádků dat, již není vrácen žádný parametr nextOffsetToken a parametr complete nabyl stavu true.