API a integrace

Rychlý start

1. Jako ověřený správce obce otevřete klíče API své obce. Pro každou integraci vytvořte vlastní klíč s co nejmenšími oprávněními.
2. Klíč zkopírujte ihned po vytvoření. Zobrazí se pouze jednou. Uložte jej do chráněné konfigurace svého serveru.
3. Předávejte jej výhradně v hlavičce Authorization jako Bearer token. Identifikátor obce a veřejné číslo hlášení určují příslušný koncový bod.
4. Nejdříve otestujte čtení. Zápisová nebo interní oprávnění aktivujte pouze tehdy, když je připojený nástroj skutečně potřebuje.

Authorization: Bearer <API_KEY>
Accept: application/json
Content-Type: application/json

Klíče jsou vázány právě na jednu obec a oprávněného tvůrce. Odvolání, vypršení nebo ztráta práv správy zablokuje přístup. Nové klíče standardně vyprší po 90 dnech; maximum je 365 dní.

Oprávnění

Čtyři oprávnění se přidělují samostatně. Zápis automaticky nezahrnuje čtení. Pro úplný postup čtení a zápisu zvolte příslušnou dvojici oprávnění.

Interní data je nutné výslovně vyžádat. Výchozí pohled zůstává veřejný. Ani oprávněný interní přístup neposkytuje úplné uživatelské účty, hesla ani libovolná databázová pole.

Pro veřejný zápis navíc potřebujete public:read k načtení aktuální verze úprav. Pro interní poznámky stačí dvojice internal:read a internal:write.

Koncové body

Základní URL: https://www.region360.dev/api/v1

municipality je identifikátor obce z URL, report je veřejné číslo hlášení. API podporuje problémy a nápady. V této verzi není zahrnuto vytváření nových podnětů, mazání ani nahrávání souborů.

Seznam podporuje q, type, status, page a per_page. Na jedné stránce se vrací nejvýše 100 záznamů. visibility=internal vyžaduje obě oprávnění pro čtení; bez tohoto údaje získáte veřejný pohled.

Kódy stavů jsou nezávislé na jazyce: open, progress, external a done. Časové údaje používají ISO 8601; struktura a všechny povolené hodnoty jsou popsány v dokumentu OpenAPI.

Příklady kódu

Příklady používají proměnné prostředí pro klíč a smyšlené identifikátory. Nahraďte identifikátory vlastní obcí a číslem hlášení.

Číst veřejné podněty · cURL

curl --fail-with-body \
  -H "Authorization: Bearer $REGION360_API_KEY" \
  -H 'Accept: application/json' \
  'https://www.region360.dev/api/v1/municipalities/sonnental/reports?per_page=20'

Veřejné vyjádření · JavaScript na serveru

const base = process.env.REGION360_BASE_URL;
const headers = {
  Authorization: `Bearer ${process.env.REGION360_API_KEY}`,
  Accept: 'application/json',
  'Content-Type': 'application/json'
};
const path = '/municipalities/sonnental/reports/ABCD-2345';
const current = await fetch(`${base}${path}`, { headers });
if (!current.ok) throw new Error(`Region360: ${current.status}`);
const { data } = await current.json();
const result = await fetch(`${base}${path}/progress`, {
  method: 'PATCH', headers,
  body: JSON.stringify({
    edit_version: data.edit_version,
    status: 'progress',
    message: 'Die Reparatur ist eingeplant.'
  })
});
if (result.status === 409) {
  throw new Error('Version conflict: reload and review before retrying.');
}
if (!result.ok) throw new Error(`Region360: ${result.status}`);

REGION360_BASE_URL obsahuje úplnou základní URL včetně /api/v1. Po konfliktu verzí neopakujte zápis bez kontroly: načtěte aktuální stav a rozhodněte podle změn.

Chyby a konflikty verzí

401

Klíč chybí, je neplatný, vypršel nebo byl odvolán; zablokuje jej i odebrání práv správy.

403

Chybí potřebné oprávnění, přístup k obci nebo požadovaný balíček.

404

Obec nebo podnět není pro tento klíč dostupný.

409

Verze úprav je zastaralá. Načtěte aktuální stav a zkontrolujte změny.

422

Údaje jsou neúplné nebo neplatné. Zkontrolujte chyby u jednotlivých polí.

429

Příliš mnoho požadavků. Vyčkejte a dodržujte údaje o omezení četnosti.

Každý požadavek zápisu potřebuje aktuální edit_version. Kontrola verze chrání před nechtěným přepsáním mezi vaším nástrojem a obecním portálem. Samotný timeout nedokazuje, že změna selhala: před opakováním zápisu zkontrolujte aktuální historii.

SDK a provoz

Dokument OpenAPI popisuje autentizaci, požadavky a odpovědi ve strojově čitelném formátu. Lze jej importovat do nástrojů kompatibilních s OpenAPI a vytvořit klienty pro váš programovací jazyk.

Pro každou integraci používejte vlastní klíč, evidujte odpovědnou osobu a obnovujte klíče před vypršením. Při podezření na vyzrazení klíč ihned odvolejte v obecním portálu.

Cesty pod /api/v1 a technické názvy polí se nepřekládají podle jazyka rozhraní. Integrace tak zůstávají stabilní i při změně jazyka.