API webu obce

Rozhraní pro programy, které na web obce samy zapisují: sazba obecního zpravodaje, kalendář akcí, systémy úřadu. Všechno, co přes API vznikne, jde stejnou cestou jako z administrace — s revizemi, auditem, kontrolou HTML a zákonných náležitostí (popisy obrázků, lhůty úřední desky). Strojový popis: /api/openapi.json (OpenAPI 3.1).

Autentizace a oprávnění

Token založí administrátor webu ve Administrace → API a integrace; ukáže se jen jednou. Posílá se v hlavičce Authorization: Bearer wov_…. Každý token má jen vybraná oprávnění:

obsah:cteni — čtení příspěvků a kategorií webu
obsah:zapis — zakládání a úprava příspěvků (aktuality, akce, stránky) a nahrávání souborů
deska:zapis — vyvěšování dokumentů na úřední desku
infokanal:rozeslat — rozeslání příspěvku odběratelům infokanálu (e-mail, případně SMS)
zpravodaj — zveřejňování čísel obecního zpravodaje

Adresa API: https://vlastiborice.cz/api/v1. Data v JSON (UTF-8), soubory jako multipart/form-data (textová pole se jmenují stejně jako v JSON). Časy: YYYY-MM-DD, YYYY-MM-DDTHH:MM (pražský čas) nebo ISO 8601 se zónou.

curl -sS https://vlastiborice.cz/api/v1/kategorie -H "Authorization: Bearer $TOKEN"

Chyby a limity

Chyba vrací JSON {"chyba": "popis česky", "pole": "nazev_pole"} (pole jen když se chyba týká konkrétního údaje). Stavy: 400 neplatná data, 401 chybí/neplatný token, 403 token nemá oprávnění, 404 nenalezeno, 409 konflikt (např. potvrzení u desky), 413 moc velký soubor (max. 30 MB na soubor), 429 limit — 600 požadavků na token za 15 minut.

Příspěvky

POST /api/v1/prispevky (oprávnění obsah:zapis) založí aktualitu, akci nebo stránku. Bez "zverejnit": true vznikne koncept, který redaktor zkontroluje a zveřejní v administraci.

Pole	Význam
`typ`	`aktualita` (výchozí), `akce`, `stranka`
`titulek`	povinný
`perex`	krátký úvod (do 600 znaků)
`html` / `markdown`	text; HTML se pročistí (povolené značky jako v editoru), Markdown se převede
`kategorie`	slug nebo id kategorie (`GET /api/v1/kategorie`)
`datum`	aktualita: datum zveřejnění zprávy (výchozí teď)
`akce_od`, `akce_do`, `akce_cely_den`, `misto`	akce: termín a místo (jen datum = celý den)
`v_aktualitach`	akce se ukáže i v Aktualitách jako pozvánka
`obrazek` (soubor) nebo `obrazek_id`, `obrazek_alt`	úvodní obrázek; popis je před zveřejněním povinný (přístupnost)
`prilohy` (soubory) nebo `prilohy_id`	dokumenty ke stažení — připojí se na konec textu
`zverejnit`	`true` = hned na web, `false` = koncept
`zdroj`, `externi_id`	viz idempotence

curl -sS https://vlastiborice.cz/api/v1/prispevky -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{
    "typ": "akce", "titulek": "Drakiáda", "akce_od": "2026-10-25T14:00", "misto": "hřiště",
    "markdown": "Přijďte pouštět draky.\n\n- občerstvení\n- soutěže", "v_aktualitach": true,
    "zdroj": "kalendar", "externi_id": "drakiada-2026", "zverejnit": false }'

curl -sS https://vlastiborice.cz/api/v1/prispevky -H "Authorization: Bearer $TOKEN" \
  -F typ=aktualita -F titulek='Uzavírka silnice' -F html='<p>Od pondělí…</p>' \
  -F obrazek=@mapa.jpg -F obrazek_alt='Mapa objízdné trasy' -F prilohy=@rozhodnuti.pdf -F zverejnit=true

