--- title: "Zaptime pro vývojáře: API, SDK, webhooky a MCP" description: "Vývojářský portál Zaptime: rezervační API s OpenAPI specifikací, API tokeny, chybové kódy, limity, verzování, Vue SDK, webhooky a MCP server pro AI asistenty." canonical: https://zaptime.cz/developers/ --- # 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](https://docs.zaptime.app/) (anglicky). ## [Rychlý start: Zaptime API ve třech krocích](#rychlý-start-zaptime-api-ve-třech-krocích) 1. Zaregistrujte se na [my.zaptime.app/register](https://my.zaptime.app/register) (plán Personal je zdarma) a vytvořte typ události. 2. Na [my.zaptime.app](https://my.zaptime.app/) u typu události zkopírujte **API token**. Token je zároveň API klíč, každý typ události má vlastní. 3. 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":"jana@example.com","firstname":"Jana","lastname":"Nováková","timezone":"Europe/Prague"}'` Kompletní popis požadavků a odpovědí je v [OpenAPI 3.1 specifikaci](https://zaptime.cz/openapi.json) (11 operací: termíny, rezervace, předrezervace a potvrzení, platby, konfigurace typu události, časové zóny). ## [Sandbox a testování](#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](#autentizace) Token typu události posílejte jako bearer token: `Authorization: Bearer `. 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](#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 to znovu, případně napište na podporu Větvěte podle `code`, ne podle `message`: kódy jsou stabilní, texty se mohou změnit. ## [Limity požadavků](#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í](#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](https://zaptime.cz/novinky/) 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](#vložitelný-kalendář-a-sdk) - Skript nebo iframe: [Getting started](https://docs.zaptime.app/guide/getting-started.html) - Vue 3: balíček [`@zaptime/vue3`](https://www.npmjs.com/package/@zaptime/vue3) na npm, [návod na instalaci](https://docs.zaptime.app/guide/vue-installation.html) a headless composables - Logika bez frameworku: [`@zaptime/core`](https://www.npmjs.com/package/@zaptime/core) na npm - Reference konfigurace: [ZaptimeConfig](https://docs.zaptime.app/reference/zaptime-config.html), [locale](https://docs.zaptime.app/reference/zaptime-locale.html), [theme](https://docs.zaptime.app/reference/zaptime-theme.html) ## [Webhooky](#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](https://docs.zaptime.app/guide/webhooks.html). ## [MCP server pro AI asistenty](#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](https://zaptime.cz/funkce/mcp/). ## [Příkazová řádka](#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 [support@zaptime.app](mailto:support@zaptime.app). ## [Strojově čitelné zdroje](#strojově-čitelné-zdroje) - [OpenAPI specifikace](https://zaptime.cz/openapi.json) - [llms.txt](https://zaptime.cz/llms.txt) a [llms-full.txt](https://zaptime.cz/llms-full.txt) - Každá stránka existuje i jako markdown: přidejte `.md` k cestě nebo pošlete `Accept: text/markdown` - [Sitemap](https://zaptime.cz/sitemap.xml) - [Stav API](https://status.zaptime.app/) ## [Podpora](#podpora) Pište na [support@zaptime.app](mailto:support@zaptime.app). Uveďte cestu požadavku, `code` z těla chyby a pokud ji máte, hlavičku odpovědi `apigw-requestid`.