API et intégrations

Démarrage rapide

1. En tant que gestionnaire communal vérifié, ouvrez les clés API de votre commune. Créez pour chaque intégration une clé distincte avec les droits les plus limités possible.
2. Copiez la clé immédiatement après sa création. Elle n’est affichée qu’une seule fois. Conservez-la dans la configuration sécurisée de votre serveur.
3. Transmettez la clé uniquement dans l’en-tête Authorization comme jeton Bearer. Le slug de la commune et le numéro public du signalement déterminent le point de terminaison.
4. Testez d’abord en lecture seule. N’activez les droits d’écriture ou internes que si l’outil connecté en a réellement besoin.

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

Chaque clé est liée à une seule commune et à son créateur autorisé. La révocation, l’expiration ou la perte des droits de gestion bloque l’accès. Les nouvelles clés expirent par défaut après 90 jours ; la durée maximale est de 365 jours.

Autorisations

Les quatre droits sont attribués séparément. Les droits d’écriture n’incluent pas automatiquement les droits de lecture. Pour un processus complet de lecture et d’écriture, choisissez la paire de droits appropriée.

Les données internes doivent être demandées explicitement. La vue par défaut reste publique. Même un accès interne autorisé ne fournit pas les comptes utilisateur complets, les mots de passe ou des champs arbitraires de la base de données.

Pour écrire des contenus publics, vous avez aussi besoin de public:read afin de lire la version de modification actuelle. Pour les notes internes, la paire internal:read et internal:write suffit.

Points de terminaison

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

municipality est l’identifiant de la commune dans l’URL et report le numéro public du signalement. L’API prend en charge les problèmes et les idées. Cette version ne prévoit pas de nouveaux signalements, de suppressions ou de téléversements de fichiers.

La liste prend en charge q, type, status, page et per_page. Chaque page contient au maximum 100 éléments. visibility=internal exige les deux droits de lecture ; sans ce paramètre, vous obtenez la vue publique.

Les codes d’état restent indépendants de la langue : open, progress, external et done. Les dates et heures utilisent ISO 8601 ; la structure et toutes les valeurs autorisées figurent dans le document OpenAPI.

Exemples de code

Les exemples utilisent des variables d’environnement pour la clé et des identifiants fictifs. Remplacez les identifiants par ceux de votre commune et de votre signalement.

Lire les signalements publics · 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'

Information publique · JavaScript côté serveur

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 contient l’URL de base complète, y compris /api/v1. Après un conflit de version, ne réessayez pas d’écrire sans vérifier : chargez l’état actuel et décidez en fonction des modifications.

Erreurs et conflits de version

401

La clé manque, est invalide, expirée ou révoquée ; le retrait des droits de gestion bloque également son utilisation.

403

Le droit demandé, l’autorisation communale ou l’offre nécessaire manque.

404

La commune ou le signalement n’est pas accessible avec cette clé.

409

La version de modification est dépassée. Rechargez l’état actuel et vérifiez les changements.

422

Les données sont incomplètes ou invalides. Vérifiez les erreurs des champs.

429

Trop de requêtes. Faites une pause et respectez les indications de limitation du débit.

Chaque requête d’écriture nécessite la edit_version actuelle. La vérification de version évite les écrasements accidentels entre votre outil et le portail communal. Un délai d’attente dépassé ne prouve pas à lui seul qu’une modification a échoué : vérifiez l’historique actuel avant de réessayer d’écrire.

SDK et exploitation

Le document OpenAPI décrit l’authentification, les requêtes et les réponses dans un format lisible par machine. Il peut être importé dans des outils compatibles OpenAPI pour générer des clients dans votre langage de programmation.

Utilisez une clé distincte pour chaque intégration, documentez le responsable et renouvelez les clés avant leur expiration. En cas de suspicion de divulgation, révoquez immédiatement la clé dans le portail communal.

Les chemins sous /api/v1 et les noms techniques des champs ne sont pas traduits avec la langue de l’interface. Les intégrations restent ainsi stables lors d’un changement de langue.