Jedná o synchronní obousměrnou REST komunikaci.

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 dotazů (requestů) 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.

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ích Fidoo aplikace. Podrobněji rozepsáno v dokumentaci Fidoo public API zde: https://api.fidoo.com/v2/.

Ano, Fidoo aplikace pravidelně prochází penetračním testováním.

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.

Napřímo to nelze, neboť endpoint /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.

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 demo prostředí apli kace https://demo.fidoo.com/app/ musí volaná URL začínat ht tps://api-demo.fidoo.com/v2/ .

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.

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.

Bohužel, 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í. SMSka také slouží k potvrzování plateb kartou on-line.

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.

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.

Ne, vytvořené API klíče jsou vázáné 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.

Nejspíše jste ve volaném body (těle) API volání ponechali parametr 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.

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.

Aby se v jeden současný moment na jeden volaný API endpoint nevracel příliš objemný soubor dat, který by mohl zatížit nejen servery, ale také zpozdit jejich odpověď na API volání, tak lze většinu API endpointů omezit volaným parametrem 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.