API Dokumentace a vývojářský portál
Vítejte v technickém srdci platformy UnhostCampus, kde poskytujeme veškeré nástroje a informace potřebné pro úspěšnou integraci našich služeb do vašeho školního ekosystému. Naše API je postaveno na principech REST architektury, což zajišťuje předvídatelnost, snadnou testovatelnost a širokou kompatibilitu s moderními programovacími jazyky. Tato dokumentace je určena vývojářům, kteří chtějí využít plný potenciál naší databázové infrastruktury pro tvorbu vlastních aplikací a rozšíření.
Rozcestník sekcí
REST API nad školní databází
Komunikační vrstva UnhostCampus je navržena jako bezstavové RESTful API. Každý endpoint představuje konkrétní zdroj — studenta, kartu, transakci nebo inventářní položku — a přijímá standardní HTTP metody. Datová struktura vždy vrací JSON, což usnadňuje integraci v jazycích jako PHP, Python, JavaScript i C#. Vývojář tak pracuje s předvídatelnými adresami a konzistentním schématem odpovědí napříč celou platformou.
HTTPS / TLS 1.2+
Veškerá komunikace je šifrovaná.
application/json
Požadavek i odpověď v JSON.
Bearer Token
API klíč v hlavičce Authorization.
Základy komunikace a autentizace
Přístup k API UnhostCampus je zabezpečen pomocí tokenů, které garantují, že s daty pracují pouze autorizované subjekty s příslušnými oprávněními. Veškeré požadavky musí být realizovány přes protokol HTTPS, přičemž data jsou přenášena ve standardizovaném formátu JSON pro snadnou čitelnost a zpracování.
V této sekci naleznete návod, jak vygenerovat svůj první API klíč a jak správně nastavit hlavičky požadavků pro úspěšné navázání spojení. Tokeny mají omezenou platnost a lze je kdykoli zneplatnit, což umožňuje rychlou reakci na bezpečnostní incidenty.
curl -X GET https://api.unhostcampus.com/v1/students -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -H "Accept: application/json"
api.unhostcampus.com/v1
Obnovitelný přes refresh endpoint
Správa entit studentů a zaměstnanců
Základním stavebním kamenem našeho API jsou endpointy pro manipulaci s uživatelskými profily, které umožňují synchronizaci dat s vaším primárním informačním systémem. Můžete vytvářet, aktualizovat a dotazovat záznamy o osobách, přiřazovat jim identifikační média a spravovat jejich organizační zařazení v rámci školy.
Dokumentace obsahuje detailní popis všech polí a datových typů, se kterými platforma pracuje, včetně limitů pro hromadné operace. Typický objekt osoby zahrnuje jméno, rodné číslo, třídu, roli a seznam aktivních karet. Hromadné operace jsou omezeny na 500 záznamů na jeden požadavek.
Integrace kreditních operací
Pro implementaci platebních funkcí nabízíme sadu endpointů, které umožňují realizovat transakce, kontrolovat zůstatky a získávat historii pohybů na virtuálních účtech. API podporuje atomické operace, což je kritické pro zajištění integrity finančních dat a prevenci chyb při souběžných požadavcích. Vývojáři zde najdou ukázky kódu pro různé scénáře, od jednoduchého nákupu u pokladny až po komplexní systém pravidelných plateb za služby.
{
"student_id": "STU-2026-0148",
"amount": -45.50,
"description": "Oběd — jídelna",
"terminal_id": "TERM-003",
"idempotency_key": "tx_17356a2b"
{
"transaction_id": "TX-88472",
"status": "completed",
"balance_after": 312.00,
"timestamp": "2026-08-25T11:42:01Z"
Pole idempotency_key zaručuje, že opakované odeslání stejného požadavku neúčtuje transakci podruhé. Tento mechanismus je nezbytný pro scénáře, kdy síťové přerušení zpětně neovlivní stav účtu.
Práce s identifikačními médii
Tato část dokumentace se zaměřuje na nízkoúrovňovou komunikaci s čipovými kartami a jejich vazbu na digitální identity v systému. Popisujeme mechanismy registrace nových UID, mapování karet na konkrétní uživatele a procesy okamžité deautorizace v případě ztráty média. Naleznete zde také doporučené postupy pro integraci s hardwarem čteček a terminálů od různých výrobců, se kterými je naše platforma kompatibilní.
Mapování karet na uživatele
Nový fyzický prostředek se registruje odesláním UID čipu přes dedikovaný endpoint. Po úspěšném mapování je karta okamžitě funkční pro průchod i platby v rámci definovaných oprávnění dané osoby.
Okamžité zablokování
Při ztrátě nebo krádeži karty lze médium deaktivovat jediným voláním. Blokace se propaguje na všechny čtečky a terminály v rámci sekund, takže zneužití je minimalizováno na nejkratší možnou dobu.
Podporované čtečky
Platforma komunikuje s čtečkami podporujícími standardy MIFARE a EMV. Dodavatel hardwaru si volíte sami — API přijímá data v nezávislém formátu, takže nezáleží na konkrétním výrobci terminálu.
Webhooky a real-time události
Aby vaše aplikace mohly okamžitě reagovat na změny v systému, nabízíme mechanismus webhooků, které zasílají notifikace o důležitých událostech v reálném čase. Může se jednat o informaci o provedeném průchodu dveřmi, nízký stav kreditu nebo úspěšnou inventarizaci majetku v konkrétní lokalitě.
V dokumentaci uvádíme seznam všech podporovaných typů událostí a strukturu dat, která je v rámci notifikace odesílána na váš server. Každý webhook obsahuje jedinečné ID události, časovou značku v ISO 8601 a datový payload specifický pro daný typ notifikace.
Při neúspěšném doručení se aplikuje exponenciální backoff strategie s maximálně 24hodinovým oknem pro opakované pokusy. Váš endpoint musí odpovědět HTTP stavem 200, jinak systém pokus opakuje.
credit.low_balance
Zůstatek klesl pod nastavenou hranici.
door.access_granted
Úspěšný průchod dveřmi.
card.deauthorized
Karta byla zablokována.
asset.inventory_completed
Dokončena inventarizace.
credit.transaction_created
Nová transakce na účtu.
Chybové stavy a ladění aplikací
Kvalitní vývoj se neobejde bez jasných informací o tom, proč požadavek selhal, a proto naše API vrací standardizované HTTP chybové kódy doplněné o detailní textový popis problému. Tato sekce obsahuje kompletní katalog chybových zpráv a doporučení, jak se s nimi v kódu vypořádat, například implementací mechanismu retry pro dočasné výpadky konektivity.
Poskytujeme také přístup k sandboxovému prostředí, kde můžete bezpečně testovat své integrace bez ovlivnění produkčních dat. Sandbox využívá identické API endpointy s vlastní URL a zcela nezávislými datovými sadami.
Bad Request
Požadavek obsahuje neplatná nebo chybějící pole. Zkontrolujte payload proti schématu v referenční dokumentaci.
Unauthorized
Token chybí, vypršela jeho platnost nebo nebyl rozpoznán. Obnovte token přes refresh endpoint.
Forbidden
Token je platný, ale postrádá oprávnění pro daný zdroj. Kontaktujte administrátora o rozšíření scopu.
Conflict
Kolize — například pokus o duplicitní registraci UID nebo konflikt idempotency klíče. Vraťte odpověď z předchozího úspěšného volání.
Too Many Requests
Byl překročen rate limit. Hlavičky odpovědi obsahují čas do obnovení kvóty. Implementujte exponenciální backoff.
Internal Server Error
Neočekávaná chyba na straně serveru. Opakujte požadavek po krátké pauze. Pokud chyba přetrvává, kontaktujte podporu.
Limity požadavků a optimalizace výkonu
Pro zajištění stability platformy pro všechny uživatele uplatňujeme limity na počet volání API za určité časové období (rate limiting). Dokumentace vysvětluje, jak tyto limity sledovat v hlavičkách odpovědí a jak optimalizovat vaše dotazy pomocí stránkování a filtrování dat, aby nedocházelo k jejich překračování.
Uvádíme zde také tipy pro efektivní využívání cache paměti na straně klienta, což urychlí odezvu vaší aplikace a sníží zátěž serverů. Stránkování je výchozí pro všechny seznamové endpointy s parametry pro offset a limit.
600
požadavků / okno
412
zbývající počet
epoch
obnovení kvóty
Okno pro měření limitu je 60 sekund. Při dosažení limitu API vrací stav 429 Too Many Requests spolu s hlavičkou Retry-After, která udává počet sekund do obnovení. Pro endpoints s hromadnými operacemi platí nižší limit — viz jednotlivé reference.
JSON API Reference
Kompletní referenční dokumentace obsahuje seznam všech endpointů, parametrů, datových typů a příkladů request i response payloadů. Reference je generována ze zdrojových kódů platformy a je průběžně aktualizována s každým vydáním.
Testujte bez rizika
Sandbox je dostupný pro všechny registrované vývojáře. Nabízí stejnou funkcionalitu jako produkční API s vlastní URL a nezávislými datovými sadami, takže můžete testovat integraci bez jakéhokoli vlivu na reálná data studentů a zaměstnanců.
Vyžádat přístup →Nevíte si rady?
Pokud narazíte na nejasnosti v dokumentaci nebo potřebujete poradit s integrací, naše vývojářská podpora je dostupná v pracovní době. Pište na e-mail uvedený níže a odpovíme během jednoho pracovního dne.
support@unhostcampus.com / martin.macek.zak@zsunhost.cz