# Forfaits d'abonnement

L'API Subscription Plans gère les forfaits définis par le tenant : nombre d'annonces autorisées pour un compte, période d'expiration et frais ou commissions sur les commandes. Elle est distincte de l'API Memberships basée sur des annonces (`/v1/memberships`), destinée aux programmes de membres et clients d'une entreprise.

Tous les exemples utilisent l'authentification Bearer. Le tenant et l'utilisateur sont déterminés à partir de la requête authentifiée ; n'envoyez pas d'en-têtes d'identité supplémentaires.

```bash
export API="https://api.tradly.app"
export TOKEN="<bearer-token>"
```

## Gérer les forfaits

- `GET /v1/subscription_products` liste les forfaits visibles pour le tenant. Les paramètres facultatifs incluent `currency_id`, `account_id` et `include_stats=true`. Les non-administrateurs ne voient que les forfaits actifs et doivent fournir le contexte de devise.
- `GET /v1/subscription_products/{id}` renvoie un forfait. Les non-administrateurs ne peuvent récupérer que les forfaits actifs et doivent fournir le contexte de devise requis.
- `POST /v1/subscription_products` crée un forfait dans l'objet `subscription_product`. Champs requis : `title`, `allowed_listings` (> 0), `currency_id`, `expiry_days` (> 0) et `type`. Valeurs `type` acceptées : `free_subscription`, `stripe`, `android`, `ios`, `mangopay`.

```bash
curl -X POST "$API/v1/subscription_products" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  --data-raw '{"subscription_product":{"title":"Starter","description":"Starter plan","amount":49.00,"currency_id":13,"expiry_days":30,"allowed_listings":25,"type":"stripe","sku":"starter-monthly","active":true,"fee_fixed_per_order":0,"commission_percent_per_order":0,"metadata":{}}}'
```

La réponse inclut le nouvel `subscription_product.id`.

- `PUT /v1/subscription_products/{id}` met à jour un forfait avec le même objet et les champs requis. Valeurs acceptées : `stripe`, `android`, `ios`, `mangopay` ; ce validateur n'accepte pas `free_subscription`.
- `DELETE /v1/subscription_products/{id}` archive le forfait et le marque inactif, sans supprimer l'historique.

## Analytique des forfaits

Les routes d'analyse sont limitées au tenant authentifié.

| Méthode | Point de terminaison | Description |
|---|---|---|
| `GET` | `/v1/subscription_products/stats` | Statistiques agrégées des forfaits du tenant. |
| `GET` | `/v1/subscription_products/{id}/stats` | Statistiques d'un forfait. |
| `GET` | `/v1/subscription_products/{id}/subscribers` | Abonnés paginés ; filtres `page`, `per_page` (max. 100), `status` (`active`, `trial`, `expired`, `cancelled`). |
| `GET` | `/v1/subscription_products/{id}/invoices` | Historique de facturation paginé avec les mêmes filtres ; dérivé des abonnements, sans table de factures séparée. |
| `GET` | `/v1/subscription_products/{id}/revenue` | Séries mensuelles de revenus et du nombre d'abonnés. |

Les statistiques agrégées comprennent les nombres d'abonnements actifs, annulés, expirés et à l'essai, MRR/ARR, le taux de résiliation, les nouveaux abonnés et résiliations du mois, la durée moyenne des abonnements annulés et le revenu total enregistré. Ce sont des analyses opérationnelles, pas un substitut aux factures comptables ou au grand livre.

## Cycle de vie des abonnements clients

| Méthode | Point de terminaison | Fonction |
|---|---|---|
| `GET` | `/v1/subscriptions/subscribe/products?account_id={account_id}` | Liste les forfaits disponibles d'un compte ; filtre facultatif `type`. |
| `POST` | `/v1/subscriptions/subscribe` | Confirme un achat mobile avec `account_id`, `subscription_product_id` et le reçu `token`. Le gestionnaire vérifie les reçus iOS/Android. |
| `POST` | `/v1/subscriptions/subscribe/confirm` | Confirme un achat mobile avec les mêmes champs requis. |
| `POST` | `/v1/subscriptions/email_trigger` | Envoie l'email d'invitation à s'abonner pour un compte admissible (`account_id`). |
| `DELETE` | `/v1/subscriptions/unsubscribe` | Annule l'abonnement du compte (`account_id`). |
| `GET` | `/v1/subscriptions/subscribe/manage?account_id={account_unique_id}&tenant_id={tenant_unique_id}` | Ouvre la page de gestion ou le portail client pris en charge (actuellement Stripe). |

La confirmation d'achat prend actuellement en charge les reçus iOS et Android. Les forfaits `stripe` ne sont pas confirmés par ces points de terminaison de reçus : utilisez le processus Checkout/portail Stripe configuré. Les points de transfert web ont un ancien contrat distinct et ne sont pas présentés comme exemples client Bearer uniquement.

## API associées

- [Adhésions](memberships) — adhésions liées aux annonces, contributions et journaux de prix.
- [Annonces](listings) — offres et produits, et paiement.