Connecter Sylius à un ERP, une application mobile ou un service logistique paraît simple tant que l’intégration ne fait que lire quelques produits. La difficulté arrive avec les effets métier : un prix dépend d’un canal, un panier change entre deux appels, une commande déclenche paiement et réservation, puis un timeout laisse le client sans savoir si l’action a réussi. Une API trop proche de la base expose alors des états que le commerce ne sait pas assumer.
Les premiers incidents sont souvent ambigus. Une variante existe, mais pas sur le canal demandé ; deux validations créent deux commandes ; un stock physique positif masque des unités déjà réservées ; une relance après coupure applique deux fois la même transition. Le support voit des réponses HTTP isolées, tandis que l’administration des ventes raisonne en panier, commande, paiement et expédition. Sans identifiant commun, la preuve se disperse entre plusieurs systèmes.
En pratique, une intégration API sur mesure doit protéger les invariants Sylius au lieu de permettre aux consommateurs de les contourner. Contre-intuitivement, exposer moins de ressources au départ donne souvent une interface plus utile : le contrat se concentre sur les décisions réellement consommées, leurs préconditions et leur résultat observable.
La démarche ci-dessous sépare lecture du catalogue, mutation du panier et cycle de commande. Elle précise autorité, idempotence, erreurs, événements, sécurité, tests et runbook. Le but est qu’une équipe de support puisse expliquer un dossier et choisir attendre, corriger, rejouer ou compenser sans écrire directement dans la base.
Tracer la frontière de l’API Sylius
Partir des capacités métier attendues
Le périmètre décrit des verbes : consulter une offre vendable, créer un panier, ajouter une variante, choisir une adresse, sélectionner une livraison, confirmer puis lire une commande. Il ne commence pas par la liste des tables ou des entités. Cette formulation révèle les validations et les effets qui doivent rester dans Sylius. Un consommateur peut demander une transition ; il ne doit pas fixer arbitrairement l’état final.
Chaque capacité nomme sa source faisant foi. Le PIM peut posséder la description enrichie, Sylius la disponibilité commerciale, l’ERP le stock physique et le PSP le paiement. L’API ne fusionne pas silencieusement ces autorités. Elle expose la valeur utile, sa date et son origine, puis définit le comportement lorsque les sources divergent.
Différencier lecture publique et administration
Le catalogue destiné à un front n’a pas besoin des champs internes de modération, de coût ou de configuration. L’administration possède une interface séparée, des scopes distincts et des preuves renforcées. Réutiliser un endpoint privilégié pour simplifier le développement augmente le risque d’exposition et rend les évolutions plus difficiles à versionner.
Le contrat conserve aussi les limites. Une première version peut refuser les promotions complexes, les commandes fractionnées ou certains retours. Ce refus documenté est préférable à une prise en charge partielle qui produit un état impossible. Le backlog d’extension part des cas réels et de leur coût, pas d’un objectif abstrait de couverture complète.
Exposer produits, variantes, canaux et prix
Préserver les dimensions qui changent la vente
Le produit porte une identité et des informations communes ; la variante porte le SKU et les options vendables. Le canal, la locale et la grille tarifaire déterminent ce que le client peut voir et à quel prix. Aplatir ces dimensions dans un objet unique crée rapidement des contradictions : une variante active en France peut être absente du B2B, ou posséder un autre prix et une autre disponibilité.
La réponse contient donc des identifiants stables, les options, l’état sur le canal demandé, le prix monétaire avec devise et la date de calcul. Un champ facultatif est réellement facultatif : son absence possède une signification et ne devient pas une chaîne vide. Les consommateurs testent explicitement cette absence au lieu de déduire une valeur par défaut trompeuse.
Versionner les attributs exposés
Un attribut interne n’acquiert pas une garantie publique parce qu’il figure dans le modèle. L’équipe classe les champs en identité, contrat stable, enrichissement et donnée privée. Une évolution d’un contrat stable nécessite compatibilité ou nouvelle version ; un enrichissement peut apparaître sans modifier la décision principale.
Exemple concret : renommer une option visible ne doit pas changer le code de variante utilisé par l’ERP. La fixture associe ancien libellé, nouveau libellé et même identifiant. Si un mapping aval dépend du texte, le test le révèle avant la bascule et permet de corriger le consommateur plutôt que de figer le vocabulaire métier.
Paginer un catalogue sans perdre les changements
Choisir un ordre reproductible
Une pagination par offset devient fragile lorsqu’un catalogue change pendant l’extraction. Une création en tête décale les pages ; une suppression peut faire sauter un élément. Pour une synchronisation, le curseur doit s’appuyer sur un ordre stable et documenté, par exemple une date de modification complétée par un identifiant. Le client conserve le curseur et la version de filtre avec son lot.
Le contrat indique ce qui se passe lorsqu’un curseur expire ou lorsque la politique de tri évolue. Le consommateur repart d’un point sûr et réconcilie les doublons grâce aux identifiants. Il ne poursuit pas avec un jeton devenu incompréhensible. La reprise privilégie l’exhaustivité vérifiable à l’illusion d’un flux sans répétition.
Rapprocher extraction et état final
À la fin d’un lot, une balance compare objets lus, objets appliqués, rejets et éléments absents de la destination. Elle ne se contente pas du nombre de réponses réussies. Un produit rejeté pour devise inconnue reste visible dans la file avec sa cause et son owner.
Une extraction complète périodique peut contrôler le flux incrémental sans devenir le mécanisme nominal. Elle détecte une notification perdue ou une règle de filtre erronée. Le coût du contrôle est connu, et son calendrier dépend du délai métier acceptable pour découvrir un écart.
Donner une identité durable au panier
Séparer le token d’accès de la clé métier
Le panier possède une identité que le front peut conserver entre les appels. Le token autorise l’accès, mais il ne doit pas être le seul identifiant présent dans les traces. Le support relie session, panier et éventuelle commande sans exposer le secret. Une rotation ou une fusion de session ne doit pas créer un nouveau panier par accident.
Les mutations portent une version attendue. Si deux onglets modifient le même panier, le second reçoit un conflit et relit l’état courant avant de proposer sa correction. Écraser silencieusement le premier changement produit des quantités ou adresses incompréhensibles. Le conflit devient un comportement prévu, pas une panne rare.
Recalculer les totaux dans le domaine
Le client envoie variante, quantité et choix, jamais un total faisant foi. Sylius applique prix, promotion, taxe et livraison dans le contexte du canal. La réponse renvoie les composantes et la version tarifaire qui ont conduit au montant. Une interface peut afficher le détail sans pouvoir forcer un prix.
Lorsque le catalogue change, le contrat dit si le panier est recalculé immédiatement ou lors de l’étape suivante. Un écart de prix exige une confirmation explicite avant commande. Le support retrouve l’ancien montant, le nouveau et la cause, au lieu de recevoir une plainte sans chronologie.
Protéger les transitions de commande
Faire de l’état une conséquence contrôlée
Une commande suit des transitions autorisées. L’API expose les actions disponibles et accepte une demande avec sa précondition, mais le domaine décide du nouvel état. Une commande expédiée ne revient pas vers « panier » parce qu’un message ancien arrive. La règle d’ordre s’appuie sur version et historique, pas sur l’heure du serveur consommateur.
Chaque transition produit un résultat terminal ou un refus actionnable. Une adresse incomplète, un stock insuffisant et un paiement non confirmé ne partagent pas le même code. Le client sait ce qui peut être corrigé, ce qui doit attendre et ce qui impose une intervention. Le runbook reprend exactement cette classification.
Conserver une commande lisible après la vente
Les lignes de commande gardent les informations nécessaires à l’historique, même si le produit change ensuite. Nom, SKU, prix, taxe et adresse ne doivent pas être reconstruits depuis le catalogue courant. Cette immutabilité fonctionnelle protège facture, support et analyse des incidents.
Les effets externes portent leurs propres identités : paiement, expédition, facture et retour. La commande les référence sans prétendre posséder tous leurs détails. Une équipe peut ainsi suivre l’effet manquant et relancer le bon système sans recréer la commande.
Séparer stock physique, réservé et disponible
Publier une promesse, pas un compteur brut
Dix unités physiques ne signifient pas dix unités vendables. Des paniers confirmés, un contrôle qualité ou une marge de sécurité réduisent la disponibilité. L’API nomme la mesure exposée, son dépôt, son canal et son instant de calcul. Le front n’interprète pas un nombre sans contexte.
Lorsqu’un panier réserve, confirme ou expire, l’événement de stock porte la cause et l’objet métier. Une balance rapproche mouvements et état courant. Si un mouvement manque, l’équipe corrige la chaîne à partir du premier écart ; elle ne modifie pas simplement le total pour faire disparaître l’alerte.
Décider l’autorité par type de stock
L’ERP peut posséder le physique et Sylius le réservé. La disponibilité résulte alors d’une formule versionnée. Le contrat décrit latence, mode dégradé et comportement en cas d’indisponibilité. Continuer à vendre avec une dernière valeur connue n’a pas le même risque selon le produit et la durée de coupure.
Le seuil de repli est validé avec la logistique. Au-delà, le canal réduit les quantités, bloque la vente ou passe en information différée selon la promesse. Ce choix métier doit être testé ; il ne peut pas rester une constante technique découverte pendant l’incident.
Rendre les écritures idempotentes
Dédupliquer l’intention métier
La clé d’idempotence représente l’effet attendu : valider ce panier pour cette version, créer ce paiement ou demander cette expédition. Elle n’est pas régénérée à chaque retry. Sylius conserve clé, empreinte de requête et résultat. Une même clé avec un contenu différent reçoit un conflit au lieu d’exécuter une nouvelle intention.
Après un timeout, le consommateur consulte le résultat associé avant de relancer. Si la commande existe, il reprend depuis elle ; si la requête n’a jamais été appliquée et que la précondition reste valide, il peut retenter. Cet ordre empêche le doublon tout en autorisant une vraie correction avec une nouvelle clé.
Borner la conservation et le rejeu
La durée de conservation couvre la fenêtre réelle de retry et de diagnostic. Elle est publiée dans le contrat. Une clé expirée ne garantit plus la déduplication ; le client relit alors l’objet métier et demande un arbitrage si l’effet demeure ambigu.
Le test de concurrence lance deux validations avec la même clé, puis deux clés différentes sur la même version. Il vérifie qu’un seul effet gagne et que les refus restent explicables. Le comportement doit être identique sur plusieurs workers et après redémarrage.
Utiliser événements et webhooks sans perdre la vérité
Notifier un changement, puis vérifier l’état utile
Un événement signale qu’une commande ou un produit a changé. Il contient identité, type, date, version de schéma et corrélation. Il n’a pas besoin de recopier tout l’objet. Le consommateur déduplique la notification et relit la ressource lorsque sa décision exige l’état courant.
Les événements peuvent arriver en retard ou dans le désordre. La version de l’objet empêche un message ancien d’écraser une donnée récente. Une file de quarantaine conserve les schémas inconnus et les erreurs permanentes. Le support peut rejouer après correction sans déplacer manuellement le dossier.
Éviter le double write non contrôlé
La commande et la publication de l’événement doivent partager une garantie. Une outbox ou un mécanisme équivalent évite le cas où la commande est validée mais la notification perdue. Le worker publie, marque et peut reprendre après coupure sans recréer l’effet métier.
Une réconciliation compare régulièrement les états terminaux Sylius aux accusés des consommateurs critiques. Elle révèle la perte silencieuse. Le seuil d’alerte porte sur l’âge du plus ancien écart et son impact, pas uniquement sur la taille instantanée de la file.
Limiter les droits par consommateur
Séparer lecture catalogue et mutation commerciale
Un front public, un ERP et un outil de support n’obtiennent pas les mêmes scopes. Le compte technique possède une identité dédiée, un propriétaire et une procédure de révocation indépendante d’un salarié. Les secrets ne figurent ni dans le code, ni dans les logs, ni dans un export de test.
La rotation accepte temporairement deux versions, vérifie l’usage de la nouvelle puis refuse l’ancienne. Le test couvre cette transition avant l’échéance. Une alerte suffisamment précoce laisse au propriétaire le temps d’agir sans coupure.
Filtrer les données par contexte
Le canal, la locale et le périmètre organisationnel sont contrôlés côté serveur. Le consommateur ne peut pas élargir sa visibilité en modifiant un paramètre. Les réponses et les logs évitent les données personnelles inutiles ; les fixtures de masque contiennent des champs sensibles attendus et inattendus.
Une action support privilégiée produit une trace avec acteur, motif et objet, mais jamais le secret utilisé. Les droits temporaires expirent. La revue des accès confirme que les comptes inactifs et les scopes devenus inutiles sont retirés.
Traiter les erreurs fréquentes et décider la reprise
Distinguer correction, attente et arbitrage
Une validation invalide appelle une correction de payload ; un conflit appelle une relecture ; une indisponibilité appelle un retry borné ; un état métier interdit appelle un arbitrage. L’erreur fournit code stable, message humain, champ concerné, corrélation et documentation. Elle ne dévoile pas la pile interne.
Le client ne relance pas toutes les réponses de la même manière. Les retries utilisent backoff et plafond, puis ouvrent une quarantaine. Un refus permanent ne doit pas saturer la file. Le runbook indique l’owner et la preuve nécessaire à la réouverture.
Ne pas confondre réception et effet final
Une réponse réussie peut confirmer l’acceptation d’une tâche sans confirmer la facture ou l’expédition. Le contrat expose le statut de traitement et la manière d’obtenir le résultat. Le support garde le dossier ouvert jusqu’à l’état terminal attendu.
Cas concret : la commande est créée, mais l’expédition échoue. Rejouer la création serait faux. L’opérateur repart de l’identifiant de commande, vérifie paiement et stock, puis relance uniquement l’étape logistique autorisée. La trace relie les deux tentatives.
Observer le parcours métier de bout en bout
Faire partir le diagnostic de la commande
Le tableau support recherche panier, commande, paiement ou expédition. Il affiche les transitions, appels externes, erreurs et reprises dans l’ordre. La corrélation traverse HTTP, workers et événements. Un technicien n’a pas à reconstruire la chronologie depuis plusieurs horodatages incompatibles.
Les métriques suivent délai de confirmation, commandes ambiguës, doublons bloqués, écarts de stock, âge de quarantaine et temps de reprise. Elles sont segmentées par canal et flux. Une alerte nomme le runbook et le périmètre affecté.
Mesurer la qualité de service métier
Un taux HTTP favorable peut masquer des commandes jamais expédiées. La mesure relie entrée acceptée, état terminal et délai. Elle distingue attente normale, rejet et perte. Le métier valide les seuils car il connaît le coût d’une confirmation tardive ou d’un stock surpromis.
La revue hebdomadaire traite les plus anciens écarts, les causes répétées et les exceptions proches de leur échéance. Elle finance une correction seulement si elle supprime une cause ou réduit un délai observé. Le monitoring reste ainsi un outil de décision.
Recetter doublons, concurrence et pannes
Contredire le parcours nominal
La recette crée un panier, modifie son catalogue entre deux étapes, lance deux validations, coupe la réponse après l’écriture et livre un événement en retard. Elle vérifie identité, conflit, idempotence et état final. Un test supplémentaire simule l’indisponibilité du stock puis le retour au nominal.
Les fixtures conservent canal, devise, variantes et versions. Le verdict compare Sylius, consommateur et preuve de support. Aucune correction directe en base n’est autorisée pendant l’exercice ; sinon la procédure de reprise reste inconnue.
Exercer le mode dégradé et le rollback
Le pilote limite une population et un type de commande. Le rollback arrête les nouvelles entrées, laisse finir les effets sûrs, restaure la configuration compatible et réconcilie les dossiers ouverts. Il ne supprime pas les commandes déjà engagées.
La sortie du pilote exige que le support retrouve un dossier, distingue effet appliqué et effet manquant, puis exécute la reprise sans aide du développeur auteur. Si ce geste échoue, l’extension est différée même si les tests unitaires sont verts.
Plan d’action avant la mise en production
Fermer d’abord le contrat et les autorités
L’équipe choisit un parcours, nomme les sources, dessine les états et liste les effets externes. Elle stabilise identifiants, version, erreurs et clé d’idempotence. Elle prépare ensuite les fixtures catalogue, panier, commande, stock et panne ambiguë. Ce contrat attribue les responsabilités, l’owner de chaque entrée, les dépendances et les seuils de refus avant le premier développement.
Le développement implémente lecture et mutations derrière des scopes distincts, branche outbox et corrélation, puis publie une documentation avec exemples nominaux et refus. Le support écrit le runbook en parallèle et refuse les actions irréversibles sans preuve. Chaque sortie conserve instrumentation, monitoring, traçabilité et règle de rollback afin que la queue puisse être reprise sans nouvelle commande.
Ouvrir un pilote puis élargir par capacité
Le premier lot porte un canal, une devise et des commandes simples. La recette joue concurrence, timeout, rupture de stock et événement retardé. Le monitoring suit états terminaux, quarantaines et temps de reprise. Le comité examine coût et incidents avant d’ajouter une nouvelle capacité.
L’extension ne combine pas promotions complexes, multi-expédition et nouveau PSP dans le même lot. Une dimension isolée conserve un diagnostic possible. Le rollback reste disponible jusqu’à ce que la balance ne montre plus d’écart critique.
- À faire d’abord : figer les identifiants et l’autorité de produit, prix, panier, commande et stock.
- À tester ensuite : conflit de version, double validation, timeout après écriture et événement désordonné.
- À différer : toute capacité dont l’état final ou le support ne sont pas définis.
- À refuser : les écritures directes qui court-circuitent transitions, trace ou idempotence.
Lectures complémentaires pour sécuriser les flux
Renforcer sécurité et architecture
L’architecture IAM appliquée aux API aide à séparer identités, scopes et rotation. Elle complète le contrat Sylius lorsque plusieurs consommateurs accèdent à des capacités différentes.
La comparaison REST, synchronisation et webhook permet de choisir lecture directe, extraction ou événement selon la fraîcheur et la capacité de reprise attendues.
Préparer provisioning et audit
Le dossier consacré au provisioning SCIM fournit des repères pour les comptes techniques et leur cycle de vie. L’objectif est d’éviter une intégration liée à une identité humaine durable.
Enfin, l’audit trail d’une API montre comment conserver une preuve utile sans journaliser secrets ni données inutiles. Cette discipline soutient les reprises de commande et les actions support.
Conclusion : publier un contrat exploitable
Une API Sylius fiable ne reproduit pas la base. Elle expose des capacités qui respectent produit, variante, canal, panier et commande. Elle nomme les autorités, conserve les identités et protège chaque transition contre concurrence, doublon et état ancien.
Le catalogue exige pagination reproductible et rapprochement. Le panier exige version et recalcul métier. La commande exige idempotence, états terminaux et effets externes traçables. Les événements accélèrent le flux, tandis que la réconciliation prouve qu’aucun dossier n’a disparu.
Le pilote doit chercher les réponses ambiguës, exercer le runbook et préserver un rollback réaliste. Une couverture fonctionnelle plus large n’a de valeur que si le support peut expliquer le résultat et reprendre au bon endroit sans mutation cachée.
Pour cadrer ces contrats, construire les flux et sécuriser leur exploitation, notre équipe peut vous accompagner dans votre projet d’intégration API, de la première ressource Sylius jusqu’au suivi en production.
