Skip to Content
Meubles Morinière

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

This page is shown in its original French. Code excerpts, tests and figures read the same in either language.

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.

ServicePourApplication
Stripele paiement en ligne, les remboursements, les litigesle site (sessions de paiement, clé restreinte) et l’ERP (webhook, remboursements)
Neonla base Postgresles deux, chacune avec son rôle
Vercell’hébergement, la tâche planifiée du matin, le pare-feules trois projets
Vercel Blobles 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 AnthropicFisherERP
Resendles e-mails transactionnels et les alertesles deux
Upstash Redisles limites de débit (connexion, Fisher, alertes)les deux
Web Pushles notifications sur le téléphone du personnelERP
Géoplateforme de l’IGNles suggestions d’adresses et de communes dans les formulairesles deux
La Poste, API Suivila confirmation des livraisons par colis, que la veille relit chaque matinERP
Google Merchant Centerle flux des produits (flux-produits.xml)site
Vercel Analyticsla mesure d’audiencesite
Collecteur d’erreurs, compatible Sentryles erreurs du serveur et du navigateurles 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

  1. 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 → SitereconcileCartWithCatalogue

  2. Le 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 → BasecreatePendingOrder

  3. Le site ouvre la session de paiement

    Il utilise sa clé restreinte. L’échéance de la session suit ce que la commande retient.

    Site → StripeopenCheckoutSession

Le client paie

  1. Le client paie chez Stripe

    Sa carte ne passe pas par les applications.

    Client → Stripe

  2. 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 → SiteRefreshWhilePending

L’ERP encaisse

Quelques secondes plus tard, parfois des heures. Stripe relivre pendant 3 jours.

  1. 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 → ERPprocessStripeWebhookRequest

  2. L’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 → BasehandleSessionPaid

  3. L’ERP périme le cache du site

    Quand une pièce suivie a quitté le stock, sa fiche se refait à la visite suivante.

    ERP → SiteexpireStockCaches

  4. L’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 → ClientensureSaleInvoice

Les fonctions nommées sont vérifiées dans le dépôt à chaque build de cette documentation, et le délai de relivraison de Stripe y est lu (packages/domain/src/checkout-session.ts).

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) :

  1. 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.
  2. 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.
  3. 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.
  4. Il lance le traitement qui correspond au type d’événement.
  5. 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.

On this page