Přes REST API můžete data z Aptienu automaticky načítat do vlastních systémů – do reportingu, na intranet nebo do jiné aplikace – a z nich v Aptienu zakládat nové záznamy. Aptien zůstává místem, kde data vznikají a udržují se. API je způsob, jak s nimi pracovat i jinde, bez ručních exportů.
Typické využití
- Propojení systémů – stejnou informaci nemusíte udržovat na dvou místech.
- Vyhledávání napříč evidencemi – jeden dotaz projde všechny evidence najednou.
- Sledování dostupnosti – monitorovací nástroj si sám ověřuje, že je vaše instance v provozu.
Co dnes API umí
API ve verzi 1 data z Aptienu hlavně čte. Zapisovat umí jediným způsobem: zakládat nové záznamy. Existující záznamy přes API zatím neupravíte ani nesmažete.
Čtení
- Role klíče – jaká role je ke klíči přiřazená a k čemu má přístup.
- Evidence – seznam evidencí, které role smí číst (např. Zaměstnanci, Majetek, Smlouvy), a detail jedné evidence včetně toho, zda v ní role smí zakládat.
- Struktura evidence – sloupce evidence v pořadí, v jakém je zobrazuje Aptien, s formátem hodnot a informací, které sloupce jsou povinné a které lze zapisovat.
- Záznamy evidence – výpis záznamů po stránkách s filtrem podle stavu, kategorie, textu nebo hodnot sloupců.
- Detail záznamu – název, popis, stav, kategorie, přiřazený uživatel, obrázek, hodnoty všech sloupců a odkaz do Aptienu.
- Kategorie – kategorie definované ve vaší instanci.
- Fulltextové vyhledávání – hledání v názvech, popisech a hodnotách sloupců ve všech evidencích najednou.
- Nastavení zobrazení – formáty data a času, které používá vaše instance.
- Kontrola dostupnosti – ověření, že je vaše instance v provozu. Nepotřebuje přístupový klíč.
Zakládání záznamů
- Nový záznam založíte v evidenci, ve které má role klíče právo zakládat.
- Vyplnit lze jen sloupce s jednou jednoduchou hodnotou – text, číslo nebo datum. Vazby, tabulky, výčty, štítky, zaškrtávací pole a vypočítané sloupce přes API nevyplníte.
- Povinné sloupce musíte poslat všechny. Pokud má evidence kategorie, je nutné kategorii vybrat.
- Při založení zaměstnance musí být e-mail platný a v instanci jedinečný. Nový zaměstnanec automaticky dostane uživatelský účet bez licence a bez pozvánky.
Bezpečnost a oprávnění
API nikdy nesmí víc než uživatel se stejnou rolí. Přístup se otevírá přístupovým klíčem vydaným pro vaši instanci. Každý klíč má přiřazenou roli a ta určuje, co přes něj integrace smí. Klíč nevystupuje pod uživatelem, který ho vydal (ten je u klíče jen uvedený), ale jako samostatný uživatel pod svým názvem. Změny provedené přes API se proto v historii záznamu zobrazují pod názvem klíče a snadno je odlišíte od práce uživatelů. Klíč pojmenujte podle integrace, například „Reporting“ pro čtení dat nebo „Import z HR systému“ pro zakládání záznamů.
- Platí stejná oprávnění, jaká máte nastavená v Aptienu, pro čtení i zakládání. API je nijak neobchází.
- Dotaz na evidenci nebo záznam mimo oprávnění role skončí chybou.
- Pro integraci přiřaďte klíči samostatnou roli s právy jen na to, co integrace skutečně potřebuje.
Klíč chraňte jako heslo. Kdo ho má, čte data v rozsahu jeho role a může zakládat záznamy tam, kde to role dovoluje. Ukládejte ho jen na serveru navazujícího systému, nikdy v kódu běžícím v prohlížeči, v repozitáři ani v e-mailu.
Jak začít krok za krokem
- Získejte přístupový klíč. Klíč založí administrátor v Administrace → API klíče. Vydává se pro vaši instanci a přiřazuje se mu role, podle které se řídí, co API smí.
- Otevřete technickou dokumentaci. Interaktivní dokumentace je na adrese https://mojefirma.aptien.com/api-docs/ – místo „mojefirma“ doplňte název své instance. Popis API je ve standardu OpenAPI 3.0.0, takže z něj váš IT tým vygeneruje klienta pro běžné programovací jazyky.
- Ověřte klíč. Klíč se posílá v hlavičce
x-api-keykaždého požadavku a všechna volání začínají cestou/api/v1, například:curl -H "x-api-key: VÁŠ_KLÍČ" https://mojefirma.aptien.com/api/v1/user/info
Odpověď ukáže roli klíče. Podle ní se řídí, co integrace uvidí. - Vyberte evidence a napojte je. Načtěte seznam dostupných evidencí a jejich záznamy. Pokud chcete záznamy zakládat, podívejte se nejdřív na strukturu evidence – uvidíte v ní, které sloupce jsou povinné a které lze zapsat.
- Přidejte monitoring. Kontrolu dostupnosti zapojte do své monitorovací služby. Klíč pro ni potřeba není.
Na co myslet při napojení
- Stránkování – výpis záznamů vrací data po stránkách. Další stránky načtete posunem (offset) podle celkového počtu záznamů (total_count). U vyhledávání může stránka vrátit méně výsledků, než je limit. Další stránku načítejte podle příznaku has_more, ne podle počtu vrácených řádků.
- Limit počtu dotazů – API má limit na počet požadavků, u fulltextového vyhledávání přísnější. Zakládání záznamů má vlastní, přísnější limit, počítaný zvlášť od čtení. Počítá se s cílenými dotazy, ne s dávkovým vytěžováním.
- Bezpečné opakování při zakládání – k požadavku na založení posílejte hlavičku
Idempotency-Keys jedinečnou hodnotou. Když odpověď nedorazí, zopakujte stejný požadavek se stejným klíčem a záznam nevznikne dvakrát. Výsledek se po určitou dobu pamatuje. Pokud chcete po chybě poslat opravená data, použijte nový klíč. - Chybové odpovědi – chyby mají jednotný tvar (stav, kód a popis), takže je lze vyhodnocovat strojově.
- Formát – popis API je ve standardu OpenAPI 3.0.0.
- Formáty data a času – načtěte nastavení zobrazení instance, ať váš systém používá stejnou konvenci jako Aptien.
Co chystáme
API budeme postupně rozšiřovat o další oblasti Aptienu, například práci s dokumenty a úpravy existujících záznamů. Jde o výhled, ne o závazek termínu ani rozsahu.
I nové operace se budou řídit oprávněními role přiřazené ke klíči.
Časté dotazy
Používáme starší webové služby (SOAP/WSDL). Co s nimi?
Podpora webových služeb v roce 2026 skončila a přístup k nim se postupně vypíná. Přejděte na REST API. Čtení a zakládání záznamů už umí, úpravy existujících záznamů jsou v plánu.
Dostane se integrace k datům, která běžný uživatel nevidí?
Ne. Klíč vidí jen to, na co má právo role, která je k němu přiřazená.
Proč stránka vyhledávání vrátila méně výsledků, než je limit?
Je to běžné. Pokračujte podle příznaku has_more.
Proč API odmítlo založit záznam?
Nejčastěji chybí povinný sloupec nebo kategorie, sloupec nejde přes API zapsat, nebo role nemá v evidenci právo zakládat. Důvod najdete v popisu chyby a ve struktuře evidence.
Potřebuje kontrola dostupnosti klíč?
Ne. Je to jediná oblast bez klíče a její odpověď neobsahuje žádné vnitřní podrobnosti.