API e integrazioni

Avvio rapido

1. Come amministratori comunali verificati, aprite le chiavi API del vostro Comune. Create per ogni integrazione una chiave distinta con i diritti più limitati possibile.
2. Copiate la chiave subito dopo averla creata. Viene mostrata una sola volta. Conservatela nella configurazione protetta del vostro server.
3. Trasmettete la chiave esclusivamente nell’header Authorization come token Bearer. Lo slug del Comune e il numero pubblico della segnalazione determinano l’endpoint.
4. Provate prima in sola lettura. Attivate i diritti di scrittura o interni solo se lo strumento collegato ne ha effettivamente bisogno.

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

Ogni chiave è associata a un solo Comune e al creatore autorizzato. La revoca, la scadenza o la perdita dei diritti di gestione bloccano l’accesso. Le nuove chiavi scadono normalmente dopo 90 giorni; il massimo è 365 giorni.

Autorizzazioni

I quattro diritti vengono assegnati separatamente. I diritti di scrittura non includono automaticamente quelli di lettura. Per un flusso completo di lettura e scrittura, scegliete la coppia di diritti appropriata.

I dati interni devono essere richiesti esplicitamente. La vista predefinita resta pubblica. Anche un accesso interno autorizzato non restituisce account utente completi, password o campi arbitrari del database.

Per scrivere contenuti pubblici serve anche public:read, per leggere la versione di modifica attuale. Per le note interne basta la coppia internal:read e internal:write.

Endpoint

URL di base: https://www.region360.dev/api/v1

municipality è l’identificativo del Comune nell’URL, report è il numero pubblico della segnalazione. L’API supporta problemi e idee. Questa versione non prevede nuove segnalazioni, eliminazioni o caricamenti di file.

L’elenco supporta q, type, status, page e per_page. Vengono restituiti al massimo 100 elementi per pagina. visibility=internal richiede entrambi i diritti di lettura; senza questa indicazione si ottiene la vista pubblica.

I codici di stato restano indipendenti dalla lingua: open, progress, external e done. Gli orari usano ISO 8601; struttura e valori consentiti sono descritti nel documento OpenAPI.

Esempi di codice

Gli esempi usano variabili di ambiente per la chiave e identificativi fittizi. Sostituite gli identificativi con quelli del vostro Comune e della vostra segnalazione.

Leggere segnalazioni pubbliche · 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'

Aggiornamento pubblico · JavaScript sul 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 contiene l’URL di base completo, incluso /api/v1. Dopo un conflitto di versione, non riprovate a scrivere senza verificare: caricate lo stato attuale e decidete in base alle modifiche.

Errori e conflitti di versione

401

La chiave manca, non è valida, è scaduta o è stata revocata; anche la revoca dei diritti di gestione ne blocca l’uso.

403

Manca il diritto richiesto, l’autorizzazione comunale o il pacchetto necessario.

404

Il Comune o la segnalazione non è disponibile per questa chiave.

409

La versione di modifica è superata. Ricaricate lo stato attuale e verificate le modifiche.

422

I dati sono incompleti o non validi. Controllate gli errori nei campi.

429

Troppe richieste. Attendete e rispettate le indicazioni sui limiti di frequenza.

Ogni richiesta di scrittura richiede la edit_version attuale. Il controllo della versione protegge da sovrascritture accidentali tra il vostro strumento e il portale comunale. Un timeout da solo non dimostra che una modifica sia fallita: prima di riprovare a scrivere, controllate la cronologia attuale.

SDK e gestione operativa

Il documento OpenAPI descrive autenticazione, richieste e risposte in formato leggibile dalle macchine. Può essere importato in strumenti compatibili con OpenAPI per generare client nel vostro linguaggio di programmazione.

Usate una chiave distinta per ogni integrazione, documentate il responsabile e rinnovate le chiavi prima della scadenza. In caso di sospetta divulgazione, revocate subito la chiave nel portale comunale.

I percorsi sotto /api/v1 e i nomi tecnici dei campi non vengono tradotti con la lingua dell’interfaccia. Le integrazioni restano così stabili anche cambiando lingua.