API Acteurs

Objectif

Consulter et gérer les acteurs locaux, leurs tags, documents, XP et actions administratives.

Périmètre

Acteurs publics, gestion authentifiée, validation backoffice et droits liés aux acteurs.

Acteurs/applications consommatrices

• DMV public.
• Backoffice.
• AssoSuite.
• Mairie.
• PlayLoop admin selon acteur propriétaire.

Authentification requise

• Lecture publique avec X-App-Source.
• Écriture avec auth:sanctum.
• Admin avec ensure.admin.

Permissions/RBAC

• Le socle d’autorité acteur est désormais :
  • acteur_collaborateurs
  • acteur_roles
  • acteur_permissions
  • acteur_role_permissions
  • acteur_modules
• user_acteurs reste une projection technique de compatibilité workspace, mais n’est plus la source d’autorité RBAC.
• Admin global : platform_admin via users_roles, avec bypass contrôlé côté Laravel.
• Un accès acteur effectif exige :
  • un collaborateur active
  • un rôle valide
  • des permissions explicites
  • et, si la fonctionnalité est modulaire, le module actif correspondant.

Rôles système initiaux

• owner
• admin
• editor
• publisher
• viewer

Permissions initiales

• manage_actor
• manage_collaborators
• manage_publications
• publish_publications
• manage_documents
• view_statistics
• manage_infos
• manage_services
• manage_elus
• manage_collectes
• manage_alertes

Endpoints actuels visibles si confirmés

Méthode	Route	Statut
GET	/api/v1/acteurs	Confirmé.
GET	/api/v1/acteurs/{slug}	Confirmé.
GET	/api/v1/acteurs/{slug}/tags	Confirmé.
GET	/api/v1/acteurs/{slug}/documents	Confirmé.
GET	/api/v1/acteurs/{slug}/xp	Confirmé, authentifié.
POST	/api/v1/acteurs	Confirmé, authentifié.
PATCH	/api/v1/acteurs/{id}	Confirmé, authentifié.
DELETE	/api/v1/acteurs/{id}	Confirmé, authentifié.
POST	/api/v1/acteurs/{id}/tags	Confirmé.
POST	/api/v1/acteurs/{id}/documents	Confirmé.
DELETE	/api/v1/acteurs/{id}/documents/{documentId}	Confirmé.
PATCH	/api/v1/acteurs/{id}/documents/{documentId}/pin	Confirmé.
POST	/api/v1/acteurs/{id}/xp	Confirmé.
GET	/api/v1/acteurs/{acteurId}/access-context	Confirmé, authentifié.
GET	/api/v1/acteurs/{acteurId}/collaborateurs	Confirmé, authentifié.
GET	/api/v1/acteurs/{acteurId}/collaborateurs/search-users	Confirmé, authentifié.
POST	/api/v1/acteurs/{acteurId}/collaborateurs/invite	Confirmé, authentifié.
POST	/api/v1/acteurs/{acteurId}/collaborateurs/attach	Confirmé, authentifié.
PATCH	/api/v1/acteurs/{acteurId}/collaborateurs/{collaborateurId}	Confirmé, authentifié.
POST	/api/v1/acteurs/{acteurId}/collaborateurs/{collaborateurId}/suspend	Confirmé, authentifié.
POST	/api/v1/acteurs/{acteurId}/collaborateurs/{collaborateurId}/reactivate	Confirmé, authentifié.
DELETE	/api/v1/acteurs/{acteurId}/collaborateurs/{collaborateurId}	Confirmé, authentifié.
GET	/api/v1/admin/acteurs	Confirmé admin.
PATCH	/api/v1/admin/acteurs/{id}/validate	Confirmé admin.
PATCH	/api/v1/admin/acteurs/{id}/badge	Confirmé admin.
DELETE	/api/v1/admin/acteurs/{id}/restore	Confirmé admin.
POST	/api/v1/admin/acteurs/{id}/can-publish	Confirmé admin.

Endpoints cibles proposés si utile

• Endpoint d’acceptation d’invitation collaborateur à expliciter si l’invitation sort du simple rattachement interne.

Exemple de requête

GET /api/v1/acteurs?commune_id=commune-id&q=boulangerie
X-App-Source: dmv

Exemple de réponse succès

{
  "data": [
    {
      "id": "acteur-id",
      "nom": "Nom acteur",
      "slug": "nom-acteur",
      "kind": "pro",
      "commune_id": "commune-id"
    }
  ]
}

Exemple d’erreur

{
  "error": "forbidden",
  "message": "Vous ne pouvez pas modifier cet acteur."
}

Pagination si applicable

Applicable sur /acteurs et /admin/acteurs.

Rate limiting si applicable

Recommandé sur création, mise à jour, documents et XP.

Audit/logs si applicable

Obligatoire pour validation, badge, restauration, droits de publication et changements sensibles.

Sécurité

• Séparer données publiques et données de gestion.
• Les droits acteur doivent être contrôlés côté Laravel.
• Les documents uploadés doivent suivre les règles média.

État actuel vs cible

Sujet	État actuel	Cible
Lecture/écriture acteur	Routes visibles.	Contrats payload stabilisés.
RBAC acteur	En place via collaborateurs + rôles + permissions + modules.	Supprimer la dépendance workspace résiduelle à user_acteurs.

Points à confirmer

• Payloads exacts.
• Règles de documents.
• Règle finale d’acceptation d’invitation collaborateur.
• Cycle de suppression/restauration.