API a webhooky

Součást tarifů Profi a Provozovna · Ceník · Kontakt

Všechno, co umí administrace, umí i API — je to totiž stejné rozhraní. Klíč se generuje v Nastavení a posílá se jako Bearer token. Webhook naopak volá vás: každá nová, přesunutá nebo zrušená rezervace přiletí POSTem na vaši adresu, podepsaná.

API klíč

Vygenerujete ho v administraci v Nastavení → Účet → API přístup. Ukáže se jednou; uložte si ho. Kdykoli ho můžete zneplatnit a vydat nový — starý tím okamžitě přestane fungovat.

Authorization: Bearer <váš klíč>
Content-Type: application/json

Klíč zastupuje váš účet: vidí a mění přesně to, co byste viděli a měnili přihlášením. Limit je 120 požadavků za minutu na klíč; nad ním přijde 429 a hlášku „příliš mnoho požadavků“. Neplatný klíč vrací 401.

Endpointy

Základ je https://schuzky.online. Vše přijímá i vrací JSON.

S klíčem (váš účet)

Metoda	Cesta	Co dělá
GET	/api/me	účet, události, tým, provozovny, stav propojení
POST	/api/me/events	nová událost včetně oken dostupnosti
PUT	/api/me/events/{id}	úplné nahrazení události
GET	/api/me/bookings	rezervace organizátora
POST	/api/me/bookings	rezervace zapsaná za klienta; potvrzení mu přijde stejně
POST	/api/me/bookings/{id}/reschedule	přesun termínu
POST	/api/me/bookings/{id}/cancel	zrušení
POST	/api/me/staff	člen týmu s vlastní dostupností
POST	/api/me/venues	provozovna včetně otevírací doby
POST	/api/me/webhook	nastavení adresy webhooku

Bez klíče (veřejné, čtou i vaši klienti)

Metoda	Cesta	Co dělá
GET	/api/u/{jmeno}	profil a aktivní události
GET	/api/u/{jmeno}/{sluzba}	detail události
GET	/api/u/{jmeno}/{sluzba}/slots?from&to	volné termíny v UTC, rozsah nejvýš 62 dnů
POST	/api/u/{jmeno}/{sluzba}/book	rezervace; 409 = termín mezitím padl
GET	/api/p/{provozovna}	provozovna, tým a jeho služby

Webhook

Adresu nastavíte v Nastavení → Účet → Webhook. Zároveň dostanete tajný klíč, kterým se podepisuje každé volání. Prázdná adresa webhook vypne.

Co přijde

POST s hlavičkou Content-Type: application/json a tělem:

{
  "event": "booking.created",
  "booking": {
    "id": 412,
    "event_owner": "salon-u-lipy",
    "event_slug": "strih",
    "event_name": "Střih a foukaná",
    "duration_min": 45,
    "start": "2026-08-03T07:00:00Z",
    "end": "2026-08-03T07:45:00Z",
    "guest_name": "Jana Dvořáková",
    "guest_email": "jana@example.cz",
    "note": "Prosím kratší než minule.",
    "answers": [],
    "location_kind": "place",
    "location_value": "Dlouhá 12, Praha",
    "cancel_min_minutes": 120,
    "status": "confirmed",
    "manage_token": "…",
    "lang": "cs",
    "staff_id": 3,
    "staff": "Adam",
    "payment_state": "paid",
    "deposit_czk": 300
  }
}

Hodnota event je booking.created, booking.moved nebo booking.cancelled. Časy jsou vždy v UTC s koncovým Z — přepočet do místního času si udělejte podle časového pásma události.

Pozor na manage_token: je to tajemství, které drží v ruce klient — kdo ho má, může rezervaci přesunout i zrušit. Nikam ho dál neposílejte a nelogujte.

Ověření podpisu

V hlavičce X-Schuzky-Signature přijde sha256=<hex>: HMAC-SHA256 syrového těla požadavku vaším tajným klíčem. Počítejte ho z bajtů, které přišly, ne z JSONu, který si znovu poskládáte — přeuspořádané klíče nebo jiné mezery dají jiný podpis.

// Node.js / Express
const crypto = require("crypto");

app.post("/schuzky", express.raw({ type: "application/json" }), (req, res) => {
  const mine = crypto.createHmac("sha256", process.env.SCHUZKY_SECRET)
                     .update(req.body)
                     .digest("hex");
  const sent = (req.get("X-Schuzky-Signature") || "").replace(/^sha256=/, "");
  if (!crypto.timingSafeEqual(Buffer.from(mine), Buffer.from(sent))) {
    return res.sendStatus(401);
  }
  const { event, booking } = JSON.parse(req.body);
  // …
  res.sendStatus(200);
});

Co čekat od doručování

Bez opakování. Zkoušíme jednou. Doručovací jistotu nese e-mail, ne webhook — kdyby vám volání uteklo, rezervace tím nezmizí.
Timeout 10 sekund. Odpovězte rychle a práci si odložte na frontu; dlouhý handler skončí utnutým spojením.
Jen veřejná adresa. Cíl musí být dostupný z internetu a mířit mimo privátní rozsahy. Kontrolujeme to při uložení i při odeslání, protože DNS mezitím mohlo ukázat jinam.
Návratový kód neřešíme, ale chybu spojení si zalogujeme.

Kalendářový feed

Kdo nepotřebuje API, ale chce jen vidět rezervace jinde, má v Nastavení tajnou .ics adresu. Přidá se v Google Kalendáři nebo Outlooku přes „Přidat kalendář z adresy URL“ a je read-only.

Něco chybí?

API roste podle toho, co lidé opravdu potřebují. Napište na ahoj@schuzky.online, co byste chtěli volat — odpovídá člověk, který to psal.