Système B2B professionnel pour Magento 2 Open Source
- Compatibilité
- 2.4.9, 2.4.8, 2.4.7
- Hyva Theme
- Hyva Theme Redy
Description / Système B2B professionnel pour Magento 2 Open Source
MAGENTO 2 · MAGENTO OPEN SOURCE · ENTREPRISES · COMMERCE B2B
Réunissez les ventes B2B et B2C dans une seule installation Magento.
Kowal B2B Suite enrichit Magento Open Source avec les entreprises, la vérification des numéros de TVA intracommunautaire dans VIES, des conditions commerciales individuelles, les listes d’achat, les offres RFQ, le crédit client, les approbations, les documents et les intégrations.
Proposez à vos clients professionnels un portail en libre-service et gérez le travail des commerciaux dans l’administration Magento.
17 modules et un thème de base · REST et GraphQL · Adaptateur de compte Hyvä
COMMENT CELA FONCTIONNE EN PRATIQUE
01 · Définissez votre modèle de vente
Configurez les entreprises, canaux, prix et sources de données.
02 · Configurez le processus B2B
Affectez les rôles, les accès au catalogue, les conditions et les approbations.
03 · Connectez les systèmes et déployez
Choisissez les adaptateurs et vérifiez les scénarios complets.
Toutes les fonctionnalités de Kowal B2B Suite
De l’inscription d’un client professionnel et de la définition d’un prix aux offres, commandes, documents et échanges de données. Choisissez les fonctionnalités à activer selon les règles commerciales de votre entreprise.
Entreprises et cycle de vie du client
Gérez les fiches des entreprises avec leur nom, identifiant fiscal, identifiant externe et commercial responsable.
- Inscription et approbation des entreprises, activation, blocage ou rejet.
- Statuts : en attente, active, inactive, bloquée et rejetée.
- Liens avec les comptes clients Magento, les groupes de clients et les canaux de vente.
- Historique des modifications des entreprises, utilisateurs, rôles, adresses et contacts.
Utilisateurs, rôles, adresses et contacts
Chaque entreprise peut avoir plusieurs acheteurs et ses propres rôles avec des autorisations définies.
- Affectation et désactivation des utilisateurs, modification de leurs rôles.
- Autorisations distinctes pour passer des commandes, consulter les commandes de l’entreprise, les demandes de devis, les documents, les utilisateurs et les adresses.
- Adresses de facturation et de livraison, valeurs par défaut par website et adresses communes à l’entreprise.
- Contacts de l’entreprise, dont un contact principal ; leur modification dépend des autorisations.
- Les informations et l’identifiant fiscal de l’entreprise restent distincts des données d’adresse personnelles de l’acheteur.
Vérification des numéros de TVA intracommunautaire dans VIES
Vérifiez les numéros de TVA intracommunautaire avec leur préfixe pays directement depuis la fiche de l’entreprise B2B dans l’administration Magento. Le bouton « Vérifier dans VIES » lance la vérification et affiche le résultat à côté du champ de l’identifiant fiscal.
- Numéros de TVA de l’UE avec code pays, par exemple
PL1234567890; la vérification couvre les pays reconnus par Magento comme membres de l’UE. - Normalisation de la saisie : les espaces, points et tirets sont ignorés, et les lettres sont converties en majuscules avant la vérification.
- Prise en charge du préfixe grec EL par correspondance avec le code pays GR utilisé par Magento.
- Contrôle du format et du pays avant l’envoi de la requête à VIES, avec un message si les données doivent être corrigées.
- Résultats distincts : numéro valide dans VIES, non valide dans VIES, données saisies incorrectes ou vérification indisponible.
Un administrateur autorisé lance la vérification d’une entreprise et d’un numéro de TVA préalablement enregistrés, dans le contexte d’un canal B2B actif attribué à cette entreprise. Un numéro modifié doit d’abord être enregistré.
Résultats VIES enregistrés et actualité des données
Le résultat est immédiatement enregistré sur la fiche de l’entreprise, avec la date et l’heure de la vérification ainsi que le numéro de TVA vérifié. Il devient ainsi plus facile d’identifier les données à vérifier de nouveau.
- Colonne de statut VIES dans la liste des entreprises avec filtres : non vérifié, valide, non valide, format incorrect ou VIES indisponible.
- Colonne de date de vérification avec filtrage par plage de dates.
- Réinitialisation après modification du numéro de TVA : l’enregistrement d’un autre numéro rétablit le statut « non vérifié » et efface la date précédente ainsi que le numéro vérifié enregistré.
- Conservation du résultat lorsque seule la présentation change, par exemple les espaces, séparateurs ou majuscules et minuscules, ainsi que lors de la modification d’autres données de l’entreprise.
- Association du résultat au bon numéro : si le numéro de TVA change pendant la vérification, le module refuse d’enregistrer le résultat de l’ancien numéro et demande une nouvelle tentative.
Lorsque le service ne peut pas vérifier le numéro, l’administrateur reçoit un message distinct indiquant l’indisponibilité de la vérification et l’invitant à réessayer plus tard. Une erreur de connexion est distinguée d’un résultat VIES négatif.
B2B et B2C dans une seule installation
Activez le B2B pour les websites Magento sélectionnés. Toutes les vues magasin de ce website utilisent le mode B2B, tandis que les autres websites peuvent servir les clients B2C.
- Une entreprise peut être affectée à plusieurs websites B2B actifs.
- L’activité de la relation et le groupe de clients de l’entreprise se configurent séparément pour chaque website.
- Prix, catalogues, documents, limites de crédit, devis et intégrations fonctionnent dans le contexte de l’entreprise et du canal concernés.
- L’ajout d’une affectation à un website ne déplace pas les comptes clients Magento et ne modifie pas automatiquement leurs groupes.
Contrôle d’accès et portail B2B privé
Choisissez parmi trois modèles : boutique publique, boutique nécessitant une connexion ou catalogue public avec restrictions pour les visiteurs non connectés.
- Connexion obligatoire avec exceptions pour certaines actions ou certains chemins d’URL.
- Retour à la page initialement demandée après la connexion.
- Réglages indépendants pour masquer les prix et interdire les achats aux visiteurs non connectés.
- Messages personnalisés et lien de connexion à la place du prix ou du bouton d’achat.
- Masquage des commandes standard d’ajout au panier et blocage de l’ajout côté serveur dans la boutique classique.
- Inscription des clients laissée ouverte ou désactivée.
La protection de la boutique standard doit être mise en œuvre séparément dans une API publique personnalisée ou une interface headless.
Migration des clients existants vers des entreprises
L’action groupée Assign or Create Company permet d’organiser la base de clients Magento existante.
- Filtre des clients affectés ou non à une entreprise, également pour les exports et les actions groupées.
- Rapprochement avec une entreprise par identifiant fiscal normalisé ou création d’une entreprise ; les comptes sans identifiant fiscal reçoivent des entreprises distinctes.
- Copie des adresses par défaut et du contact principal vers une entreprise nouvellement créée.
- Affectation d’un rôle d’acheteur avec les autorisations B2B de base.
- Conservation des groupes de clients existants, exclusion des comptes déjà affectés et rapport des résultats et erreurs de migration.
Administration et opérations groupées
Gérez les entreprises et leurs données associées depuis un menu B2B unique. Les fiches clients Magento disposent d’un champ d’affectation à une entreprise.
- Listes et formulaires pour les entreprises, utilisateurs, rôles, adresses, contacts et journaux d’audit.
- Modification groupée du statut, du commercial responsable, de l’affectation à un website, de l’activité de la relation et du groupe de clients de l’entreprise.
- Création ou mise à jour groupée des rôles, avec possibilité d’affecter un rôle à tous les utilisateurs actifs des entreprises sélectionnées.
- Transaction distincte et entrées d’audit pour chaque entreprise traitée.
- Autorisations des administrateurs Magento pour limiter l’accès à chaque opération.
Tarifs, prix contractuels et paliers de quantité
Définissez les prix par entreprise, website, SKU, devise et quantité. Les prix contractuels sont prioritaires, suivis du tarif B2B affecté, puis des prix du catalogue Magento.
- Plusieurs tarifs et affectations aux entreprises avec priorités.
- Prix contractuels et lignes tarifaires avec paliers de quantité et champs de période de validité.
- Application des prix contractuels et des tarifs dans le panier.
- Indexation des prix, audit des modifications et outil Explain Price pour identifier la source du prix retenu.
- Import et export CSV des lignes tarifaires et accès aux prix via l’API.
Les suggestions de prix RFQ tiennent compte du magasin, du client, de la quantité, de la devise et des taxes ; lorsque le prix du catalogue est utilisé, elles incluent aussi les promotions Magento applicables.
Un catalogue propre à chaque entreprise
Contrôlez la visibilité des produits avec des règles pour une entreprise ou pour tout un website.
- Règles visant des produits, des catégories ou l’ensemble du catalogue.
- Actions d’autorisation et de refus ; le refus est prioritaire.
- Index de visibilité et filtrage des listes de produits dans la boutique.
- Vérification de l’accès aux SKU masqués et nouvelle validation dans les listes d’achat, les demandes de devis et le passage en caisse.
- Consultation de la visibilité des produits pour une entreprise et reconstruction de l’index via l’API.
L’absence de règle correspondante ne masque pas à elle seule un produit. L’offre reste fondée sur le catalogue natif de Magento.
Commandes rapides et listes d’achat
Les clients créent des listes d’achat nommées et ajoutent plusieurs articles par SKU sans rechercher chaque produit individuellement.
- Collage de 100 lignes maximum à la fois : SKU, quantité et note facultative, par exemple
SKU-001;10;Livrer à l’entrepôt. - Listes avec indicateur de liste par défaut, articles, dernier prix B2B et devise.
- Validation du SKU, du statut du produit, de son affectation au website, de sa visibilité pour l’entreprise, d’une quantité positive et du prix B2B.
- Ajout d’une liste au panier après une nouvelle validation.
- Les administrateurs peuvent consulter les listes, supprimer des articles et exporter les lignes au format CSV.
- Debug SKU et écrans de journaux d’import et d’erreurs par ligne pour les processus qui alimentent ces données.
RFQ : demandes depuis le compte client
Un acheteur autorisé peut envoyer une demande de devis avec un titre, une note et entre 1 et 200 articles.
- Recherche par SKU, nom du produit et attributs existants EAN, EAN13, GTIN ou code-barres.
- Suggestions limitées aux produits simples et virtuels actifs et visibles.
- Quantité, prix unitaire net souhaité facultatif et commentaire par article.
- Aperçu des prix hors taxes et toutes taxes comprises ; les changements de quantité actualisent les suggestions en conservant les prix saisis manuellement.
- Prix gérés dans la devise du magasin et selon sa configuration fiscale.
- Validation de la demande entière : un article invalide annule l’enregistrement et le formulaire conserve les données pour correction.
RFQ : préparation et négociation des offres
Les commerciaux peuvent aussi créer des demandes de devis dans l’administration Magento en sélectionnant le website, la Store View, l’entreprise, le client, la devise et les produits.
- Enregistrement d’un brouillon ou d’une demande soumise ; recherche de produits avec suggestions de prix hors taxes et toutes taxes comprises.
- Prix demandés et proposés, total négocié, date d’expiration, commentaires et notes commerciales.
- Statuts du processus, historique des décisions et protection contre l’acceptation d’une offre expirée.
- Envoi de l’offre préparée par e-mail avec des liens vers ses détails et son PDF nécessitant une connexion.
- Acceptation ou refus par le client, motif de refus facultatif et décisions de l’administrateur.
- PDF distincts pour le client et l’administrateur ; les notes internes et l’historique administratif restent dans la version d’administration.
De l’offre acceptée à la commande
Transférez les articles et les prix convenus d’une offre acceptée vers le processus d’achat Magento.
- Convert to Cart crée un panier client avec les articles et les prix de l’offre.
- Un client autorisé à commander poursuit le passage en caisse standard pour choisir l’adresse, la livraison et le paiement.
- Create Order dans l’administration crée automatiquement une commande lorsque les adresses requises et des modes de paiement et de livraison non ambigus sont disponibles.
- Si certaines conditions doivent encore être choisies, l’offre est chargée dans le formulaire natif de création de commande de l’administration Magento.
- Conservation du contexte Store View de l’offre et de son lien avec le panier ou la commande préparés.
Passage en caisse, paiement, livraison et numéros PO
Ajoutez des règles B2B au processus de commande standard de Magento.
- Vérification de l’entreprise active, de l’affectation au website et du droit de l’utilisateur à passer commande.
- Validation du catalogue et de la disponibilité des prix B2B lors de la commande.
- Règles des modes de paiement et de livraison autorisés par entreprise et website.
- Adresses de facturation et de livraison de l’entreprise avec valeurs par défaut propres à chaque canal.
- Numéro de bon de commande du client (PO) et commentaire de commande.
- Enregistrement de l’entreprise, de l’acheteur et des statuts de crédit, d’approbation et d’export dans le contexte B2B de la commande.
Limites de crédit client et délais de paiement
Suivez la limite de crédit, son utilisation et le montant disponible séparément pour chaque entreprise, website et devise.
- Délais de paiement, activation ou blocage de la limite et possibilité d’autoriser son dépassement.
- Sélection des modes de paiement utilisant le crédit de l’entreprise ; les autres fonctionnent sans limite configurée.
- Réservation atomique avant la commande, rattachée à la commande enregistrée.
- Libération de la réservation après un échec sans création de commande, un paiement intégral, une annulation ou une clôture.
- Ajustements manuels de l’encours, détail de l’exposition et historique des événements.
- Rapprochement par cron après l’interruption d’un processus ou une erreur temporaire.
Un paiement partiel maintient la totalité de la réservation jusqu’au règlement intégral ou à l’annulation.
Approbation des commandes et contrôle du traitement
Définissez les règles d’approbation par entreprise, website, devise et seuil de montant de commande. La priorité et le seuil déterminent la règle applicable si plusieurs correspondent.
- Affectation d’utilisateurs actifs de l’entreprise comme approbateurs.
- Création automatique d’une demande en attente pour une commande correspondant à une règle.
- Approbation, refus ou annulation avec commentaire et piste d’audit.
- Marquage de l’export comme bloqué et suspension de la commande lorsque son état le permet.
- L’approbation met à jour le statut B2B et lève la suspension ; le refus ou l’annulation laisse l’export bloqué.
Le processus inclus clôture une demande en attente par une seule décision. Une approbation en plusieurs étapes nécessite une extension supplémentaire et l’intégration doit respecter le statut de blocage de l’export.
Documents commerciaux dans le portail client
Mettez les factures, avoirs, bons de livraison et confirmations de commande à la disposition de l’entreprise concernée.
- Création automatique de documents à partir des commandes, factures, expéditions et avoirs de Magento Sales.
- Configuration de la source, du statut initial et de la génération de chaque type de document ; prise en charge d’un modèle hybride Magento + API.
- Envoi manuel de PDF dans l’administration, métadonnées, dates, montants, devises et liens vers les entités Magento.
- Partage des fichiers originaux d’un système externe sans modification de leur contenu.
- Téléchargements contrôlés selon l’entreprise, le website, les autorisations et le statut du document.
- Aperçu de l’accès client, des fichiers et des journaux de synchronisation dans l’administration.
PDF personnalisables et versions linguistiques
Un générateur PDF commun prend en charge les documents commerciaux et les offres RFQ.
- Modification des modèles HTML/CSS dans l’administration et aperçu avec des données d’exemple.
- Modèles distincts par type de document, website et destinataire ; un modèle local est prioritaire sur un modèle global.
- Titres personnalisés pour les confirmations, factures, avoirs, bons de livraison et offres commerciales.
- Logo, informations du vendeur et de l’acheteur, identifiants fiscaux, adresses, articles, totaux, informations et instructions de paiement et de livraison dans les documents Sales.
- Version RFQ destinée au client séparée des données internes de l’administrateur.
- Libellés traduits selon la langue du magasin ; les dictionnaires comprennent le polonais et de nombreuses autres langues européennes.
Les modifications de modèles s’appliquent aux nouveaux PDF générés. Les fichiers déjà enregistrés doivent être régénérés.
Compte entreprise et adaptateur Hyvä Themes
Le portail entreprise rassemble les informations de l’entreprise, les adresses, contacts, utilisateurs, documents, crédit, listes d’achat et demandes de devis.
- Adresses de l’entreprise et cinq dernières commandes dans le tableau de bord natif du compte.
- Consultation des commandes personnelles ou de l’entreprise selon les autorisations, liens PDF protégés et renouvellement de commande par l’acheteur d’origine autorisé.
- Six réglages de visibilité des liens natifs : adresses, commandes, téléchargements, paiements enregistrés, avis et newsletter.
- Adaptateur Hyvä Themes facultatif inclus avec tableaux, formulaires et navigation du compte adaptés aux écrans.
- Activation par Store View ; désactivé par défaut et actif uniquement avec Hyvä et B2B.
L’adaptateur couvre le compte client. Hyvä Checkout, le panier et le mini-panier nécessitent un périmètre d’intégration distinct. Les réglages du menu contrôlent la visibilité des liens ; les autorisations sont vérifiées indépendamment.
Import et export CSV des données B2B
Transférez et mettez à jour les données au moyen de profils affectés à un website donné.
- Entreprises, affectations d’utilisateurs et rôles avec autorisations.
- Définitions de tarifs, prix contractuels et règles de visibilité du catalogue.
- Métadonnées des documents, liens vers les fichiers de documents existants et limites de crédit client.
- Envoi de CSV, validation et mode dry-run pour vérifier un import avant son enregistrement.
- Historique des tâches, journaux d’erreurs par ligne et téléchargement des rapports d’erreurs et fichiers d’export.
- Import et export distincts des lignes tarifaires dans Pricing.
L’import des affectations d’utilisateurs utilise les comptes Magento existants ; l’import des fichiers de documents référence des fichiers déjà présents dans un emplacement autorisé.
API REST et GraphQL
Exposez les processus B2B aux intégrations ou aux interfaces personnalisées via l’API.
- REST : configuration des websites, entreprises et utilisateurs, produits, disponibilité MSI, prix, catalogue, listes d’achat, RFQ, documents, limites, approbations, contexte de commande, import/export et intégrations.
- Opérations groupées sur les entreprises et clé d’idempotence pour leur création.
- Rapports produits, y compris les traductions manquantes et les données de stock.
- Requêtes GraphQL sur les données de l’entreprise, prix, listes, offres, documents, crédit, approbations et tâches d’intégration.
- Mutations GraphQL pour les listes d’achat, les processus RFQ et la publication, le traitement et la relance des tâches d’intégration.
L’accès dépend des autorisations et du contexte de l’opération. REST et GraphQL exposent des contrats définis ; leurs ensembles d’opérations ne sont pas identiques.
Intégrations ERP, PIM, WMS et CRM
Le package fournit une infrastructure pour connecter Magento aux systèmes de votre entreprise.
- Profils par website, type de système, sens d’échange et adaptateur.
- Correspondances entre identifiants locaux et externes.
- Création de tâches de synchronisation avec heure planifiée, données d’entrée et clé d’idempotence.
- Statuts de traitement, résultats, nombre de tentatives, journaux et erreurs.
- Relance manuelle de la même tâche et consultation des tâches nécessitant une intervention dans la Dead Letter Queue.
La connexion d’un ERP, PIM, WMS, CRM, EDI ou système d’approvisionnement précis nécessite un adaptateur et un processus de traitement en fonctionnement. La mise en œuvre définit les sources des entreprises, prix, stocks, commandes et documents.
Tableau de bord, rapports et diagnostics
Le tableau de bord B2B présente le nombre et les statuts des entreprises, les utilisateurs actifs, les tarifs, les règles de catalogue, les erreurs et les modifications récentes.
- Rapports sur les entreprises sans website actif, utilisateurs ou tarif, et sur les clients sans entreprise.
- Rapports sur les prix indexés, les données de sources MSI et les traductions de noms de produits manquants.
- Documents sans fichiers, erreurs d’import et d’intégration, commandes en attente d’approbation ou bloquées à l’export.
- Filtrage des rapports par website, aperçu des enregistrements et export CSV.
- État du système, audits des entreprises et des décisions, journaux de crédit et de synchronisation, outils Explain Price et Debug SKU.
- Configuration des diagnostics B2B et de la durée de conservation des journaux.
Un package, une architecture modulaire
Le package kowal/metapackage-b2b-suite contient 17 modules Magento et le thème de base frontend/Kowal/b2b. Il comprend Base, Access Control, Company, Admin UI, Pricing, Catalog Permissions, Quick Order, Quote, Checkout, Credit Limit, Approval, Document, Import/Export, Integration, REST API, GraphQL et l’adaptateur Hyvä facultatif.
L’installation s’effectue avec un seul package Composer. Après l’octroi de l’accès au dépôt, le déploiement comprend l’activation des modules requis, la mise à jour de la base de données Magento, la configuration des websites et des entreprises, puis la compilation, la publication des ressources et le nettoyage des caches selon le mode de déploiement de la boutique.
Prérequis et périmètre de mise en œuvre
Le projet cible Magento Open Source 2.4.9 et le package nécessite PHP ^8.3. Il utilise le catalogue, le panier, le passage en caisse et MSI natifs de Magento, ainsi que le générateur mPDF.
La boutique Magento classique et un adaptateur de compte Hyvä Themes facultatif sont disponibles. Le thème B2B de base constitue un point de départ pour personnaliser l’apparence du portail.
Le périmètre dépend de la version de la boutique, du thème, des paiements, de la livraison et des systèmes externes. La compatibilité et le parcours d’achat complet doivent être vérifiés dans l’installation cible.
Planifiez une mise en œuvre B2B adaptée à votre entreprise
Vous souhaitez adapter le module à votre boutique ? Renseignez-vous sur la mise en œuvre de Kowal B2B Suite et discutez de la configuration ou d’extensions supplémentaires.
Avant de planifier le projet, découvrez comment réduire le traitement manuel des ventes B2B dans Magento 2 et le coût réel du traitement manuel d’une commande B2B (articles en polonais).
Caractéristiques
| Hyva Theme | Hyva Theme Redy |
|---|---|
| Compatibilité avec le modèle | Hyvä, Luma / Blank, KOWAL |
Configuration de l'intégration
Kowal B2B API — documentation REST complète
Version du contrat :
V1· Source de vérité :Kowal_B2BApi/etc/webapi.xml· Destinataires : administrateurs de boutiques, partenaires de déploiement et équipes intégrant ERP, PIM, WMS ou système d’achat.
1. Objet et limites de l’API
Kowal B2B API expose les données et processus B2B fonctionnant dans Magento 2 : entreprises, catalogue et prix personnalisés, achats rapides, documents, limite de crédit, validations, RFQ et files d’intégration. Il s’agit d’une REST API destinée aux intégrations système ; elle ne remplace pas les endpoints Magento standard pour le catalogue, le panier, le checkout et le compte client.
Ce document décrit uniquement les endpoints actuellement exposés par le module. Il ne promet pas d’opérations que le contrat V1 ne fournit pas, par exemple la création de commande via REST, le CRUD des grilles tarifaires ou la modification de la configuration website.
2. Obtention de l’accès et règles de coopération
2.1. Processus de lancement de l’intégration
- L’intégrateur transmet à l’administrateur de la boutique l’objectif de l’intégration, l’environnement test/production, le système source, le périmètre des données et la liste des zones API requises.
- L’administrateur crée ou configure l’intégration Magento, lui attribue les droits ACL minimaux et transmet par un canal sécurisé :
baseUrl, le jeton,websiteId,companyIdlorsque applicable, la devise et les données de test. - L’intégrateur effectue le test
GET /V1/kowal-b2b/websites/:websiteId/config, puis les tests fonctionnels sur l’environnement de test. - Avant la production, les deux parties conviennent du calendrier de synchronisation, du volume maximal des données, des retry, du propriétaire des données et du mode de signalement des erreurs.
- Les jetons sont stockés uniquement dans un coffre-fort à secrets ; l’administrateur les fait tourner ou les révoque en cas de changement de prestataire, d’utilisateur ou de périmètre d’intégration.
2.2. Responsabilités
| Partie | Responsabilité |
|---|---|
| Administrateur de la boutique | Configuration du website B2B, de l’entreprise et de la relation entreprise-website, du jeton et des ACL ; transmission des données de test ; décision d’accès aux données. |
| Intégrateur | Stockage sécurisé du jeton, utilisation correcte du contexte websiteId/companyId, validation des données, gestion des erreurs et des nouvelles tentatives, non-divulgation des données d’autres entreprises. |
| Propriétaire du processus métier | Définition de la source de vérité pour les prix, documents, RFQ, limites et statuts de synchronisation. |
Il ne faut pas utiliser de jeton administrateur dans une application cliente ni partager un seul jeton entre systèmes indépendants. Chaque intégration doit disposer de son propre jeton et uniquement des ACL nécessaires.
2.3. Droits
Magento vérifie le jeton Bearer ainsi que les ACL attribuées à l’utilisateur administratif ou à l’intégration. Les endpoints B2B nécessitent l’un des groupes de droits suivants :
| ACL | Périmètre |
|---|---|
config | Websites et feature flags |
companies, company_save, company_users, batch | Entreprises, leurs utilisateurs et import groupé d’entreprises |
products, prices, catalog_permissions | Catalogue, disponibilité, prix et visibilité |
import_export, quick_order, documents | Profils d’import/export, listes d’achat et documents |
credit_limits, approvals, orders, quotes | Limite, workflow de validation, contexte des commandes et RFQ |
system_integrations | Profils, mappings et jobs d’intégration |
Le périmètre doit découler de l’objectif de l’intégration. Exemple : un système d’achat a généralement besoin de products, prices, catalog_permissions, quick_order et quotes ; un ERP gérant les documents — documents et, s’il est propriétaire de la synchronisation, system_integrations.
3. Conventions techniques
Adresse, en-têtes et paramètres
L’adresse de base a la forme https://b2b.example.com/rest/V1. Tous les chemins indiqués plus loin dans le document sont fournis à partir de /V1 ; l’adresse complète de l’endpoint est BASE_URL + chemin.
Authorization: Bearer Accept: application/jsonContent-Type: application/json L’API utilise JSON. Les noms dans l’URL sont en camelCase (websiteId, companyId) et les champs JSON correspondent aux noms des paramètres des contrats Magento. :companyId, :quoteId, :sku, etc. sont des paramètres de chemin. Dans les exemples, ? indique un paramètre optionnel.
websiteId est requis pour les opérations dépendantes du canal de vente. Il doit pointer vers un website existant avec B2B activé. companyId désigne l’entreprise, qui doit avoir une relation active avec ce website lorsque l’opération s’exécute dans son contexte. L’API ne choisit pas de website ni d’entreprise par défaut.
Request body et idempotence
Magento sérialise l’objet DTO sous le nom du paramètre de la méthode : la plupart des écritures acceptent {'request': {...}} ; la création d’entreprise utilise {'company': {...}} ; le batch d’entreprises — {'companies': [...]}. Les endpoints avec des arguments simples acceptent les champs sans wrapper, par exemple {'websiteId': 1, 'currency': 'PLN', 'items': [...]}.
L’en-tête Idempotency-Key (128 caractères max.) est actuellement pris en charge par POST /companies : une nouvelle tentative avec la même clé renverra l’entreprise créée précédemment. Pour un job d’intégration, utilisez le champ request.idempotencyKey. Ne supposez pas l’idempotence automatique des autres endpoints d’écriture ; ne les relancez qu’après avoir déterminé le statut de l’opération.
Réponses et erreurs
Les réponses de succès sont des objets ou tableaux de contrats Magento. Les champs renvoyés par les objets peuvent être étendus de manière compatible ; l’intégration doit ignorer les champs inconnus. Une erreur métier peut contenir :
{ 'code': 'b2b.company.not_assigned_to_website', 'message': 'B2B company is not assigned to website.', 'website_id': 1, 'trace_id': 'request-correlation-id', 'details': {'company_id': 10}, 'field_errors': []}| HTTP | Signification | Réaction de l’intégrateur |
|---|---|---|
400 / 422 | Données incorrectes ou validation de domaine | Corrigez les données ; ne relancez pas sans modifier le payload. |
401 / 403 | Jeton/ACL absent ou insuffisant | Ne relancez pas ; signalez à l’administrateur le périmètre du jeton. |
404 | La ressource ou la relation dans ce contexte n’existe pas | Vérifiez les identifiants et le contexte website. |
409 | Conflit de statut ou doublon | Lisez l’état actuel avant de décider d’une nouvelle tentative. |
5xx / timeout | Erreur technique | Appliquez des retry limités avec backoff et conservez trace_id. |
Ne journalisez pas les jetons, les données personnelles complètes ni les secrets de configuration. La demande adressée à l’équipe de la boutique doit contenir l’heure, la méthode, le chemin sans secrets, le statut HTTP, trace_id et le payload anonymisé.
4. Schémas des données d’entrée
Les schémas ci-dessous sont communs aux endpoints de référence. Un champ sans ? est requis par le contrat ; ? indique une valeur optionnelle. Les champs metadata, config, configuration et payload sont des objets JSON.
| DTO / wrapper | Champs |
|---|---|
company | websiteId, name, taxId, externalId?, status?, salesRepresentativeId?, customerGroupId?, websiteActive? |
companyUser | websiteId, roleId, active |
request — RFQ | websiteId, companyId, customerId?, externalId?, title, currency, validUntil?, customerNote?, salesNote?, metadata? |
request — ligne RFQ | quoteId, sku, productId?, name?, qty, requestedPrice?, offeredPrice?, comment?, metadata? |
request — décision RFQ | customerId?, adminUserId?, message? |
request — commentaire RFQ | quoteId, customerId?, adminUserId?, authorType, message, visibleForCustomer |
request — document | websiteId, companyId, orderId?, orderIncrementId?, invoiceId?, invoiceIncrementId?, creditmemoId?, creditmemoIncrementId?, externalId?, documentNumber, documentType, status, issueDate?, dueDate?, grandTotal?, currency?, metadata? |
request — fichier de document | documentId, fileName, filePath, mimeType, fileSize, checksum?, primary |
request — limite | websiteId, companyId, termsId?, creditLimit, currency, active, status, metadata? |
request — exposition de limite | websiteId, companyId, sourceType, sourceId, sourceIncrementId?, amount, currency, dueDate?, metadata? |
request — conditions de paiement | websiteId, code, name, daysDue, active, description? |
request — règle de validation | websiteId, companyId, name, thresholdAmount, currency?, priority, active, metadata? |
request — valideur | ruleId, customerId, sortOrder, active |
request — décision de validation | approverCustomerId?, comment? |
request — demande de validation | websiteId, companyId, orderId?, orderIncrementId?, requesterCustomerId?, grandTotal, currency, comment?, metadata? |
request — profil import/export | websiteId, code, name, direction, entityType, format, behavior, active, configuration? |
request — profil d’intégration | websiteId, code, name, systemType, adapterCode, direction, active, maxAttempts, config? |
request — mapping | websiteId, systemType, entityType, localId, externalId, metadata? |
request — job d’intégration | profileId, direction?, entityType, operation, idempotencyKey?, maxAttempts?, payload?, scheduledAt? |
5. Référence des endpoints
Dans les tableaux, ACL indique la ressource minimale de droit Magento. Résultat précise le type de réponse de succès.
5.1. Websites et configuration
| Méthode et endpoint | ACL | Entrée | Résultat et utilisation |
|---|---|---|---|
GET /V1/kowal-b2b/websites | config | — | Tableau des websites (websiteId, code, nom, flag B2B). À récupérer avant de configurer l’intégration. |
GET /V1/kowal-b2b/websites/:websiteId/config | config | path : websiteId | Configuration du website B2B (notamment enabled/debug/rétention des logs). À exécuter comme test d’accès. |
GET /V1/kowal-b2b/websites/:websiteId/features | config | path : websiteId | Feature flags actifs pour le website ; à utiliser pour activer conditionnellement les fonctions client. |
5.2. Entreprises et utilisateurs d’entreprise
| Méthode et endpoint | ACL | Entrée | Résultat et utilisation |
|---|---|---|---|
GET /companies?websiteId= | companies | query : websiteId | Tableau des entreprises attribuées au website. |
POST /companies | company_save | body : company | Crée une entreprise et la relation avec le website ; utilisez Idempotency-Key lors des nouvelles tentatives. Renvoie l’entreprise. |
POST /companies/batch | batch | body : companies — tableau company | Crée plusieurs entreprises et renvoie le résultat par élément, y compris les erreurs. |
GET /companies/:companyId?websiteId= | companies | path : companyId ; query : websiteId | Entreprise vérifiée dans le contexte du website. |
PUT /companies/:companyId | company_save | path : companyId ; body : company | Met à jour les données et la relation de l’entreprise pour company.websiteId. |
POST /companies/:companyId/activate?websiteId= | company_save | path : companyId ; query : websiteId | Active l’entreprise dans le website indiqué et renvoie l’entreprise. |
POST /companies/:companyId/block?websiteId= | company_save | path : companyId ; query : websiteId | Bloque l’entreprise dans le website indiqué et renvoie l’entreprise. |
GET /companies/:companyId/users?websiteId= | company_users | path : companyId ; query : websiteId | Tableau des attributions de clients à l’entreprise. |
PUT /companies/:companyId/users/:customerId | company_users | path : companyId, customerId ; body : companyUser | Attribue/met à jour le rôle et l’activité du client dans l’entreprise ; renvoie l’attribution. |
5.3. Produits, prix et visibilité du catalogue
| Méthode et endpoint | ACL | Entrée | Résultat et utilisation |
|---|---|---|---|
GET /products?websiteId= | products | query : websiteId | Tableau des produits Magento de base pour le website. |
GET /products/:sku?websiteId= | products | path : sku encodé ; query : websiteId | Produit (id, sku, nom, type, statut, websites). |
GET /products/:sku/availability?websiteId= | products | path : sku ; query : websiteId | Disponibilité et quantité vendable MSI pour le SKU. |
GET /products/:sku/b2b-status?websiteId= | products | path : sku ; query : websiteId | Statut B2B : attribution au website, traductions et données stock. |
GET /reports/products/missing-translations?websiteId= | products | query : websiteId | Rapport des SKU sans traductions requises, avec reason/details. |
GET /reports/products/missing-stock?websiteId= | products | query : websiteId | Rapport des SKU sans données stock requises. |
GET /companies/:companyId/products/:sku/price?websiteId=¤cy=&qty= | prices | path : companyId, sku ; query : websiteId, currency, option qty (par défaut 1) | Explication du prix applicable à l’entreprise, à la devise et à la quantité ; à lire avant l’achat. |
GET /companies/:companyId/products/:sku/visibility?websiteId= | catalog_permissions | path : companyId, sku ; query : websiteId | Résultat de visibilité/achat du SKU pour l’entreprise. |
GET /companies/:companyId/catalog-visibility?websiteId= | catalog_permissions | path : companyId ; query : websiteId | Tableau des entrées de l’index du catalogue visible de l’entreprise. |
POST /companies/:companyId/catalog-visibility/reindex?websiteId= | catalog_permissions | path : companyId ; query : websiteId | Reconstruit l’index et renvoie le nombre d’entrées indexées. Opération administrative. |
5.4. Import et export de fichiers
| Méthode et endpoint | ACL | Entrée | Résultat et utilisation |
|---|---|---|---|
GET /import-export/profiles?websiteId= | import_export | query : websiteId | Tableau des profils d’import/export du website. |
POST /import-export/profiles | import_export | body : request — profil import/export | Enregistre le profil et renvoie ses données. |
POST /import-export/import/:profileId?sourceFile=&dryRun= | import_export | path : profileId ; query : sourceFile, option dryRun=false | Lance l’import du fichier indiqué côté environnement Magento ; renvoie le job. N’envoie pas de multipart. |
POST /import-export/export/:profileId?resultFile= | import_export | path : profileId ; query optionnelle : resultFile | Crée un job d’export, éventuellement avec un chemin de fichier cible. |
GET /import-export/jobs?websiteId= | import_export | query : websiteId | Tableau des jobs import/export pour le website. |
GET /import-export/jobs/:jobId | import_export | path : jobId | État, résultat et données d’un job unique. |
GET /import-export/jobs/:jobId/logs | import_export | path : jobId | Logs de diagnostic du job. |
5.5. Commande rapide et listes d’achat
| Méthode et endpoint | ACL | Entrée | Résultat et utilisation |
|---|---|---|---|
POST /companies/:companyId/quick-order/validate | quick_order | path : companyId ; body : websiteId, currency, items (sku, qty) | Valide plusieurs SKU dans le contexte de l’entreprise : disponibilité, visibilité et prix ; renvoie un résultat agrégé. |
GET /companies/:companyId/shopping-lists?websiteId= | quick_order | path : companyId ; query : websiteId | Tableau des listes d’achat de l’entreprise. |
POST /companies/:companyId/shopping-lists | quick_order | path : companyId ; body : websiteId, name, option customerId, isDefault=false | Crée une liste d’achat et la renvoie. |
GET /shopping-lists/:listId/items | quick_order | path : listId | Tableau des lignes de la liste indiquée. |
POST /shopping-lists/:listId/items | quick_order | path : listId ; body : currency, items (sku, qty) | Ajoute des lignes à la liste et renvoie les lignes enregistrées. |
5.6. Documents et fichiers
| Méthode et endpoint | ACL | Entrée | Résultat et utilisation |
|---|---|---|---|
GET /companies/:companyId/documents?websiteId=&documentType= | documents | path : companyId ; query : websiteId, option documentType | Documents de l’entreprise, filtrés éventuellement par type. |
GET /documents/:documentId?companyId=&websiteId= | documents | path : documentId ; query : companyId, websiteId | Détails du document après vérification de l’appartenance à l’entreprise. |
POST /documents | documents | body : request — document | Crée ou enregistre les métadonnées du document et renvoie le document. |
POST /documents/files | documents | body : request — fichier de document | Enregistre un fichier existant dans le storage Magento (nom, chemin, MIME, taille), sans envoyer de binaires. |
GET /documents/:documentId/files?companyId=&websiteId= | documents | path : documentId ; query : companyId, websiteId | Tableau des métadonnées des fichiers du document. |
GET /documents/:documentId/sync-logs | documents | path : documentId | Logs de synchronisation du document ; destinés à l’intégration administrative. |
5.7. Limite de crédit et conditions de paiement
| Méthode et endpoint | ACL | Entrée | Résultat et utilisation |
|---|---|---|---|
GET /companies/:companyId/credit/status?websiteId=¤cy= | credit_limits | path : companyId ; query : websiteId, currency | Statut de la limite, utilisation et montant disponible de l’entreprise. |
POST /credit-limits | credit_limits | body : request — limite | Crée/met à jour la limite de l’entreprise et renvoie la limite. |
POST /credit/exposures | credit_limits | body : request — exposition | Réserve l’exposition de limite pour la source (par exemple une commande) et la renvoie. |
POST /credit/exposures/:exposureId/release | credit_limits | path : exposureId ; body optionnel : message | Libère l’exposition ; renvoie son état. |
GET /payment-terms?websiteId= | credit_limits | query : websiteId | Tableau des conditions de paiement actives/connues du website. |
POST /payment-terms | credit_limits | body : request — conditions de paiement | Enregistre les conditions de paiement et les renvoie. |
5.8. Workflow de validation
| Méthode et endpoint | ACL | Entrée | Résultat et utilisation |
|---|---|---|---|
GET /companies/:companyId/approval/rules?websiteId=¤cy= | approvals | path : companyId ; query : websiteId, option currency | Règles de validation de l’entreprise pour le canal/la devise. |
POST /approval/rules | approvals | body : request — règle | Crée/met à jour une règle de seuil et la renvoie. |
GET /approval/rules/:ruleId/approvers | approvals | path : ruleId | Tableau des valideurs attribués, dans l’ordre sortOrder. |
POST /approval/approvers | approvals | body : request — valideur | Enregistre l’attribution du client comme valideur. |
GET /companies/:companyId/approval/required?websiteId=&grandTotal=¤cy= | approvals | path : companyId ; query : websiteId, grandTotal, currency | Boolean : indique si le montant nécessite une validation. |
POST /approval/requests | approvals | body : request — demande de validation | Crée une request pour la commande et la renvoie. |
GET /companies/:companyId/approval/requests?websiteId=&status= | approvals | path : companyId ; query : websiteId, option status | Tableau des requests de validation de l’entreprise. |
POST /approval/requests/:requestId/approve | approvals | path : requestId ; body : request — décision | Approuve la request ; renvoie son état actuel. |
POST /approval/requests/:requestId/reject | approvals | path : requestId ; body : request — décision | Rejette la request ; renvoie son état actuel. |
POST /approval/requests/:requestId/cancel | approvals | path : requestId ; body : request — décision | Annule la request ; renvoie son état actuel. |
GET /approval/requests/:requestId/decisions | approvals | path : requestId | Historique des décisions pour la request. |
5.9. Contexte B2B des commandes
| Méthode et endpoint | ACL | Entrée | Résultat et utilisation |
|---|---|---|---|
GET /orders/:orderId/b2b-context | orders | path : orderId | Contexte B2B d’une commande Magento native unique (par exemple entreprise, statut de validation, limite, export). |
GET /companies/:companyId/orders/b2b-context?websiteId=&approvalStatus= | orders | path : companyId ; query : websiteId, option approvalStatus | Tableau des contextes de commandes de l’entreprise, filtré éventuellement par statut de validation. |
5.10. RFQ et offres commerciales
| Méthode et endpoint | ACL | Entrée | Résultat et utilisation |
|---|---|---|---|
GET /companies/:companyId/quotes?websiteId=&status= | quotes | path : companyId ; query : websiteId, option status | RFQ et offres de l’entreprise, éventuellement par statut. |
POST /quotes | quotes | body : request — RFQ | Crée un RFQ brouillon et le renvoie. Ajoutez les lignes via un endpoint séparé. |
GET /quotes/:quoteId | quotes | path : quoteId | Détails du RFQ/de l’offre. |
GET /quotes/:quoteId/items | quotes | path : quoteId | Tableau des lignes RFQ. |
POST /quotes/items | quotes | body : request — ligne RFQ | Ajoute le SKU et la quantité, le prix demandé/offert optionnel et un commentaire. |
GET /quotes/:quoteId/comments | quotes | path : quoteId | Commentaires RFQ. Le client ne voit que les commentaires marqués comme visibles. |
POST /quotes/comments | quotes | body : request — commentaire RFQ | Ajoute un message ; authorType et visibleForCustomer déterminent l’auteur et la visibilité. |
GET /quotes/:quoteId/history | quotes | path : quoteId | Historique des changements de statut et des événements RFQ. |
POST /quotes/:quoteId/submit | quotes | path : quoteId ; body : request — décision RFQ | Transmet le RFQ brouillon pour chiffrage. |
POST /quotes/:quoteId/make-offer | quotes | path : quoteId ; body : request — décision RFQ | Le commercial crée/transmet l’offre ; définissez les prix des lignes avant l’appel. |
POST /quotes/:quoteId/accept | quotes | path : quoteId ; body : request — décision RFQ | Accepte l’offre actuelle. Ce contrat ne crée pas de commande REST. |
POST /quotes/:quoteId/reject | quotes | path : quoteId ; body : request — décision RFQ | Rejette l’offre/le RFQ. |
POST /quotes/:quoteId/cancel | quotes | path : quoteId ; body : request — décision RFQ | Annule le RFQ si le statut actuel le permet. |
5.11. Profils et jobs d’intégration
| Méthode et endpoint | ACL | Entrée | Résultat et utilisation |
|---|---|---|---|
GET /integrations/profiles?websiteId=&systemType= | system_integrations | query : websiteId, option systemType | Profils d’intégration pour le website. |
POST /integrations/profiles | system_integrations | body : request — profil d’intégration | Enregistre le profil ERP/PIM/WMS, etc. et le renvoie. |
POST /integrations/mappings | system_integrations | body : request — mapping | Enregistre la paire ID local ↔ ID externe. |
GET /integrations/mappings/local?websiteId=&systemType=&entityType=&localId= | system_integrations | query : tous les paramètres requis | Recherche le mapping par identifiant Magento. |
GET /integrations/mappings/external?websiteId=&systemType=&entityType=&externalId= | system_integrations | query : tous les paramètres requis | Recherche le mapping par identifiant du système externe. |
POST /integrations/jobs | system_integrations | body : request — job | Publie un job à exécuter ; idempotencyKey identifie l’opération métier. |
GET /integrations/jobs?websiteId=&status= | system_integrations | query : websiteId, option status | Tableau des jobs d’intégration. |
GET /integrations/jobs/:jobId | system_integrations | path : jobId | État et détails d’un job unique. |
POST /integrations/jobs/:jobId/process | system_integrations | path : jobId | Traite le job et renvoie son état actuel. |
POST /integrations/jobs/:jobId/retry | system_integrations | path : jobId | Relance le job après une erreur, conformément à sa limite de tentatives. |
GET /integrations/jobs/:jobId/logs | system_integrations | path : jobId | Logs d’exécution du job. |
GET /integrations/jobs/:jobId/errors | system_integrations | path : jobId | Erreurs de domaine/techniques du job. |
6. Exemples d’appels
export BASE_URL='https://b2b.example.com/rest/V1'export TOKEN='token-przekazany-przez-administratora'export WEBSITE_ID=1 COMPANY_ID=10 SKU='B2B-SKU-001' CURRENCY='PLN'# Test dostępu i konfiguracji kanałucurl -sS '$BASE_URL/kowal-b2b/websites/$WEBSITE_ID/config' \ -H 'Authorization: Bearer $TOKEN' -H 'Accept: application/json'# Cena kontraktowa firmy dla konkretnej ilościcurl -sS '$BASE_URL/kowal-b2b/companies/$COMPANY_ID/products/$SKU/price?websiteId=$WEBSITE_ID¤cy=$CURRENCY&qty=5' \ -H 'Authorization: Bearer $TOKEN' -H 'Accept: application/json'# Walidacja koszyka po SKUcurl -sS -X POST '$BASE_URL/kowal-b2b/companies/$COMPANY_ID/quick-order/validate' \ -H 'Authorization: Bearer $TOKEN' -H 'Content-Type: application/json' \ --data '{'websiteId':1,'currency':'PLN','items':[{'sku':'B2B-SKU-001','qty':5}]}'# Utworzenie RFQcurl -sS -X POST '$BASE_URL/kowal-b2b/quotes' \ -H 'Authorization: Bearer $TOKEN' -H 'Content-Type: application/json' \ --data '{'request':{'websiteId':1,'companyId':10,'customerId':25,'title':'Dostawa kwartalna','currency':'PLN','externalId':'ERP-RFQ-2026-001'}}'7. Scénarios d’intégration recommandés
Achat par SKU
- Lisez la configuration du website et enregistrez les
websiteId,companyIdet la devise transmis. - Utilisez quick order pour valider en masse les SKU, quantités, visibilité et disponibilité.
- Pour les lignes acceptées, récupérez le prix via
priceavec leqtyapproprié. - Créez un RFQ, ajoutez les lignes et envoyez-les via
submitsi l’achat nécessite une offre. - Suivez le statut et l’historique du RFQ ; après acceptation, procédez selon le processus de commande Magento convenu, car
V1n’expose pas d’endpoint de création d’order.
Documents et règlements
- Récupérez la liste des documents de l’entreprise, en filtrant éventuellement par
documentType. - Pour le document sélectionné, récupérez les métadonnées et la liste des fichiers ; le chemin du fichier n’est pas automatiquement une URL publique — convenez avec l’administrateur de la boutique de la méthode de téléchargement du binaire.
- Lisez le statut de la limite avant le processus d’achat ; seule une intégration avec l’ACL
credit_limitspeut la gérer.
Opérations asynchrones
- Enregistrez le profil d’intégration et les mappings d’identifiants.
- Publiez un job avec un
idempotencyKeymétier et conservez lejobId. - Lisez le job ainsi que les logs/erreurs ; n’appelez
retryqu’après analyse de l’erreur et suppression de sa cause.
8. Liste de recette avant production
- Le jeton ne dispose que des ACL nécessaires et n’est pas le jeton administrateur utilisé par l’UI.
- L’intégrateur gère correctement
401,403,404, la validation422, le conflit409et les timeout. - Chaque request dans le contexte B2B transmet le bon
websiteId, et les données de l’entreprise utilisent lecompanyIdcorrect. - Les prix, la visibilité et la disponibilité sont vérifiés avant la création du processus d’achat.
- La création d’entreprise utilise
Idempotency-Key; les jobs d’intégration disposent d’unidempotencyKeystable dans le body. - Les logs ne contiennent pas de jetons ni de données sensibles, et la procédure de support transmet
trace_id. - Les tests ont été effectués sur l’environnement de test avec une entreprise ayant une relation active avec le website B2B.
9. Compatibilité
Le contrat est versionné par /V1. L’extension des réponses par de nouveaux champs est compatible ; l’intégrateur doit tolérer les champs inconnus. Une modification supprimant un champ, le sens d’un champ ou un endpoint nécessite une nouvelle version d’API. En cas d’écart entre le document et l’installation en fonctionnement, le contrat actif webapi.xml de la version du module concernée fait foi.
Notice d'installation du module
Installation et configuration de Kowal B2B Suite
Ce manuel s’adresse à la personne qui a acheté Kowal B2B Suite et doit le lancer dans une installation Magento Open Source existante. Il couvre deux étapes :
- installation technique — réalisée par un développeur ou un administrateur serveur ;
- configuration métier — réalisée dans le panneau Magento par l’administrateur de la boutique.
Avant de commencer, effectuez une copie de la base de données et des fichiers Magento. Nous recommandons d’effectuer le premier lancement sur un environnement de test, puis seulement ensuite de déployer en production.
1. Ce que vous recevez et ce dont vous avez besoin
Kowal B2B Suite est fourni sous forme de package Composer kowal/metapackage-b2b-suite. Il contient les modules B2B ainsi que le thème frontend/Kowal/b2b.
Prérequis
| Élément | Prérequis |
|---|---|
| Magento | Magento Open Source 2.4.9 |
| PHP | 8.3 |
| Composer | Composer 2 |
| Accès serveur | SSH et possibilité d’exécuter bin/magento |
| Magento | catalogue, clients, checkout, Sales, MSI et cron opérationnels |
possibilité d’écriture dans var/ par le processus PHP |
Vous recevrez de Kowal :
- l’adresse du dépôt Composer privé — ci-après
REPOSITORY_URL; - le nom d’utilisateur ou l’identifiant d’accès —
USERNAME; - le jeton d’accès —
ACCESS_TOKEN; - la plage de versions autorisée du package.
N’enregistrez pas le jeton dans le dépôt Git, dans les tickets ni dans l’historique d’un shell partagé avec d’autres personnes.
2. Installation technique
Exécutez toutes les commandes dans le répertoire racine de l’installation Magento existante, en tant qu’utilisateur ayant accès aux fichiers et à la commande bin/magento.
2.1. Préparation
- Assurez-vous que Magento fonctionne correctement avant la modification.
- Enregistrez l’état du déploiement et effectuez une sauvegarde de la base de données ainsi que des répertoires
app/etc,pub/mediaetvar. - En production, activez le mode maintenance pendant la mise à jour :
bin/magento maintenance:enable2.2. Ajout du dépôt privé
Ajoutez le dépôt Composer Kowal et configurez les identifiants d’accès reçus.
Les identifiants d’accès au dépôt Composer, c’est-à-dire l’adresse e-mail du client et le jeton de licence, vous seront envoyés par e-mail après l’achat. Ils sont également disponibles dans l’espace client après connexion sur kowal.store. Remplacez TWOJ_EMAIL_KLIENTA par l’adresse e-mail de votre compte et TWOJ_TOKEN par le jeton reçu. Exécutez les commandes dans le répertoire racine de Magento.
composer config repositories.kowal composer https://repo.kowal.storecomposer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'Composer enregistre généralement les identifiants dans le fichier local auth.json ; n’ajoutez pas ce fichier à Git.
2.3. Installation du package
Installez la version transmise avec la licence. Pour la ligne actuelle du package, la commande d’exemple est :
composer require kowal/metapackage-b2b-suite:^0.2 --with-all-dependenciesAprès le téléchargement des dépendances, mettez à jour le schéma et la configuration Magento :
bin/magento setup:upgradebin/magento cache:cleanEn mode production, exécutez également :
bin/magento setup:di:compilebin/magento setup:static-content:deploy -f pl_PL en_USbin/magento cache:flushUtilisez uniquement les locales actives dans la boutique. Si l’installation utilise un autre processus de deployment, ajoutez les commandes ci-dessus à sa procédure standard.
2.4. Vérification de l’installation
bin/magento module:status | grep Kowalbin/magento indexer:statusDans le panneau d’administration, le menu B2B et l’onglet Stores > Configuration > Kowal > B2B doivent apparaître. S’ils ne sont pas présents, vérifiez le résultat de setup:upgrade, le cache et les rôles ACL de l’utilisateur administrateur.
2.5. Droits des fichiers PDF
Les PDF générés par B2B utilisent mPDF et des répertoires sous var/, notamment var/tmp/kowal_b2b_mpdf et var/kowal_b2b_documents. Le processus PHP doit pouvoir les créer et y écrire. L’absence de ces droits se manifeste par une erreur de génération du document ou du PDF.
Une fois le déploiement en production terminé, désactivez le mode maintenance :
bin/magento maintenance:disable3. Configuration de la structure de la boutique B2B
3.1. Website et store view
La suite fonctionne au niveau du website, et non globalement. Vous pouvez gérer le B2C et le B2B dans la même installation Magento, mais le B2B doit fonctionner dans un website distinct ou dans un website de vente professionnelle choisi en connaissance de cause.
- Dans Stores > Settings > All Stores, créez ou sélectionnez le website B2B, son store et sa store view.
- Mémorisez
website_id— il est utilisé par les entreprises, les prix, les documents, l’API et les intégrations. - Dans Content > Design > Configuration, attribuez le thème
frontend/Kowal/b2buniquement à la B2B store view. - Vérifiez que les devises, taxes, modes de livraison et moyens de paiement actifs sont configurés pour le même scope.
N’attribuez pas le thème B2B à une store view B2C si vous ne souhaitez pas modifier sa couche de présentation. La seule installation des modules n’active pas la logique B2B pour tous les websites.
3.2. Activation du B2B
- Ouvrez Stores > Configuration > Kowal > B2B.
- Dans le sélecteur de scope, choisissez le Website approprié.
- Dans la section General, réglez Enable B2B sur
Yes. - Pendant le déploiement, vous pouvez activer Debug Mode ; désactivez-le après les tests.
- Dans le scope Default Config, définissez la durée de rétention des logs.
- Enregistrez la configuration et videz le cache.
Après activation, toutes les store views appartenant à ce website sont traitées comme B2B. Une entreprise sans relation active avec ce website n’y aura pas accès.
3.3. Données du vendeur
Complétez les informations de l’entreprise vendeuse dans Stores > Configuration > General > Store Information : nom, adresse, téléphone et numéro fiscal. Elles sont utilisées dans les documents et les PDF RFQ. Complétez également l’adresse e-mail générale de l’expéditeur dans la configuration Sales Emails ainsi que le logo d’e-mail, s’il doit apparaître dans les PDF.
4. Configuration du premier client B2B
Appliquez l’ordre ci-dessous pour chaque entreprise. Cela permet d’éviter qu’un client dispose d’un compte, mais ne voie pas l’offre ou ne puisse pas passer le checkout.
4.1. Entreprise, personnes et adresses
- Ouvrez B2B > Companies et créez une entreprise.
- Renseignez le nom, le numéro fiscal, l’identifiant externe si l’entreprise est synchronisée avec ERP, le statut
Activeet l’attribution au website B2B. - Ajoutez un utilisateur de l’entreprise ou attribuez un client Magento existant. Donnez-lui le rôle approprié et activez l’attribution.
- Dans B2B > Company Addresses, ajoutez les adresses de l’entreprise ; marquez l’adresse de facturation et de livraison par défaut pour le website B2B.
- Dans B2B > Company Contacts, ajoutez un contact principal actif avec e-mail et téléphone.
L’adresse de facturation et le contact principal sont également utilisés dans les PDF RFQ. L’absence de ces données ne bloque pas le PDF, mais le document sera moins complet.
4.2. Rôles d’entreprise
Accordez aux utilisateurs uniquement les droits nécessaires. Une répartition typique est :
| Rôle | Exemples de tâches |
|---|---|
| Administrateur de l’entreprise | utilisateurs, rôles, adresses, documents et historique de l’entreprise |
| Acheteur | catalogue, commande rapide, panier, RFQ et commandes |
| Valideur | décisions dans le workflow de validation |
| Comptabilité | documents et informations de facturation |
Testez un compte de chaque type, en particulier le droit de passer et de valider des commandes. N’utilisez pas un seul compte partagé pour toute l’entreprise.
5. Offre, prix et checkout
5.1. Catalogue et prix
- Assurez-vous que les produits Magento sont attribués au website B2B, actifs et disposent de données MSI correctes.
- Configurez les grilles tarifaires ou les prix contractuels pour l’entreprise dans la zone B2B > Pricing (Price Lists, Price List Assignments ou Contract Prices).
- Configurez les règles de visibilité du catalogue pour l’entreprise conformément au modèle d’autorisations déployé, puis vérifiez la visibilité sur le compte client.
- Testez sur le compte de l’entreprise : recherche du SKU, visibilité du produit et prix pour la quantité
1ainsi que pour le palier de quantité.
Le prix B2B dépend de l’entreprise, du website, de la devise et de la quantité. Un produit visible en B2C n’est pas nécessairement disponible pour un client B2B.
5.2. Livraison et paiement
- Activez les modes de livraison et moyens de paiement requis dans la configuration Magento standard pour la B2B store view.
- Dans B2B > Checkout, ajoutez les règles des méthodes disponibles pour l’entreprise/website si vous souhaitez limiter le choix.
- Effectuez un test de panier sur les adresses par défaut de l’entreprise.
Si la création d’une commande depuis RFQ doit fonctionner automatiquement côté administrateur, l’entreprise doit avoir des adresses par défaut sans ambiguïté ainsi qu’un moyen de paiement et un mode de livraison actifs. Sinon, la suite chargera les données dans le Backend Order Create natif, où l’administrateur complétera les éléments manquants.
5.3. Limites et validations
Ces fonctions sont facultatives, mais doivent être configurées avant d’être activées pour les clients.
- Dans B2B > Credit > Payment Terms, ajoutez les conditions de paiement.
- Dans B2B > Credit > Credit Limits, attribuez à l’entreprise une limite, une devise, un statut et une échéance de paiement.
- Dans B2B > Approvals > Rules, créez une règle de seuil de montant pour l’entreprise et le website.
- Dans B2B > Approvals > Approvers, attribuez les personnes chargées de la validation.
- Testez le panier en dessous et au-dessus du seuil et vérifiez si la décision du valideur modifie la suite du processus.
6. Documents, PDF et RFQ
6.1. Documents Magento
Dans Stores > Configuration > Kowal > B2B > Documents, choisissez la source des documents et décidez quels documents doivent être générés automatiquement : confirmations de commande, factures, bons de livraison et avoirs. Définissez également le statut cible du document.
Dans B2B > Documents > PDF Templates :
- vérifiez le modèle actif pour chaque type et website ;
- effectuez un aperçu ;
- adaptez le HTML/CSS uniquement si vous disposez d’une personne connaissant les templates Magento et CSS mPDF ;
- générez une facture ou confirmation de test et vérifiez le téléchargement depuis le compte de l’entreprise.
6.2. RFQ et offre PDF
- Dans B2B > Quotes > RFQ, créez un RFQ de test pour une entreprise et un utilisateur actifs.
- Ajoutez un SKU visible pour l’entreprise, la quantité et le prix d’offre.
- Définissez la date de validité, envoyez l’offre au client et générez le PDF.
- Vérifiez la version client : données vendeur/acheteur, lignes, prix, total et date de validité.
- Vérifiez la version administrateur : notes commerciales supplémentaires, commentaires, historique et informations internes sur les lignes.
Le PDF client ne doit pas contenir les notes du commercial ni l’historique interne des statuts.
7. Commandes rapides, imports et intégrations
Commandes rapides
Dans B2B > Quick Order > Debug SKU, vérifiez la liste SKU,qty pour l’entreprise, le website et la devise. Créez ensuite une liste d’achat et testez son utilisation par le client sur le storefront.
Import et export
Dans B2B > Import/Export, définissez un profil uniquement après avoir déterminé la source des données. La configuration du profil est un objet JSON et doit contenir des chemins de fichiers accessibles sur le serveur Magento. Lancez d’abord l’import en mode test et analysez le job ainsi que les logs.
Intégrations API
Avant de créer le jeton d’intégration, définissez le périmètre des données et le propriétaire de la synchronisation. Utilisez une intégration Magento distincte pour chaque ERP, PIM, WMS ou middleware et accordez-lui uniquement les ACL B2B nécessaires. La liste complète des endpoints, jetons et règles de sécurité se trouve dans la documentation API pour les intégrateurs.
8. Checklist de recette
Avant le lancement en production, confirmez que :
- Les modules Kowal sont actifs, cron fonctionne, et le cache ainsi que les index sont corrects.
- Le B2B est activé uniquement pour le website approprié.
- Le thème B2B est attribué uniquement à la B2B store view.
- L’entreprise de test a le statut Active, un utilisateur, un rôle, un contact et des adresses par défaut.
- Le produit de test est actif, attribué au website, visible pour l’entreprise et possède un prix B2B correct.
- Le client peut se connecter, rechercher un SKU, utiliser quick order et ajouter un produit au panier.
- Le checkout affiche uniquement les modes de livraison et moyens de paiement autorisés.
- La limite et la règle de validation fonctionnent conformément à la politique de l’entreprise si ces fonctions sont utilisées.
- Le document et le PDF RFQ se génèrent et sont accessibles uniquement à l’entreprise appropriée.
- Le RFQ peut être envoyé, accepté et transmis au processus de création de commande.
- Les intégrations disposent de jetons séparés et d’ACL limitées si elles sont utilisées.
9. Problèmes les plus fréquents
| Symptôme | À vérifier |
|---|---|
| Le menu B2B n’apparaît pas | setup:upgrade, statut des modules, cache et ACL de l’administrateur. |
| L’entreprise ou le client ne voit pas le B2B | Vérifiez si le B2B est actif pour le bon website et si l’entreprise a une relation active avec ce website. |
| Le produit n’est pas visible ou n’a pas de prix | Attribution du produit au website, activité du SKU, données MSI, règles de catalogue, prix de l’entreprise, devise et quantité. |
| Absence de mode de livraison ou de paiement | Configuration Magento standard, scope B2B store view et règles B2B Checkout. |
| Le PDF n’est pas créé | Modèle PDF actif, package mPDF, droits sur var/, données du vendeur et logs Magento. |
| Le RFQ ne crée pas automatiquement la commande | Adresses par défaut de l’entreprise, paiement et livraison sans ambiguïté ; dans les autres cas, utilisez Backend Order Create. |
L’API renvoie 403 | Le jeton d’intégration ne dispose pas de l’ACL requis ; n’utilisez pas de jeton administrateur dans une application externe. |
Lors d’une demande au support, indiquez la version de Magento, la version du package, les étapes de reproduction, l’heure de l’événement, les logs anonymisés de manière sécurisée et l’éventuel trace_id. N’envoyez pas de jetons ni de mots de passe.
10. Mise à jour du package
- Consultez les informations de version transmises par Kowal.
- Effectuez d’abord la mise à jour sur l’environnement de test.
- Effectuez une sauvegarde,
composer update kowal/metapackage-b2b-suite --with-all-dependencies,bin/magento setup:upgrade, et en production également la compilation DI et le deployment des ressources statiques. - Répétez la checklist de recette, en portant une attention particulière aux prix, au checkout, aux documents et aux intégrations.
Ne mettez pas à jour le package en copiant manuellement des fichiers dans app/code ; cela provoque des problèmes avec Composer et complique le support ultérieur.