API Communes

Objectif

Exposer les communes comme pivot territorial DMV : recherche locale, rattachement des acteurs, publications, services et informations pratiques.

Périmètre

Lecture publique des communes et de leurs sous-ressources territoriales visibles : élus, collectes et informations.

Applications consommatrices

• DMV public.
• Backoffice en lecture.
• Mairie.
• AssoSuite et PlayLoop indirectement via rattachement territorial.
• IA uniquement via services Laravel contrôlés, jamais directement.

Authentification requise

Les routes visibles sont publiques sans auth:sanctum, mais nécessitent X-App-Source via identify.app.

Permissions/RBAC

• Lecture publique filtrée par contexte applicatif.
• Écriture commune visible uniquement côté admin via routes Admin.
• Les rôles mairie ne doivent pas donner un droit global sur la commune hors périmètre encadré.

Endpoints confirmés visibles

Méthode	Route	Auth	Notes
GET	/api/v1/communes	X-App-Source	Liste paginée, commentaire code : 15 par page.
GET	/api/v1/communes/{slug}	X-App-Source	Détail par slug.
GET	/api/v1/communes/{id}/elus	X-App-Source	Sous-ressource par UUID selon commentaire code.
GET	/api/v1/communes/{id}/collectes	X-App-Source	Sous-ressource collectes.
GET	/api/v1/communes/{id}/infos	X-App-Source	Sous-ressource informations.
GET	/api/v1/communes/{id}/defibrillateurs	X-App-Source	Défibrillateurs actifs d'une commune + méta de sync.
GET	/api/v1/defibrillateurs	X-App-Source	Catalogue national GEODAE paginé, avec recherche.

Endpoints cibles si nécessaire

• Aucun endpoint public supplémentaire proposé à ce stade.
• Les écritures sont déjà couvertes côté admin : /api/v1/admin/communes.

Exemples génériques de requête/réponse

GET /api/v1/communes?page=1
X-App-Source: dmv

{
  "data": [
    {
      "id": "commune-id",
      "slug": "nom-commune",
      "nom": "Nom Commune"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 15
  }
}

Exemple défibrillateurs d'une commune :

GET /api/v1/communes/commune-id/defibrillateurs
X-App-Source: dmv

{
  "defibrillateurs": [],
  "meta": {
    "count": 0,
    "last_synced_at": null,
    "sync_status": null
  }
}

Fusion des informations mairie

Pour GET /api/v1/communes/{id}/infos, la section mairie applique la règle suivante quand communes.mairie_actor_id est renseigné :

• les coordonnées de l'acteur mairie sont prioritaires pour adresse, telephone, email et site_web
• les lignes commune_infos restantes sont conservées en complément
• si l'acteur mairie est absent ou incomplet, commune_infos reste le fallback

L'objectif est de faire primer les données métier éditables par l'acteur mairie sur les données plus génériques issues de l'import initial de la commune.

Erreurs principales

{
  "error": "missing_app_source",
  "message": "Le header X-App-Source est obligatoire."
}

Audit/logs si applicable

• Lecture publique : logs techniques agrégés uniquement.
• Écriture commune : audit côté routes Admin.

Sécurité

• Ne pas exposer d’informations mairie internes dans les endpoints publics.
• Les données territoriales publiques peuvent être cacheables avec invalidation maîtrisée.
• L’IA ne consomme ce contexte que via services backend filtrés.

État actuel vs cible

Sujet	État actuel	Cible
Lecture communes	Routes confirmées.	Contrat de pagination/filtres stabilisé.
Écriture communes	Routes admin confirmées.	Audit obligatoire et validation territoriale.
PostGIS	Documenté comme stratégique.	Recherche proximité à préciser.

Points à confirmer

• Champs exacts renvoyés par commune.
• Filtres géographiques et recherche.
• Source référentielle officielle.
• Niveau territorial futur : commune seule ou intercommunalité.