API — Facturation

Les endpoints de facturation gèrent l'abonnement Stripe de votre compte SendAs.me.

Modèle de facturation

SendAs.me facture par boîte email OAuth connectée par mois (tarif visible sur sendas.me/pricing).

Définition d'une connexion facturée : Un compte OAuth (Gmail ou Office 365) actif dans une application SendAs.me. La quantité de l'abonnement Stripe est automatiquement synchronisée à chaque connexion ou déconnexion.

• 1 utilisateur Gmail connecté = 1 connexion
• 1 utilisateur Gmail + 1 Office 365 = 2 connexions
• La quantité Stripe est mise à jour en temps réel

Cycle de vie de l'abonnement

Inscription
    │
    ▼
[trialing] ──── CB ajoutée avant échéance ──► [active] ─── paiement mensuel ──► [active]
    │                                                              │
    │  Fin trial SANS CB                              invoice.payment_failed
    ▼                                                              ▼
[canceled] ◄──────────────────────────────────────── [past_due]
    │                                                    │
    │  CB ajoutée + POST /stripe/reactivate              │  CB mise à jour + POST /stripe/reactivate
    ▼                                                    ▼
[active]                                             [active]

États et accès

subscription_status	Envoi email	Description
trialing	✅	Période d'essai en cours
active	✅	Abonnement actif et à jour
past_due	❌	Paiement en échec — moyen de paiement à mettre à jour
unpaid	❌	Facture impayée
canceled	❌	Abonnement annulé (trial expiré sans CB, ou résiliation)

Fin de trial sans CB

Si aucun moyen de paiement n'est renseigné avant la fin du trial, l'abonnement est annulé immédiatement (canceled). L'envoi d'emails est alors bloqué sur les deux voies (SMTP et API). Pour réactiver, utilisez POST /stripe/reactivate après avoir ajouté une CB.

GET /stripe/status

Retourne le statut local de l'abonnement (depuis le cache, sans appel Stripe).

Requête :

GET /stripe/status
X-Api-Secret: votre_api_secret

Réponse 200 :

{
  "allowed": true,
  "status": "trialing",
  "show_banner": false
}

Champ	Description
allowed	true si l'envoi est autorisé (active ou trialing)
status	Statut Stripe local : trialing, active, past_due, canceled, null
show_banner	true si une bannière d'alerte doit être affichée dans le portail

GET /stripe/subscription

Retourne les détails complets de l'abonnement Stripe (appel Stripe live).

Requête :

GET /stripe/subscription
X-Api-Secret: votre_api_secret

Réponse 200 :

{
  "has_stripe": true,
  "subscription": {
    "status": "active",
    "stripe_subscription_id": "sub_1234567890",
    "current_period_end": "2025-02-01T00:00:00Z",
    "cancel_at_period_end": false,
    "trial_end": null
  }
}

POST /stripe/checkout-setup

Crée une session Stripe Checkout (mode setup) pour enregistrer ou mettre à jour un moyen de paiement. Utilisé lors de la première souscription ou après un blocage past_due/canceled.

Requête :

POST /stripe/checkout-setup
X-Api-Secret: votre_api_secret
Content-Type: application/json

Corps :

Champ	Type	Description
portal_url	string	URL de retour après la session Stripe (ex. https://app.sendas.me/billing)

{
  "portal_url": "https://app.sendas.me/billing"
}

Réponse 200 :

{
  "url": "https://checkout.stripe.com/pay/cs_live_..."
}

Redirigez l'utilisateur vers url. Après saisie de la CB, Stripe redirige vers portal_url?payment=updated.

Flux complet

POST /stripe/checkout-setup → saisie CB → retour ?payment=updated → appel POST /stripe/reactivate → accès rétabli.

POST /stripe/reactivate

Réactive l'abonnement après ajout d'un moyen de paiement. Appelé automatiquement par le portail au retour du checkout (?payment=updated).

Requête :

POST /stripe/reactivate
X-Api-Secret: votre_api_secret

Comportement :

• Si status == past_due ou unpaid : paie toutes les factures ouvertes → abonnement redevient active
• Si status == canceled : crée un nouvel abonnement avec paiement immédiat → active

Réponse 200 :

{
  "reactivated": true,
  "status": "active"
}

POST /stripe/cancel-subscription

Planifie l'annulation de l'abonnement en fin de période. L'accès reste actif jusqu'à la date d'échéance.

Requête :

POST /stripe/cancel-subscription
X-Api-Secret: votre_api_secret

Réponse 200 :

{
  "cancelled": true,
  "cancel_at_period_end": true,
  "current_period_end": "2025-02-01"
}

POST /stripe/portal

Génère un lien vers le Stripe Customer Portal (gestion de l'abonnement, factures, CB enregistrées). Disponible uniquement pour les abonnements active ou trialing.

Requête :

POST /stripe/portal
X-Api-Secret: votre_api_secret
Content-Type: application/json

Corps :

{
  "return_url": "https://app.sendas.me"
}

Réponse 200 :

{
  "url": "https://billing.stripe.com/session/..."
}

Webhooks Stripe reçus

Configurez l'URL https://api.sendas.me/stripe/webhook dans votre Dashboard Stripe avec les événements suivants :

Événement Stripe	Action locale
customer.subscription.created	Enregistrement de stripe_subscription_id, sync quantité
customer.subscription.updated	Mise à jour du statut local, sync quantité
customer.subscription.deleted	Statut → canceled, envoi bloqué
invoice.payment_failed	Statut → past_due, email d'alerte envoyé
invoice.payment_action_required	Statut → past_due, email avec lien de paiement
customer.subscription.trial_will_end	Email de rappel J-3

Webhook secret

Configurez STRIPE_WEBHOOK_SECRET dans le .env de la gateway pour valider les signatures Stripe. Sans ce secret, les webhooks sont acceptés sans vérification (non recommandé en production).