API Abonnements

Objectif

Consulter les plans, gérer une souscription acteur et relier les droits premium à la logique backend.

Périmètre

Plans, abonnement acteur, compte Stripe, souscription et désabonnement.

Acteurs/applications consommatrices

• DMV acteur.
• Backoffice.
• Mairie en cible offres spécifiques.
• PlayLoop en cible selon modèle économique.

Authentification requise

• /plans : public avec X-App-Source.
• Actions abonnement : auth:sanctum.
• Webhook Stripe : signature Stripe, sans identify.app.

Permissions/RBAC

• Gestion réservée aux gestionnaires de l’acteur ou admins autorisés.
• Droits premium calculés côté Laravel.

Endpoints actuels visibles si confirmés

Méthode	Route	Statut
GET	/api/v1/plans	Confirmé.
GET	/api/v1/acteurs/{id}/subscription	Confirmé.
POST	/api/v1/acteurs/{id}/stripe-account	Confirmé.
POST	/api/v1/acteurs/{id}/subscribe	Confirmé.
POST	/api/v1/acteurs/{id}/unsubscribe	Confirmé.
GET	/api/v1/admin/subscriptions	Confirmé admin.

Endpoints cibles proposés si utile

• Endpoints offres mairie et PlayLoop dédiés à confirmer.

Exemple de requête

POST /api/v1/acteurs/acteur-id/subscribe
Authorization: Bearer <token>
X-App-Source: dmv
Content-Type: application/json

{
  "plan_id": "plan-standard"
}

Exemple de réponse succès

{
  "data": {
    "subscription_id": "subscription-id",
    "status": "pending_payment"
  }
}

Exemple d’erreur

{
  "error": "subscription_denied",
  "message": "Vous ne pouvez pas gérer l’abonnement de cet acteur."
}

Pagination si applicable

Applicable à /admin/subscriptions.

Rate limiting si applicable

Recommandé sur souscription, désabonnement et création de compte Stripe.

Audit/logs si applicable

Obligatoire sur changement d’offre, annulation et changement provider.

Sécurité

• Confirmation paiement côté backend.
• Ne pas stocker les données bancaires sensibles.
• Traitement idempotent des webhooks.

État actuel vs cible

Sujet	État actuel	Cible
Plans/souscriptions	Routes visibles.	Contrats offres stabilisés.
Offres mairie/PlayLoop	Pas de routes dédiées confirmées.	À définir selon business model.

Points à confirmer

• Plans finaux.
• Statuts subscription.
• Webhooks traités.
• Périmètre mairie et PlayLoop.