The codeArchitecture(in French)6 min read
Intégrations
Les services externes, à quoi sert chacun et quelle application a sa clé, puis le parcours d’un paiement Stripe jusqu’à l’ERP.
Not translated yet
Chaque service externe est branché seulement sur l’application qui en a besoin. Et il n’y a que l’application qui écrit qui a une clé d’écriture.
| Service | Pour | Application |
|---|---|---|
| Stripe | le paiement en ligne, les remboursements, les litiges | le site (sessions de paiement, clé restreinte) et l’ERP (webhook, remboursements) |
| Neon | la base Postgres | les deux, chacune avec son rôle |
| Vercel | l’hébergement, la tâche planifiée du matin, le pare-feu | les trois projets |
| Vercel Blob | les photos du catalogue (magasin public), les factures et devis archivés (magasin privé) | il n’y a que l’ERP qui écrit. Le site lit les photos par leur hôte public |
| Passerelle IA de Vercel, modèles Anthropic | Fisher | ERP |
| Resend | les e-mails transactionnels et les alertes | les deux |
| Upstash Redis | les limites de débit (connexion, Fisher, alertes) | les deux |
| Web Push | les notifications sur le téléphone du personnel | ERP |
| Géoplateforme de l’IGN | les suggestions d’adresses et de communes dans les formulaires | les deux |
| La Poste, API Suivi | la confirmation des livraisons par colis, que la veille relit chaque matin | ERP |
| Google Merchant Center | le flux des produits (flux-produits.xml) | site |
| Vercel Analytics | la mesure d’audience | site |
| Collecteur d’erreurs, compatible Sentry | les erreurs du serveur et du navigateur | les deux |
Quelques choix
Il n’y a que l’ERP qui confirme un paiement. Le site ouvre la session de paiement, puis l’ERP reçoit le webhook et marque la commande payée (plus bas).
Le collecteur d’erreurs n’a pas de SDK. C’est packages/infra/src/collector.ts qui envoie lui-même ses enveloppes au format de Sentry, avec un délai maximum, et qui masque les chemins où il y a une donnée personnelle. L’hôte que la CSP autorise est déduit du DSN. Du coup, si le collecteur est mal configuré, ça échoue et ça se voit tout de suite.
Les e-mails du domaine sont authentifiés par des enregistrements DNS. Des scripts les contrôlent et les appliquent (check-email-dns.mts, apply-email-dns.mts). Comme ça, les confirmations de commande n’arrivent pas dans les indésirables.
La passerelle IA plafonne ce que Fisher dépense chaque mois. Une fois le plafond atteint, Fisher s’arrête jusqu’au premier du mois et les formulaires se remplissent à nouveau à la main (Fisher).
À chaque passage, la veille prévient une sonde externe. Si la sonde ne reçoit pas ce signal, elle donne l’alerte (ERP).
Stripe
L’ERP et le site utilisent le même compte Stripe. L’ERP a une clé complète ou, de préférence, une clé restreinte à ses propres appels. Le site a une clé restreinte aux sessions de paiement et aux coupons. Ce que chaque clé autorise et ce que les applications vérifient elles-mêmes, c’est détaillé dans Stripe et Resend.
Le parcours d’un paiement
Le site prépare la commande et ouvre la session Stripe Checkout (Panier et paiement). Le client paie chez Stripe, et Stripe envoie l’événement à l’ERP (/api/webhooks/stripe). La figure reprend ce trajet dans l’ordre, avec ce que chaque application écrit.
Le site prépare la vente
Le client valide sa commande
La page envoie les lignes qu’elle a montrées, et le site les rapproche du catalogue une à une.
Client → Site
reconcileCartWithCatalogueLe site écrit la commande, en attente de paiement
C’est la seule commande qu’il a le droit d’écrire. Elle retient ses pièces suivies.
Site → Base
createPendingOrderLe site ouvre la session de paiement
Il utilise sa clé restreinte. L’échéance de la session suit ce que la commande retient.
Site → Stripe
openCheckoutSession
Le client paie
Le client paie chez Stripe
Sa carte ne passe pas par les applications.
Client → Stripe
Le client revient sur le site
Il arrive souvent avant le webhook. La page de confirmation relit la commande à intervalles de plus en plus longs.
Client → Site
RefreshWhilePending
L’ERP encaisse
Quelques secondes plus tard, parfois des heures. Stripe relivre pendant 3 jours.
Stripe annonce le paiement à l’ERP
L’ERP vérifie la signature, puis inscrit l’événement par son identifiant avant de le traiter.
Stripe → ERP
processStripeWebhookRequestL’ERP encaisse, en une transaction
La commande ne passe payée que si elle était en attente. L’encaissement s’écrit, le devis s’accepte et le stock se décompte.
ERP → Base
handleSessionPaidL’ERP périme le cache du site
Quand une pièce suivie a quitté le stock, sa fiche se refait à la visite suivante.
ERP → Site
expireStockCachesL’ERP facture et confirme
La facture est émise et archivée, puis la confirmation part par e-mail avec la facture. L’équipe est prévenue.
ERP → Client
ensureSaleInvoice
Un webhook traité une fois
Stripe peut livrer un événement en retard, deux fois, ou pas du tout du premier coup. Du coup, l’ERP le traite dans cet ordre (apps/erp/modules/payments/services/stripe-webhook.service.ts) :
- Il vérifie la signature avant de lire quoi que ce soit. Si la signature est refusée alors que l’événement a la forme d’un vrai, il envoie une alerte, une par quart d’heure au maximum. Ça veut dire que le secret n’est plus le même des deux côtés.
- Il compare le mode de l’événement et celui de la clé. Si la prod reçoit un événement de test, ou l’inverse, il l’ignore et le signale.
- Il inscrit l’événement avec son identifiant (
WebhookEvent) avant de le traiter. Si c’est un doublon déjà traité, il répond tout de suite. Si l’événement a été inscrit mais jamais terminé, il le traite à nouveau. - Il lance le traitement qui correspond au type d’événement.
- Quand le travail est fini, il marque l’événement comme traité.
Si un traitement échoue de façon passagère, si une alerte n’a pas pu partir ou si l’événement n’a pas pu être marqué, l’ERP répond par une erreur. Stripe renvoie alors l’événement plus tard. L’inscription évite de refaire un événement déjà marqué. Par contre, un événement inscrit puis interrompu est traité à nouveau. Ce qui l’empêche de compter deux fois, ce sont les écritures conditionnelles de chaque traitement : une commande ne passe payée que si elle était en attente (Un ordre dont on ne sait pas s’il est parti).
Stripe ne renvoie un événement que pendant trois jours. Après (endpoint en panne, secret de signature qui n’est plus le même, traitement qui échoue jusqu’au bout), l’ERP perdrait l’événement alors que le client a payé. Du coup, chaque matin, la veille demande à Stripe les événements abonnés qu’il n’a pas réussi à livrer (delivery_success: false, Stripe les garde trente jours). Elle les fait passer par les étapes 2 à 5, du plus ancien au plus récent (stripe-event-recovery.service.ts#recoverUndeliveredStripeEvents). Comme elle les lit par l’API avec la clé du compte, il n’y a pas de signature à vérifier. Et l’inscription évite le doublon si Stripe renvoie aussi l’événement. Une session de paiement est relue à la version d’API épinglée, parce qu’un événement listé garde la version qu’avait le compte le jour où il a été créé.
L’ERP traite les événements d’une session de paiement (réussie, réussie après coup, expirée, échouée), d’un remboursement (créé, mis à jour, échoué) et d’un litige (ouvert, mis à jour, clos).
Rembourser, contester
Un remboursement part de l’ERP en attente. C’est le webhook de Stripe qui le confirme (webhook-refund.service.ts#handleRefundEvent), et l’avoir est émis à ce moment-là seulement (Facturation). Si l’événement s’est perdu, l’équipe relit le remboursement chez Stripe depuis la commande (stripe-refund.service.ts#reconcileStripeRefund). Un remboursement refusé ou annulé n’a pas fait sortir d’argent, donc il ne compte pas dans la caisse. Quand la banque d’un client ouvre un litige, il arrive par le webhook, le personnel reçoit une notification sur son téléphone et le litige se suit sur la commande. Fisher peut préparer un brouillon de réponse (dispute-response-draft.service.ts).
Vérifier la configuration
check-stripe-endpoint.mts (ERP) vérifie que l’adresse du webhook, la version de l’API et les événements abonnés sont bien ceux que le code attend. stripe-smoke.mts (site) ouvre une session avec les totaux que le site calcule, en mode test seulement.