Zaptime pro vývojáře

Zaptime je český online rezervační kalendář. Tento vývojářský portál shrnuje vše, co potřebujete pro napojení: veřejné rezervační API, vložitelný kalendář, webhooky, MCP server pro AI asistenty a strojově čitelné soubory pro agenty. Podrobné návody jsou na docs.zaptime.app (anglicky).

Rychlý start: Zaptime API ve třech krocích

Zaregistrujte se na my.zaptime.app/register (plán Personal je zdarma) a vytvořte typ události.
Na my.zaptime.app/calendars u typu události zkopírujte API token. Token je zároveň API klíč, každý typ události má vlastní.
Načtěte volné termíny a vytvořte rezervaci:

# Volné termíny
curl "https://api.zaptime.app/time-slots?from=2026-09-01&until=2026-09-07" \
  -H "Authorization: Bearer $ZAPTIME_TOKEN" -H "Accept: application/json"

# Rezervace jednoho z nich
curl -X POST https://api.zaptime.app/reservations \
  -H "Authorization: Bearer $ZAPTIME_TOKEN" -H "Content-Type: application/json" \
  -d '{"start":"2026-09-01T09:00:00Z","end":"2026-09-01T09:30:00Z","email":"[email protected]","firstname":"Jana","lastname":"Nováková","timezone":"Europe/Prague"}'

Kompletní popis požadavků a odpovědí je v OpenAPI 3.1 specifikaci (11 operací: termíny, rezervace, předrezervace a potvrzení, platby, konfigurace typu události, časové zóny).

Sandbox a testování

Samostatný testovací server neexistuje. Vytvořte si v účtu zvláštní testovací typ události (např. „API test“) a používejte jeho token; rezervace jdou jen do tohoto kalendáře a lze je přes API zrušit. Vypnutý typ události vrací 403 event_type_disabled, což je rychlý způsob, jak testovací integraci zastavit.

Autentizace

Token typu události posílejte jako bearer token: Authorization: Bearer <token>. Token platí pro jeden typ události a lze ho v aplikaci kdykoli vygenerovat znovu. GET /timezones token nepotřebuje. Chybějící nebo neplatný token vrací 401 unauthenticated.

Chyby

Každá chyba je JSON, nikdy HTML stránka, a to i bez hlavičky Accept. Tělo odpovídá schématu Error z OpenAPI specifikace:

{
  "success": false,
  "status": 404,
  "code": "not_found",
  "message": "Not found.",
  "hint": "Check the path and resource identifier. Endpoints are listed in the OpenAPI spec.",
  "docs": "https://zaptime.cz/developers/#errors"
}

HTTP	`code`	Kdy
400	`bad_request`, `unsupported_api_version`	Chybný požadavek nebo neznámá `Zaptime-Api-Version`
401	`unauthenticated`	Chybí nebo je neplatný bearer token
403	`forbidden`, `event_type_disabled`	Token je platný, ale typ události je vypnutý
404	`not_found`	Neznámá cesta nebo UUID rezervace
405	`method_not_allowed`	Špatná HTTP metoda
422	`validation_failed`	Neplatný vstup; `errors` obsahuje zprávy pro jednotlivá pole
429	`rate_limited`	Překročen limit; počkejte `Retry-After` sekund
200 se `success: false`	`slot_locked`, `reservation_finished`	Termín právě rezervuje někdo jiný, nebo rezervaci už nelze obnovit
400	`stripe_not_configured`	Platba u typu události bez napojeného Stripe
422	`payment_required`	Potvrzení před úspěšnou platbou
500	`internal_error`	Neočekávaná chyba; zkuste znovu, pak napište podpoře

Větvěte podle code, ne podle message: kódy jsou stabilní, texty se mohou změnit.

Limity požadavků

60 požadavků za minutu na token (bez tokenu na IP adresu). Každá odpověď nese hlavičky IETF RateLimit a starší dvojici X-RateLimit-*:

RateLimit-Policy: 60;w=60
RateLimit: limit=60, remaining=59, reset=60
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59

Odpověď 429 přidává Retry-After (v sekundách). Tolik počkejte a zkuste to znovu.

Verzování a ukončování funkcí

API má verzi 1. Cesty verzované nejsou; každá odpověď nese Zaptime-Api-Version: 1 a stejnou hlavičkou můžete verzi v požadavku připnout (neznámá hodnota vrací 400 unsupported_api_version). V rámci verze jsou změny pouze aditivní: nové endpointy, volitelné parametry a pole v odpovědích. Nekompatibilní změny vycházejí jako nová verze. Cokoli se ruší, oznámíme na této stránce a v novinkách nejméně 6 měsíců předem a dotčené odpovědi po tu dobu nesou hlavičky Deprecation a Sunset (RFC 9745 a RFC 8594).

Vložitelný kalendář a SDK

Skript nebo iframe: Getting started
Vue 3: balíček @zaptime/vue3 na npm, návod na instalaci a headless composables
Logika bez frameworku: @zaptime/core na npm
Reference konfigurace: ZaptimeConfig, locale, theme

Webhooky

Zaptime zavolá vaši URL při vytvoření, přesunutí nebo zrušení rezervace. URL se nastavuje u typu události v aplikaci; formát dat a opakování jsou v návodu k webhookům.

MCP server pro AI asistenty

Zaptime má MCP (Model Context Protocol) server, díky kterému ChatGPT, Claude a další asistenti umí vypsat typy událostí, najít rezervační odkaz, hledat, přesouvat a rušit rezervace a spravovat dostupnost. Nastavení a seznam nástrojů najdete na stránce Zaptime MCP.

Příkazová řádka

Oficiální Zaptime CLI zatím neexistuje. API je obyčejné HTTPS a JSON, takže pro skriptování stačí curl a OpenAPI specifikace (nebo klient vygenerovaný z ní pomocí openapi-generator). Chybí vám? Napište na [email protected].

Strojově čitelné zdroje

OpenAPI specifikace
llms.txt a llms-full.txt
Každá stránka existuje i jako markdown: přidejte .md k cestě nebo pošlete Accept: text/markdown
Sitemap
Stav API

Podpora

Pište na [email protected]. Uveďte cestu požadavku, code z těla chyby a pokud ho máte, hlavičku odpovědi apigw-requestid.