API & Integrationen

Schnellstart

1. Öffnen Sie als bestätigter Gemeindeverwalter die API-Schlüssel Ihrer Gemeinde. Legen Sie für jede Integration einen eigenen, möglichst eingeschränkten Schlüssel an.
2. Kopieren Sie den Schlüssel direkt nach dem Erstellen. Er wird nur einmal angezeigt. Legen Sie ihn in der geschützten Konfiguration Ihres Servers ab.
3. Übergeben Sie ihn ausschließlich im Authorization-Header als Bearer-Token. Gemeinde-Slug und öffentliche Meldungsnummer bestimmen den jeweiligen Endpunkt.
4. Testen Sie zuerst lesend. Aktivieren Sie schreibende oder interne Rechte nur, wenn das angeschlossene Werkzeug diese tatsächlich benötigt.

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

Schlüssel sind an genau eine Gemeinde und den berechtigten Ersteller gebunden. Widerruf, Ablauf oder der Verlust der Verwaltungsberechtigung sperren den Zugriff. Neue Schlüssel laufen standardmäßig nach 90 Tagen ab; maximal sind 365 Tage möglich.

Berechtigungen

Die vier Rechte werden getrennt vergeben. Schreibrechte schließen Leserechte nicht automatisch ein. Für einen vollständigen Lese- und Schreibablauf wählen Sie das jeweils passende Rechtepaar.

Interne Daten sind ausdrücklich anzufordern. Der Standard bleibt öffentlich. Auch ein berechtigter interner Zugriff liefert keine vollständigen Benutzerkonten, Passwörter oder beliebigen Datenbankfelder.

Zum öffentlichen Schreiben benötigen Sie zusätzlich public:read, um die aktuelle Bearbeitungsversion zu lesen. Für interne Notizen genügt das Paar internal:read und internal:write.

Endpunkte

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

municipality ist die Gemeinde-Kennung aus der URL, report die öffentliche Meldungsnummer. Die API unterstützt Probleme und Ideen. Neue Anliegen, Löschungen und Datei-Uploads sind in dieser Version nicht vorgesehen.

Die Liste unterstützt q, type, status, page und per_page. Maximal 100 Einträge werden je Seite ausgegeben. visibility=internal verlangt beide Leserechte; ohne diese Angabe erhalten Sie die öffentliche Ansicht.

Statuscodes bleiben sprachunabhängig: open, progress, external und done. Zeitangaben verwenden ISO 8601; Hinweise zur Struktur und alle erlaubten Werte stehen im OpenAPI-Dokument.

Codebeispiele

Die Beispiele verwenden Umgebungsvariablen für den Schlüssel und fiktive Kennungen. Ersetzen Sie die Kennungen durch Ihre eigene Gemeinde und Meldungsnummer.

Öffentliche Anliegen lesen · 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'

Öffentliche Rückmeldung · JavaScript auf dem Server

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 enthält die vollständige Basis-URL einschließlich /api/v1. Schreiben Sie nach einem Versionskonflikt nicht ungeprüft erneut: Laden Sie den aktuellen Stand und entscheiden Sie anhand der Änderungen.

Fehler & Versionskonflikte

401

Schlüssel fehlt, ist ungültig, abgelaufen oder widerrufen; auch entzogene Verwaltungsrechte sperren ihn.

403

Das benötigte Recht, die Gemeindeberechtigung oder das erforderliche Paket fehlt.

404

Die Gemeinde oder das Anliegen ist für diesen Schlüssel nicht verfügbar.

409

Die Bearbeitungsversion ist veraltet. Aktuellen Stand neu laden und Änderungen prüfen.

422

Eingaben sind unvollständig oder ungültig. Feldfehler beachten.

429

Zu viele Anfragen. Eine Pause einlegen und die Rate-Limit-Angaben beachten.

Jeder Schreibaufruf benötigt die aktuelle edit_version. Die Versionsprüfung schützt vor dem versehentlichen Überschreiben zwischen Ihrem Werkzeug und dem Gemeindeportal. Ein Timeout allein beweist nicht, dass eine Änderung fehlgeschlagen ist: Prüfen Sie vor einem erneuten Schreibversuch den aktuellen Verlauf.

SDK und Betrieb

Das OpenAPI-Dokument beschreibt Authentifizierung, Anfragen und Antworten maschinenlesbar. Es kann in OpenAPI-kompatible Werkzeuge importiert werden, um Clients für Ihre Programmiersprache zu erzeugen.

Verwenden Sie pro Integration einen eigenen Schlüssel, dokumentieren Sie die verantwortliche Stelle und erneuern Sie Schlüssel vor ihrem Ablauf. Bei einem Verdacht auf Offenlegung widerrufen Sie den Schlüssel sofort im Gemeindeportal.

Die Pfade unter /api/v1 und die technischen Feldnamen werden nicht mit der Oberflächensprache übersetzt. Damit bleiben Integrationen auch beim Sprachwechsel stabil.