Odpověď 201 s id, stav (koncept/zverejneno), url a sprava_url. PATCH /api/v1/prispevky/:id změní jen poslaná pole (jen u příspěvků založených přes API); u zveřejněného příspěvku s "zverejnit": false se změna uloží jako rozpracovaná a web zůstane beze změny. GET /api/v1/prispevky?zdroj=…&externi_id=… a GET /api/v1/prispevky/:id čtou (oprávnění obsah:cteni nebo obsah:zapis).

Idempotence

Pošlete-li zdroj (jméno vašeho systému, malá písmena, výchozí api) a externi_id (id záznamu u vás), opakované POST se stejnou dvojicí upraví existující příspěvek (odpověď 200, "aktualizovano": true, nová revize) místo založení duplicity. Zdroje import, rezervace, infokanal a zpravodaj jsou vyhrazené.

Soubory

POST /api/v1/soubory s polem soubor (PDF, Office, obrázky; do 30 MB) vrátí id a url. Text dokumentu (i OCR skenů) se vyčte na pozadí a soubor pak najde hledání na webu.

curl -sS https://vlastiborice.cz/api/v1/soubory -H "Authorization: Bearer $TOKEN" -F soubor=@vyhlaska.pdf

Úřední deska

POST /api/v1/deska (oprávnění deska:zapis, multipart): nazev, kategorie (slug/id kategorie desky), vyveseno_od (výchozí dnes, nikdy v minulosti), vyveseno_do nebo do_odvolani=true (bez data se použije výchozí doba kategorie), popis, cislo_jednaci, puvodce, u rozpočtových dokumentů typ_rozpoctu a rok, přílohy v prilohy. Minimální doba vyvěšení kategorie se hlídá stejně jako v administraci. Když by dokument sejmul starší rozpočtové dokumenty, vrátí se 409 se seznamem sejme — pošlete znovu s potvrdit_nahrazeni=true.

curl -sS https://vlastiborice.cz/api/v1/deska -H "Authorization: Bearer $TOKEN" \
  -F nazev='Oznámení o konání zasedání' -F kategorie=oznameni -F vyveseno_do=2026-11-10 -F prilohy=@pozvanka.pdf

Rozeslání infokanálem

POST /api/v1/prispevky/:id/rozeslat (oprávnění infokanal:rozeslat) rozešle zveřejněnou aktualitu nebo akci odběratelům stejně jako tlačítko „Rozeslat infokanálem“ v administraci: e-mail s perexem a odkazem; SMS jen s {"sms": true} (stojí peníze). Volitelně kategorie (slug kategorie infokanálu). Odpověď 202 {"hlaseni_id", "prijemcu"}.

Zpravodaj

POST /api/v1/zpravodaj (oprávnění zpravodaj, multipart): metadata (JSON jako textové pole nebo soubor), pdf (webová verze), volitelně pdf_tisk a obalka (PNG/JPG). Vznikne aktualita v kategorii zpravodaj s obsahem čísla, odkazy ke stažení, tabulkami „Z evidence obyvatel“ a „Hospodaření obce“ a tiráží. Stejný ročník a číslo = úprava. Počet obyvatel v úvodu webu se bere z posledního zveřejněného čísla. Budoucí jednorázové akce z metadat se založí jako koncepty akcí (pokud ve stejný den už podobná akce není). "rozeslat": true rozešle číslo e-mailem odběratelům (jen jednou a jen s oprávněním infokanal:rozeslat). Schéma metadat je v /api/openapi.json.

curl -sS https://vlastiborice.cz/api/v1/zpravodaj -H "Authorization: Bearer $TOKEN" \
  -F metadata=@zpravodaj-2026-3.json -F pdf=@2026-03-web.pdf -F pdf_tisk=@2026-03-tisk.pdf -F obalka=@obalka.png