API és integrációk

Gyors kezdés

1. Megerősített önkormányzati ügykezelőként nyissa meg önkormányzata API-kulcsait. Minden integrációhoz külön, a lehető legszűkebb jogkörű kulcsot hozzon létre.
2. Létrehozás után azonnal másolja ki a kulcsot. Csak egyszer jelenik meg. Tárolja szervere védett konfigurációjában.
3. Kizárólag az Authorization fejlécben, Bearer-tokenként adja át. Az önkormányzat URL-azonosítója és a nyilvános bejelentésszám határozza meg a megfelelő végpontot.
4. Először olvasási módban teszteljen. Írási vagy belső jogosultságokat csak akkor aktiváljon, ha a csatlakoztatott eszköznek valóban szüksége van rájuk.

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

A kulcsok pontosan egy önkormányzathoz és a jogosult létrehozóhoz kötődnek. A visszavonás, lejárat vagy az ügykezelői jog elvesztése letiltja a hozzáférést. Az új kulcsok alapértelmezés szerint 90 nap után járnak le; legfeljebb 365 nap engedélyezett.

Jogosultságok

A négy jogosultság külön adható meg. Az írási jog nem foglalja magában automatikusan az olvasást. A teljes olvasási és írási folyamathoz válassza a megfelelő jogosultságpárt.

A belső adatokat kifejezetten kérni kell. Az alapértelmezett nézet nyilvános. A jogosult belső hozzáférés sem ad vissza teljes felhasználói fiókokat, jelszavakat vagy tetszőleges adatbázismezőket.

A nyilvános íráshoz a public:read jog is szükséges az aktuális szerkesztési verzió olvasásához. Belső jegyzetekhez elegendő az internal:read és internal:write páros.

Végpontok

Alap-URL: https://www.region360.dev/api/v1

A municipality az önkormányzat URL-ben szereplő azonosítója, a report a bejelentés nyilvános száma. Az API problémákat és ötleteket támogat. Új ügyek létrehozása, törlés és fájlfeltöltés ebben a verzióban nem szerepel.

A lista támogatja a q, type, status, page és per_page paramétereket. Oldalanként legfeljebb 100 bejegyzést ad vissza. A visibility=internal mindkét olvasási jogot megköveteli; e paraméter nélkül a nyilvános nézetet kapja.

Az állapotkódok nyelvfüggetlenek: open, progress, external és done. Az időadatok ISO 8601 formátumúak; a szerkezet és minden engedélyezett érték az OpenAPI-dokumentumban található.

Kódpéldák

A példák környezeti változókat használnak a kulcshoz, valamint fiktív azonosítókat. Cserélje az azonosítókat saját önkormányzatára és bejelentésszámára.

Nyilvános ügyek olvasása · 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'

Nyilvános tájékoztatás · JavaScript a szerveren

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}`);

A REGION360_BASE_URL a teljes alap-URL-t tartalmazza, az /api/v1 részt is beleértve. Verzióütközés után ne ismételje meg ellenőrzés nélkül az írást: töltse be az aktuális állapotot, és a módosítások alapján döntsön.

Hibák és verzióütközések

401

A kulcs hiányzik, érvénytelen, lejárt vagy visszavont; az ügykezelői jogosultság visszavonása is letiltja.

403

Hiányzik a szükséges jogosultság, önkormányzati hozzáférés vagy csomag.

404

Az önkormányzat vagy az ügy nem érhető el ezzel a kulccsal.

409

A szerkesztési verzió elavult. Töltse be az aktuális állapotot, és ellenőrizze a módosításokat.

422

Az adatok hiányosak vagy érvénytelenek. Ellenőrizze a mezőhibákat.

429

Túl sok kérés. Tartson szünetet, és kövesse a kérésszámkorlátra vonatkozó adatokat.

Minden írási kéréshez szükséges az aktuális edit_version. A verzióellenőrzés védi az Ön eszköze és az önkormányzati portál közötti véletlen felülírástól. Az időtúllépés önmagában nem bizonyítja a módosítás sikertelenségét: újabb írási kísérlet előtt ellenőrizze az aktuális előzményeket.

SDK és üzemeltetés

Az OpenAPI-dokumentum géppel olvashatóan írja le a hitelesítést, a kéréseket és a válaszokat. OpenAPI-kompatibilis eszközökbe importálva kliensek hozhatók létre az Ön programozási nyelvéhez.

Minden integrációhoz külön kulcsot használjon, tartsa nyilván a felelős személyt, és lejárat előtt újítsa meg a kulcsokat. Ha felmerül a kulcs kiszivárgásának gyanúja, azonnal vonja vissza az önkormányzati portálon.

Az /api/v1 alatti útvonalak és a technikai mezőnevek nem változnak a felület nyelvével. Így az integrációk nyelvváltáskor is stabilak maradnak.