Professioneel B2B-systeem voor Magento 2 Open Source
- Compatibiliteit
- 2.4.9, 2.4.8, 2.4.7
- Hyva Theme
- Hyva Theme Redy
Beschrijving / Professioneel B2B-systeem voor Magento 2 Open Source
MAGENTO 2 · MAGENTO OPEN SOURCE · BEDRIJVEN · B2B-HANDEL
Combineer B2B- en B2C-verkoop in één Magento-installatie.
Kowal B2B Suite breidt Magento Open Source uit met bedrijven, controle van EU-btw-nummers in VIES, individuele handelsvoorwaarden, bestellijsten, RFQ-offertes, handelskrediet, goedkeuringen, documenten en integraties.
Bedien zakelijke klanten via een zelfbedieningsportaal en organiseer verkoopwerkzaamheden in Magento Admin.
17 modules en een basisthema · REST en GraphQL · Hyvä-accountadapter
ZO WERKT HET IN DE PRAKTIJK
01 · Bepaal uw verkoopmodel
Definieer bedrijven, kanalen, prijzen en gegevensbronnen.
02 · Configureer het B2B-proces
Wijs rollen, catalogustoegang, voorwaarden en goedkeuringen toe.
03 · Verbind systemen en implementeer
Selecteer adapters en controleer volledige scenario’s.
Alle functies van Kowal B2B Suite
Van bedrijfsregistratie en prijsbepaling tot offertes, bestellingen, documenten en gegevensuitwisseling. Activeer de onderdelen die passen bij de verkoopregels van uw bedrijf.
Bedrijven en de klantcyclus
Beheer bedrijfsgegevens met een naam, fiscaal nummer, externe identificatie en verantwoordelijke verkoopmedewerker.
- Bedrijfsregistratie en goedkeuring, activering, blokkering of afwijzing.
- Statussen: in afwachting, actief, inactief, geblokkeerd en afgewezen.
- Koppelingen met Magento-klantaccounts, klantgroepen en verkoopkanalen.
- Een wijzigingshistorie voor bedrijven, gebruikers, rollen, adressen en contactpersonen.
Gebruikers, rollen, adressen en contactpersonen
Een bedrijf kan meerdere inkopers en eigen rollen met vastgelegde rechten hebben.
- Gebruikers toewijzen of deactiveren en hun rollen wijzigen.
- Afzonderlijke rechten voor bestellen, bedrijfsbestellingen bekijken, RFQ, documenten, gebruikers en adressen.
- Factuur- en afleveradressen, standaardadressen per website en gedeelde bedrijfsadressen.
- Contactpersonen, inclusief een primaire contactpersoon; bewerken volgens de toegekende rechten.
- Bedrijfsgegevens en het fiscale nummer blijven gescheiden van de persoonlijke adresgegevens van de inkoper.
EU-btw-nummers controleren in VIES
Controleer EU-btw-nummers met landprefix rechtstreeks op de B2B-bedrijfskaart in Magento Admin. De knop ‘Controleren in VIES’ start de controle en toont het resultaat naast het veld voor het fiscale identificatienummer.
- EU-btw-nummers met landcode, bijvoorbeeld
PL1234567890; de controle omvat landen die Magento als EU-lidstaten herkent. - Normalisatie van de invoer: spaties, punten en koppeltekens worden genegeerd en letters worden vóór de controle omgezet naar hoofdletters.
- Ondersteuning van het Griekse prefix EL door dit te koppelen aan de landcode GR die Magento gebruikt.
- Controle van formaat en land voordat een verzoek naar VIES wordt verzonden, met een melding als de invoer moet worden gecorrigeerd.
- Afzonderlijke resultaten: geldig in VIES, ongeldig in VIES, ongeldige invoer of controle niet beschikbaar.
Een bevoegde beheerder start de controle voor een eerder opgeslagen bedrijf en btw-nummer, binnen een actief B2B-kanaal dat aan het bedrijf is toegewezen. Een gewijzigd nummer moet eerst worden opgeslagen.
Opgeslagen VIES-resultaten en actualiteit van gegevens
Het resultaat wordt direct bij het bedrijf opgeslagen, samen met de datum en tijd van de controle en het gecontroleerde btw-nummer. Zo is eenvoudiger vast te stellen welke gegevens opnieuw moeten worden gecontroleerd.
- Een kolom met de VIES-status in de bedrijvenlijst met filters voor niet gecontroleerd, geldig, ongeldig, ongeldig formaat of VIES niet beschikbaar.
- Een kolom met de controledatum met een filter op datumbereik.
- Reset na wijziging van het btw-nummer: bij het opslaan van een ander nummer wordt de status teruggezet naar ‘niet gecontroleerd’ en worden de vorige datum en het opgeslagen gecontroleerde nummer gewist.
- Behoud van het resultaat bij wijzigingen in alleen de schrijfwijze, zoals spaties, scheidingstekens of hoofdletters en kleine letters, en bij het bewerken van andere bedrijfsgegevens.
- Koppeling van het resultaat aan het juiste nummer: als het btw-nummer tijdens de controle verandert, weigert de module het resultaat voor het vorige nummer op te slaan en vraagt deze om een nieuwe poging.
Als de dienst het nummer niet kan verifiëren, krijgt de beheerder een aparte melding dat de controle niet beschikbaar is, met het verzoek later opnieuw te proberen. Een verbindingsfout wordt onderscheiden van een negatief VIES-resultaat.
B2B en B2C in één installatie
Activeer B2B voor geselecteerde Magento-websites. Alle winkelweergaven binnen zo’n website gebruiken B2B, terwijl andere websites B2C kunnen bedienen.
- Een bedrijf kan aan meerdere actieve B2B-websites zijn gekoppeld.
- De actieve status van de relatie en de klantgroep van het bedrijf worden per website ingesteld.
- Prijzen, catalogi, documenten, limieten, offertes en integraties werken binnen de juiste bedrijfs- en kanaalcontext.
- Een website toevoegen aan een bedrijf verplaatst geen Magento-klantaccounts en verandert hun groepen niet automatisch.
Toegangscontrole en een besloten B2B-portaal
Kies uit drie modellen: een openbare winkel, een winkel met verplichte aanmelding of een openbare catalogus met beperkingen voor gasten.
- Verplicht aanmelden met uitzonderingen voor geselecteerde acties of URL-paden.
- Na aanmelding terugkeren naar de oorspronkelijk opgevraagde pagina.
- Prijzen verbergen en aankopen door gasten onafhankelijk van elkaar uitschakelen.
- Eigen meldingen en een aanmeldlink in plaats van de prijs of bestelknop.
- Standaardknoppen voor toevoegen aan de winkelwagen verbergen en toevoegingen serverzijdig blokkeren in de klassieke storefront.
- Klantregistratie openhouden of uitschakelen.
De bescherming van de standaardstorefront moet afzonderlijk worden geïmplementeerd in een eigen openbare API of headless frontend.
Bestaande klanten naar bedrijven migreren
Met de bulkactie Assign or Create Company ordent u uw bestaande Magento-klantenbestand.
- Klanten met of zonder bedrijfstoewijzing filteren, ook voor exports en bulkacties.
- Een bedrijf koppelen op basis van een genormaliseerd fiscaal nummer of een nieuw bedrijf aanmaken; accounts zonder nummer krijgen afzonderlijke bedrijven.
- Standaardadressen en de primaire contactpersoon naar een nieuw bedrijf kopiëren.
- Een inkopersrol met basisrechten voor B2B toekennen.
- Bestaande klantgroepen behouden, reeds gekoppelde accounts overslaan en migratieresultaten en fouten rapporteren.
Beheer en bulkbewerkingen
Beheer bedrijven en hun gekoppelde gegevens vanuit één B2B-menu. Het Magento-klantrecord bevat een veld voor bedrijfstoewijzing.
- Lijsten en formulieren voor bedrijven, gebruikers, rollen, adressen, contactpersonen en auditgegevens.
- Status, verkoopmedewerker, websitekoppeling, relatieactiviteit en de klantgroep van het bedrijf in bulk wijzigen.
- Rollen in bulk aanmaken of bijwerken en desgewenst toewijzen aan alle actieve gebruikers van geselecteerde bedrijven.
- Een afzonderlijke transactie en auditregistraties voor elk verwerkt bedrijf.
- Magento-beheerdersrechten beperken de toegang tot afzonderlijke handelingen.
Prijslijsten, contractprijzen en staffels
Stel prijzen in per bedrijf, website, SKU, valuta en aantal. Contractprijzen hebben voorrang, gevolgd door een toegewezen B2B-prijslijst en daarna Magento-catalogusprijzen.
- Meerdere prijslijsten en toewijzingen aan bedrijven met prioriteiten.
- Contractprijzen en prijslijstregels met hoeveelheidsstaffels en velden voor geldigheidsperioden.
- Contract- en prijslijstprijzen toepassen in de winkelwagen.
- Prijsindexering, wijzigingsaudit en Explain Price om de gekozen prijsbron te bekijken.
- CSV-import en -export van prijslijstregels en prijsgegevens via de API.
RFQ-prijssuggesties houden rekening met winkel, klant, aantal, valuta en belastingen; bij catalogusprijzen ook met toepasselijke Magento-promoties.
Een catalogus per bedrijf
Beperk de zichtbaarheid van producten met regels voor een specifieke zakelijke klant of een volledige website.
- Regels voor geselecteerde producten, categorieën of de hele catalogus.
- Allow- en deny-acties; weigeren heeft voorrang op toestaan.
- Een zichtbaarheidsindex en filtering van productlijsten in de storefront.
- Toegangscontrole voor verborgen SKU’s en hercontrole in bestellijsten, RFQ en checkout.
- Productzichtbaarheid voor een bedrijf bekijken en de index via de API opnieuw opbouwen.
Het ontbreken van een passende regel verbergt een product niet vanzelf. Het aanbod blijft gebaseerd op de standaardcatalogus van Magento.
Snel bestellen en bestellijsten
Klanten maken benoemde bestellijsten en voegen meerdere regels op SKU toe, zonder elk product afzonderlijk te zoeken.
- Tot 100 regels tegelijk plakken: SKU, aantal en een optionele notitie, bijvoorbeeld
SKU-001;10;Levering aan magazijn. - Lijsten met een standaardmarkering, artikelen, laatste B2B-prijs en valuta.
- Controle van SKU, productstatus, websitekoppeling, zichtbaarheid voor het bedrijf, positief aantal en B2B-prijs.
- Een lijst na hercontrole aan de winkelwagen toevoegen.
- Beheerders kunnen lijsten bekijken, regels verwijderen en naar CSV exporteren.
- Debug SKU en schermen voor importlogboeken en regelfouten uit processen die deze gegevens aanleveren.
RFQ: offerteaanvragen vanuit het klantaccount
Een bevoegde inkoper kan een aanvraag indienen met een titel, notitie en 1 tot 200 artikelen.
- Zoeken op SKU, productnaam en bestaande EAN-, EAN13-, GTIN- of barcode-attributen.
- Suggesties uitsluitend voor actieve, zichtbare producten van het type simple en virtual.
- Aantal, een optionele gewenste netto-eenheidsprijs en een opmerking per artikel.
- Netto- en brutoprijzen bekijken; wijzigingen in het aantal vernieuwen suggesties zonder handmatig ingevoerde prijzen te overschrijven.
- Prijsverwerking in de winkelvaluta en volgens de belastinginstellingen van de winkel.
- Validatie van de hele aanvraag: een fout in een artikel draait het opslaan terug; het formulier bewaart de gegevens voor correctie.
RFQ: offertes opstellen en onderhandelen
Verkoopmedewerkers maken ook RFQ’s in Magento Admin, met een gekozen website, Store View, bedrijf, klant, valuta en producten.
- Opslaan als concept of ingediende aanvraag; productzoekfunctie met netto- en brutoprijssuggesties.
- Gevraagde en aangeboden prijzen, onderhandeld totaal, vervaldatum, opmerkingen en verkoopnotities.
- Processtatussen, beslissingshistorie en blokkering van acceptatie na de vervaldatum.
- Een gereed aanbod e-mailen met links naar details en PDF waarvoor aanmelding vereist is.
- Acceptatie of afwijzing door de klant, een optionele afwijsreden en beslissingen van de beheerder.
- Afzonderlijke PDF’s voor klant en beheerder; interne notities en beheerhistorie blijven in de beheerdersversie.
Van geaccepteerde offerte naar bestelling
Neem artikelen en overeengekomen prijzen uit een geaccepteerde offerte over in het bestelproces van Magento.
- Convert to Cart maakt een klantwinkelwagen met de artikelen en offerteprijzen.
- Een klant met bestelrechten kiest in de standaardcheckout het adres, de verzending en betaling.
- Create Order in Admin maakt automatisch een bestelling wanneer de vereiste adressen en eenduidige betaal- en verzendmethoden beschikbaar zijn.
- Als nog keuzes nodig zijn, wordt de offerte geladen in het standaardformulier voor bestellingen in de backend.
- De Store View-context en de koppeling met de voorbereide winkelwagen of bestelling blijven behouden.
Checkout, betaling, verzending en PO-nummer
Breid het standaardbestelproces van Magento uit met B2B-regels.
- Controleer het actieve bedrijf, de websitekoppeling en de bestelrechten van de gebruiker.
- Valideer catalogustoegang en de beschikbaarheid van een B2B-prijs bij het bestellen.
- Regels voor toegestane betaal- en verzendmethoden per bedrijf en website.
- Zakelijke factuur- en afleveradressen met standaardwaarden voor het juiste kanaal.
- Een inkoopordernummer van de klant (PO) en een bestelopmerking.
- Bedrijf, inkoper, kredietstatus, goedkeuringsstatus en exportstatus vastleggen in de B2B-context van de bestelling.
Handelskrediet en betalingsvoorwaarden
Volg kredietlimiet, gebruik en beschikbaar bedrag afzonderlijk per bedrijf, website en valuta.
- Betalingsvoorwaarden, activering of blokkering van de limiet en de optie om overschrijding toe te staan.
- Selecteer betaalmethoden die bedrijfskrediet gebruiken; andere werken zonder ingestelde kredietlimiet.
- Atomaire reservering vóór het plaatsen van de bestelling, gekoppeld aan de opgeslagen bestelling.
- Vrijgave na een fout zonder aangemaakte bestelling, volledige betaling, annulering of afsluiting.
- Handmatige correcties van het gebruik, inzicht in reserveringen en een gebeurtenissenhistorie.
- Cron-afstemming na een onderbroken proces of tijdelijke fout.
Bij een gedeeltelijke betaling blijft het volledige bedrag gereserveerd tot volledige afrekening of annulering.
Bestelgoedkeuring en controle op verwerking
Stel goedkeuringsregels in per bedrijf, website, valuta en waardedrempel. Bij meerdere passende regels zijn prioriteit en drempel bepalend.
- Actieve bedrijfsgebruikers als goedkeurders toewijzen.
- Automatisch een aanvraag in afwachting aanmaken voor een bestelling die aan een regel voldoet.
- Goedkeuren, afwijzen of annuleren met opmerking en auditspoor.
- Export als geblokkeerd markeren en de bestelling in de wacht zetten wanneer de status dat toelaat.
- Na goedkeuring de B2B-status bijwerken en de wachtstand opheffen; afwijzing of annulering laat de exportblokkering bestaan.
De meegeleverde workflow sluit een openstaande aanvraag met één beslissing. Goedkeuring in meerdere stappen vereist een aanvullende uitbreiding; de integratie moet de exportblokkering respecteren.
Zakelijke documenten in het klantportaal
Stel facturen, creditnota’s, leveringsbonnen en orderbevestigingen beschikbaar aan het juiste bedrijf.
- Automatisch documenten maken uit Magento Sales-bestellingen, facturen, verzendingen en creditnota’s.
- Documentbron, beginstatus en generatie per documenttype instellen; ondersteuning voor een hybride model Magento + API.
- Handmatige PDF-upload in Admin, metadata, datums, bedragen, valuta’s en koppelingen met Magento-entiteiten.
- Originele bestanden uit een extern systeem aanbieden zonder de inhoud te wijzigen.
- Downloads na controle van bedrijf, website, rechten en documentstatus.
- Klanttoegang, bestanden en synchronisatielogboeken in Admin bekijken.
Bewerkbare PDF’s en taalversies
Een gedeelde PDF-generator ondersteunt verkoopdocumenten en RFQ-offertes.
- HTML/CSS-sjablonen in Admin bewerken en met voorbeeldgegevens bekijken.
- Afzonderlijke sjablonen per documenttype, website en ontvanger; een lokaal sjabloon gaat vóór een globaal sjabloon.
- Eigen titels voor bevestigingen, facturen, creditnota’s, leveringsbonnen en offertes.
- Logo, verkoper- en kopergegevens, fiscale nummers, adressen, artikelen, totalen en betaal- en verzendinformatie en -instructies in verkoopdocumenten.
- Een RFQ-klantversie gescheiden van interne beheerdersgegevens.
- Vertaalde labels volgens de winkeltaal; woordenboeken voor Pools en veel andere Europese talen.
Sjabloonwijzigingen gelden voor nieuw gegenereerde PDF’s. Eerder opgeslagen bestanden moeten opnieuw worden gegenereerd.
Bedrijfsaccount en Hyvä Themes-adapter
Het bedrijfsportaal combineert bedrijfsgegevens, adressen, contactpersonen, gebruikers, documenten, krediet, bestellijsten en RFQ.
- Bedrijfsadressen en de vijf recentste bestellingen in het standaardaccountdashboard.
- Eigen of bedrijfsbrede bestellingen bekijken volgens de rechten, beveiligde PDF-links en opnieuw bestellen door de bevoegde oorspronkelijke koper.
- Zes zichtbaarheidsschakelaars voor standaardlinks: adressen, bestellingen, downloads, opgeslagen betalingen, beoordelingen en nieuwsbrief.
- Meegeleverde optionele Hyvä Themes-adapter met responsieve tabellen, formulieren en accountnavigatie.
- Activering per Store View; standaard uitgeschakeld en alleen actief met Hyvä en B2B.
De adapter omvat het klantaccount. Hyvä Checkout, winkelwagen en minicart vereisen een afzonderlijke integratie. Menuschakelaars regelen de zichtbaarheid van links; rechten worden apart gecontroleerd.
CSV-import en -export van B2B-gegevens
Draag gegevens over en werk ze bij met profielen die aan een specifieke website zijn toegewezen.
- Bedrijven, gebruikerstoewijzingen en rollen met rechten.
- Prijslijstdefinities, contractprijzen en regels voor cataloguszichtbaarheid.
- Documentmetadata, koppelingen naar bestaande documentbestanden en kredietlimieten.
- CSV-upload, validatie en dry-run om een import vóór het opslaan te controleren.
- Taakhistorie, foutlogboeken met regelnummers en downloads van foutrapporten en exportbestanden.
- Afzonderlijke import en export van prijslijstregels in Pricing.
Import van gebruikerstoewijzingen gebruikt bestaande Magento-accounts; import van documentbestanden verwijst naar bestanden die al op een toegestane locatie staan.
REST API en GraphQL
Maak B2B-processen via de API beschikbaar voor integraties of eigen interfaces.
- REST: websiteconfiguratie, bedrijven en gebruikers, producten, MSI-beschikbaarheid, prijzen, catalogus, bestellijsten, RFQ, documenten, limieten, goedkeuringen, bestelcontext, import/export en integraties.
- Batchbewerkingen voor bedrijven en een idempotentiesleutel bij het aanmaken van een bedrijf.
- Productrapporten, waaronder ontbrekende vertalingen en voorraadgegevens.
- GraphQL-query’s voor bedrijfsgegevens, prijzen, lijsten, offertes, documenten, krediet, goedkeuringen en integratietaken.
- GraphQL-mutaties voor bestellijsten, RFQ-processen en het publiceren, verwerken en opnieuw uitvoeren van integratietaken.
Toegang hangt af van rechten en de context van de handeling. REST en GraphQL bieden vastgelegde interfaces; hun bewerkingen zijn niet identiek.
Integraties met ERP, PIM, WMS en CRM
Het pakket biedt infrastructuur om Magento met uw bedrijfssystemen te verbinden.
- Profielen per website, systeemtype, uitwisselingsrichting en adapter.
- Koppelingen tussen lokale en externe identificaties.
- Synchronisatietaken aanmaken met een gepland tijdstip, invoergegevens en idempotentiesleutel.
- Verwerkingsstatussen, resultaten, aantallen pogingen, logboeken en fouten.
- Dezelfde taak handmatig opnieuw uitvoeren en taken die aandacht vereisen bekijken in de Dead Letter Queue.
Een specifiek ERP-, PIM-, WMS-, CRM-, EDI- of inkoopsysteem aansluiten vereist een adapter en een werkend verwerkingsproces. Bij de implementatie worden de bronnen voor bedrijven, prijzen, voorraad, bestellingen en documenten vastgelegd.
Dashboard, rapporten en diagnostiek
Het B2B-dashboard toont bedrijfsaantallen en -statussen, actieve gebruikers, prijslijsten, catalogusregels, fouten en recente wijzigingen.
- Rapporten over bedrijven zonder actieve website, gebruikers of prijslijst en klanten zonder bedrijf.
- Rapporten over ontbrekende geïndexeerde prijzen, MSI-brongegevens en vertalingen van productnamen.
- Documenten zonder bestand, import- en integratiefouten en bestellingen die wachten op goedkeuring of voor export zijn geblokkeerd.
- Rapporten per website filteren, records bekijken en naar CSV exporteren.
- Systeemstatus, audits van bedrijven en beslissingen, krediet- en synchronisatielogboeken, plus Explain Price en Debug SKU.
- Instellingen voor B2B-diagnostiek en bewaartermijnen van logboeken.
Eén pakket, modulaire architectuur
kowal/metapackage-b2b-suite bevat 17 Magento-modules en het basisthema frontend/Kowal/b2b: Base, Access Control, Company, Admin UI, Pricing, Catalog Permissions, Quick Order, Quote, Checkout, Credit Limit, Approval, Document, Import/Export, Integration, REST API, GraphQL en de optionele Hyvä-adapter.
Installatie verloopt via één Composer-pakket. Na toegang tot de repository omvat de implementatie het inschakelen van benodigde modules, bijwerken van de Magento-database, configureren van websites en bedrijven, compileren, publiceren van statische bestanden en legen van caches volgens de winkelmodus.
Vereisten en implementatie
Het project is gericht op Magento Open Source 2.4.9 en het pakket vereist PHP ^8.3. Het gebruikt Magento’s standaardcatalogus, winkelwagen, checkout en MSI, plus de PDF-generator mPDF.
De klassieke Magento-storefront en een optionele accountadapter voor Hyvä Themes zijn beschikbaar. Het B2B-basisthema vormt het uitgangspunt voor aanpassing van de vormgeving.
De implementatie hangt af van winkelversie, thema, betalingen, verzending en externe systemen. Compatibiliteit en het volledige bestelproces moeten in de doelinstallatie worden gecontroleerd.
Plan een B2B-implementatie voor uw bedrijf
Wilt u de module op uw winkel afstemmen? Vraag naar de implementatie van Kowal B2B Suite en bespreek de configuratie of benodigde uitbreidingen.
Lees vooraf hoe u handmatig B2B-verkoopwerk in Magento 2 beperkt en wat de handmatige verwerking van een B2B-bestelling werkelijk kost (artikelen in het Pools).
Meer informatie
| Hyva Theme | Hyva Theme Redy |
|---|---|
| Overeenstemming met sjabloon | Goed, Luma / Blank, Smid |
Configuratie van de integratie
Kowal B2B API — volledige REST-documentatie
Contractversie:
V1· Source of truth:Kowal_B2BApi/etc/webapi.xml· Doelgroepen: shopbeheerders, implementatiepartners en teams die ERP, PIM, WMS of een inkoopsysteem integreren.
1. Doel en grenzen van de API
Kowal B2B API stelt B2B-gegevens en -processen beschikbaar die in Magento 2 werken: bedrijven, catalogus en individuele prijzen, snelle aankopen, documenten, kredietlimiet, goedkeuringen, RFQ en integratiewachtrijen. Dit is een REST API voor systeemintegraties; deze vervangt niet de standaard Magento-endpoints voor catalogus, winkelwagen, checkout en klantaccount.
Het document beschrijft uitsluitend endpoints die momenteel door de module worden aangeboden. Het bevat geen belofte van operaties die contract V1 niet beschikbaar stelt, bijvoorbeeld het aanmaken van een bestelling via REST, CRUD van prijslijsten of bewerken van websiteconfiguratie.
2. Toegang verkrijgen en samenwerkingsregels
2.1. Proces voor het starten van een integratie
- De integrator geeft aan de shopbeheerder het doel van de integratie, omgeving (test/productie), bronsysteem, datascope en lijst met vereiste API-gebieden door.
- De beheerder maakt een Magento-integratie aan of configureert deze, wijst minimale ACL-rechten toe en geeft via een veilig kanaal door:
baseUrl, token,websiteId,companyIdindien van toepassing, valuta en testgegevens. - De integrator voert de test
GET /V1/kowal-b2b/websites/:websiteId/configuit en daarna functionele tests op de testomgeving. - Vóór productie stemmen beide partijen synchronisatieschema, maximale datagrootte, retry, data-eigenaar en foutmeldingswijze af.
- Tokens worden uitsluitend in een secrets vault bewaard; de beheerder roteert of trekt ze in bij wijziging van leverancier, gebruiker of integratiescope.
2.2. Verantwoordelijkheden
| Partij | Verantwoordelijkheid |
|---|---|
| Shopbeheerder | Configuratie van B2B-website, bedrijf en relatie tussen bedrijf en website, token en ACL; verstrekken van testgegevens; beslissing over toegang tot gegevens. |
| Integrator | Veilige opslag van token, correct gebruik van context websiteId/companyId, datavalidatie, fout- en retry-afhandeling, niet openbaar maken van gegevens van andere bedrijven. |
| Eigenaar van het bedrijfsproces | Afstemming van de source of truth voor prijzen, documenten, RFQ, limieten en synchronisatiestatussen. |
Gebruik geen beheertoken in een klantapplicatie en deel niet één token tussen onafhankelijke systemen. Elke integratie moet een eigen token hebben en uitsluitend de vereiste ACL.
2.3. Rechten
Magento verifieert het Bearer-token en de ACL die aan de administratieve gebruiker of integratie zijn toegewezen. B2B-endpoints vereisen een van onderstaande rechtengroepen:
| ACL | Scope |
|---|---|
config | Websites en feature flags |
companies, company_save, company_users, batch | Bedrijven, hun gebruikers en batchimport van bedrijven |
products, prices, catalog_permissions | Catalogus, beschikbaarheid, prijzen en zichtbaarheid |
import_export, quick_order, documents | Import-/exportprofielen, inkooplijsten en documenten |
credit_limits, approvals, orders, quotes | Limiet, goedkeuringsworkflow, bestelcontext en RFQ |
system_integrations | Profielen, mappings en integratiejobs |
De scope moet voortkomen uit het doel van de integratie. Voorbeeld: een inkoopsysteem heeft doorgaans products, prices, catalog_permissions, quick_order en quotes nodig; ERP dat documenten verwerkt — documents en, als het eigenaar van synchronisatie is, system_integrations.
3. Technische conventies
Adres, headers en parameters
Het basisadres heeft de vorm https://b2b.example.com/rest/V1. Alle paden verder in het document worden vanaf /V1 opgegeven; het volledige endpointadres is BASE_URL + pad.
Authorization: Bearer Accept: application/jsonContent-Type: application/json De API gebruikt JSON. Namen in URL's zijn camelCase (websiteId, companyId) en JSON-velden komen overeen met de parameternamen van Magento-contracten. :companyId, :quoteId, :sku enz. zijn padparameters. In voorbeelden betekent ? een optionele parameter.
websiteId is vereist bij operaties die afhankelijk zijn van het verkoopkanaal. Het moet verwijzen naar een bestaande website met ingeschakelde B2B. companyId verwijst naar een bedrijf dat een actieve relatie met deze website moet hebben wanneer de operatie in zijn context werkt. De API kiest geen standaardwebsite of standaardbedrijf.
Request body en idempotentie
Magento serialiseert een DTO-object onder de naam van de methodeparameter: de meeste schrijfoperaties accepteren {'request': {...}}; het aanmaken van een bedrijf gebruikt {'company': {...}}; batch van bedrijven — {'companies': [...]}. Endpoints met eenvoudige argumenten accepteren velden zonder wrapper, bijvoorbeeld {'websiteId': 1, 'currency': 'PLN', 'items': [...]}.
Header Idempotency-Key (max. 128 tekens) wordt momenteel ondersteund door POST /companies: een retry met dezelfde sleutel retourneert het eerder aangemaakte bedrijf. Gebruik voor een integratiejob het veld request.idempotencyKey. Ga niet uit van automatische idempotentie van andere schrijfendpoints; herhaal ze pas na vaststelling van de operatiestatus.
Antwoorden en fouten
Succesantwoorden zijn objecten of tabellen van Magento-contracten. Velden die door objecten worden geretourneerd kunnen op compatibele wijze worden uitgebreid; de integratie moet onbekende velden negeren. Een bedrijfsfout kan bevatten:
{ '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 | Betekenis | Reactie van integrator |
|---|---|---|
400 / 422 | Onjuiste gegevens of domeinvalidatie | Corrigeer gegevens; niet opnieuw proberen zonder payloadwijziging. |
401 / 403 | Ontbrekend of onvoldoende token/ACL | Niet opnieuw proberen; meld tokenscope aan beheerder. |
404 | Resource of relatie bestaat niet in de gegeven context | Verifieer identifiers en websitecontext. |
409 | Statusconflict of duplicaat | Lees de actuele status vóór beslissing over retry. |
5xx / timeout | Technische fout | Gebruik beperkte retry met backoff en bewaar trace_id. |
Log geen tokens, volledige persoonsgegevens of configuratiegeheimen. Een melding aan het shopteam moet tijd, methode, pad zonder secrets, HTTP-status, trace_id en geanonimiseerde payload bevatten.
4. Schema's voor invoergegevens
Onderstaande schema's gelden voor de referentie-endpoints. Een veld zonder ? is verplicht volgens het contract; ? betekent optionele waarde. Velden metadata, config, configuration en payload zijn JSON-objecten.
| DTO / wrapper | Velden |
|---|---|
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 — RFQ-regel | quoteId, sku, productId?, name?, qty, requestedPrice?, offeredPrice?, comment?, metadata? |
request — RFQ-beslissing | customerId?, adminUserId?, message? |
request — RFQ-opmerking | 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 — documentbestand | documentId, fileName, filePath, mimeType, fileSize, checksum?, primary |
request — limiet | websiteId, companyId, termsId?, creditLimit, currency, active, status, metadata? |
request — limietblootstelling | websiteId, companyId, sourceType, sourceId, sourceIncrementId?, amount, currency, dueDate?, metadata? |
request — betalingsvoorwaarden | websiteId, code, name, daysDue, active, description? |
request — goedkeuringsregel | websiteId, companyId, name, thresholdAmount, currency?, priority, active, metadata? |
request — goedkeurder | ruleId, customerId, sortOrder, active |
request — goedkeuringsbeslissing | approverCustomerId?, comment? |
request — goedkeuringsaanvraag | websiteId, companyId, orderId?, orderIncrementId?, requesterCustomerId?, grandTotal, currency, comment?, metadata? |
request — import/export-profiel | websiteId, code, name, direction, entityType, format, behavior, active, configuration? |
request — integratieprofiel | websiteId, code, name, systemType, adapterCode, direction, active, maxAttempts, config? |
request — mapping | websiteId, systemType, entityType, localId, externalId, metadata? |
request — integratiejob | profileId, direction?, entityType, operation, idempotencyKey?, maxAttempts?, payload?, scheduledAt? |
5. Endpointreferentie
In de tabellen betekent ACL de minimale Magento-rechtenresource. Resultaat geeft het soort succesantwoord aan.
5.1. Websites en configuratie
| Methode en endpoint | ACL | Input | Resultaat en toepassing |
|---|---|---|---|
GET /V1/kowal-b2b/websites | config | — | Tabel met websites (websiteId, code, naam, B2B-vlag). Ophalen vóór integratieconfiguratie. |
GET /V1/kowal-b2b/websites/:websiteId/config | config | path: websiteId | B2B-configuratie van website (o.a. enabled/debug/logretentie). Uitvoeren als toegangstest. |
GET /V1/kowal-b2b/websites/:websiteId/features | config | path: websiteId | Feature flags actief voor website; gebruik voor voorwaardelijk inschakelen van klantfuncties. |
5.2. Bedrijven en bedrijfsgebruikers
| Methode en endpoint | ACL | Input | Resultaat en toepassing |
|---|---|---|---|
GET /companies?websiteId= | companies | query: websiteId | Tabel met bedrijven toegewezen aan website. |
POST /companies | company_save | body: company | Maakt bedrijf en relatie met website aan; gebruik Idempotency-Key bij retries. Retourneert bedrijf. |
POST /companies/batch | batch | body: companies — tabel company | Maakt meerdere bedrijven aan en retourneert resultaat per element, inclusief fouten. |
GET /companies/:companyId?websiteId= | companies | path: companyId; query: websiteId | Bedrijf geverifieerd in websitecontext. |
PUT /companies/:companyId | company_save | path: companyId; body: company | Werkt gegevens en bedrijfsrelatie bij voor company.websiteId. |
POST /companies/:companyId/activate?websiteId= | company_save | path: companyId; query: websiteId | Activeert bedrijf in de aangegeven website en retourneert bedrijf. |
POST /companies/:companyId/block?websiteId= | company_save | path: companyId; query: websiteId | Blokkeert bedrijf in de aangegeven website en retourneert bedrijf. |
GET /companies/:companyId/users?websiteId= | company_users | path: companyId; query: websiteId | Tabel met klanttoewijzingen aan bedrijf. |
PUT /companies/:companyId/users/:customerId | company_users | path: companyId, customerId; body: companyUser | Geeft/werkt rol en activiteit van klant in bedrijf bij; retourneert toewijzing. |
5.3. Producten, prijs en cataloguszichtbaarheid
| Methode en endpoint | ACL | Input | Resultaat en toepassing |
|---|---|---|---|
GET /products?websiteId= | products | query: websiteId | Tabel met basis Magento-producten voor website. |
GET /products/:sku?websiteId= | products | path: gecodeerde sku; query: websiteId | Product (id, sku, naam, type, status, websites). |
GET /products/:sku/availability?websiteId= | products | path: sku; query: websiteId | Beschikbaarheid en verkoopbare MSI-hoeveelheid voor SKU. |
GET /products/:sku/b2b-status?websiteId= | products | path: sku; query: websiteId | B2B-status: toewijzing aan website, vertalingen en stockgegevens. |
GET /reports/products/missing-translations?websiteId= | products | query: websiteId | Rapport van SKU's zonder vereiste vertalingen, met reason/details. |
GET /reports/products/missing-stock?websiteId= | products | query: websiteId | Rapport van SKU's zonder vereiste stockgegevens. |
GET /companies/:companyId/products/:sku/price?websiteId=¤cy=&qty= | prices | path: companyId, sku; query: websiteId, currency, opt. qty (standaard 1) | Uitleg van de prijs die geldt voor bedrijf, valuta en hoeveelheid; lezen vóór aankoop. |
GET /companies/:companyId/products/:sku/visibility?websiteId= | catalog_permissions | path: companyId, sku; query: websiteId | Resultaat van zichtbaarheid/aankoop van SKU voor bedrijf. |
GET /companies/:companyId/catalog-visibility?websiteId= | catalog_permissions | path: companyId; query: websiteId | Tabel met indexposities van de zichtbare catalogus van het bedrijf. |
POST /companies/:companyId/catalog-visibility/reindex?websiteId= | catalog_permissions | path: companyId; query: websiteId | Bouwt de index opnieuw op en retourneert het aantal geïndexeerde posities. Administratieve operatie. |
5.4. Bestandsimport en -export
| Methode en endpoint | ACL | Input | Resultaat en toepassing |
|---|---|---|---|
GET /import-export/profiles?websiteId= | import_export | query: websiteId | Tabel met import-/exportprofielen van website. |
POST /import-export/profiles | import_export | body: request — import/export-profiel | Slaat profiel op en retourneert de gegevens. |
POST /import-export/import/:profileId?sourceFile=&dryRun= | import_export | path: profileId; query: sourceFile, opt. dryRun=false | Start import van bestand dat aan Magento-omgevingszijde is aangegeven; retourneert job. Verzendt geen multipart. |
POST /import-export/export/:profileId?resultFile= | import_export | path: profileId; opt. query: resultFile | Maakt exportjob aan, optioneel met doelbestandspad. |
GET /import-export/jobs?websiteId= | import_export | query: websiteId | Tabel met import/export-jobs voor website. |
GET /import-export/jobs/:jobId | import_export | path: jobId | Status, resultaat en gegevens van één job. |
GET /import-export/jobs/:jobId/logs | import_export | path: jobId | Diagnostische logs van de job. |
5.5. Snelle bestelling en inkooplijsten
| Methode en endpoint | ACL | Input | Resultaat en toepassing |
|---|---|---|---|
POST /companies/:companyId/quick-order/validate | quick_order | path: companyId; body: websiteId, currency, items (sku, qty) | Valideert meerdere SKU's in bedrijfscontext: beschikbaarheid, zichtbaarheid en prijs; retourneert verzamelresultaat. |
GET /companies/:companyId/shopping-lists?websiteId= | quick_order | path: companyId; query: websiteId | Tabel met inkooplijsten van het bedrijf. |
POST /companies/:companyId/shopping-lists | quick_order | path: companyId; body: websiteId, name, opt. customerId, isDefault=false | Maakt inkooplijst aan en retourneert deze. |
GET /shopping-lists/:listId/items | quick_order | path: listId | Tabel met regels van de aangegeven lijst. |
POST /shopping-lists/:listId/items | quick_order | path: listId; body: currency, items (sku, qty) | Voegt regels aan de lijst toe en retourneert opgeslagen regels. |
5.6. Documenten en bestanden
| Methode en endpoint | ACL | Input | Resultaat en toepassing |
|---|---|---|---|
GET /companies/:companyId/documents?websiteId=&documentType= | documents | path: companyId; query: websiteId, opt. documentType | Documenten van het bedrijf, optioneel gefilterd op type. |
GET /documents/:documentId?companyId=&websiteId= | documents | path: documentId; query: companyId, websiteId | Documentdetails na controle van bedrijfstoewijzing. |
POST /documents | documents | body: request — document | Maakt documentmetadata aan of slaat ze op en retourneert document. |
POST /documents/files | documents | body: request — documentbestand | Registreert een bestand dat in Magento storage bestaat (naam, pad, MIME, grootte), verzendt geen binaries. |
GET /documents/:documentId/files?companyId=&websiteId= | documents | path: documentId; query: companyId, websiteId | Tabel met metadata van documentbestanden. |
GET /documents/:documentId/sync-logs | documents | path: documentId | Synchronisatielogs van document; bedoeld voor administratieve integratie. |
5.7. Kredietlimiet en betalingstermijnen
| Methode en endpoint | ACL | Input | Resultaat en toepassing |
|---|---|---|---|
GET /companies/:companyId/credit/status?websiteId=¤cy= | credit_limits | path: companyId; query: websiteId, currency | Limietstatus, gebruik en beschikbare bedrag van bedrijf. |
POST /credit-limits | credit_limits | body: request — limiet | Maakt/werkt bedrijfslimiet bij en retourneert limiet. |
POST /credit/exposures | credit_limits | body: request — blootstelling | Reserveert limietblootstelling voor bron, bijvoorbeeld bestelling, en retourneert deze. |
POST /credit/exposures/:exposureId/release | credit_limits | path: exposureId; opt. body: message | Geeft blootstelling vrij; retourneert de status. |
GET /payment-terms?websiteId= | credit_limits | query: websiteId | Tabel met actieve/bekende betalingstermijnen van website. |
POST /payment-terms | credit_limits | body: request — betalingsvoorwaarden | Slaat betalingstermijnen op en retourneert ze. |
5.8. Goedkeuringsworkflow
| Methode en endpoint | ACL | Input | Resultaat en toepassing |
|---|---|---|---|
GET /companies/:companyId/approval/rules?websiteId=¤cy= | approvals | path: companyId; query: websiteId, opt. currency | Goedkeuringsregels van bedrijf voor kanaal/valuta. |
POST /approval/rules | approvals | body: request — regel | Maakt/werkt drempelregel bij en retourneert deze. |
GET /approval/rules/:ruleId/approvers | approvals | path: ruleId | Tabel met toegewezen goedkeurders, in volgorde sortOrder. |
POST /approval/approvers | approvals | body: request — goedkeurder | Slaat toewijzing van klant als goedkeurder op. |
GET /companies/:companyId/approval/required?websiteId=&grandTotal=¤cy= | approvals | path: companyId; query: websiteId, grandTotal, currency | Boolean: of bedrag goedkeuring vereist. |
POST /approval/requests | approvals | body: request — goedkeuringsaanvraag | Maakt request voor bestelling aan en retourneert deze. |
GET /companies/:companyId/approval/requests?websiteId=&status= | approvals | path: companyId; query: websiteId, opt. status | Tabel met goedkeuringsrequests van bedrijf. |
POST /approval/requests/:requestId/approve | approvals | path: requestId; body: request — beslissing | Keurt request goed; retourneert actuele status. |
POST /approval/requests/:requestId/reject | approvals | path: requestId; body: request — beslissing | Wijst request af; retourneert actuele status. |
POST /approval/requests/:requestId/cancel | approvals | path: requestId; body: request — beslissing | Annuleert request; retourneert actuele status. |
GET /approval/requests/:requestId/decisions | approvals | path: requestId | Beslissingsgeschiedenis voor request. |
5.9. B2B-context van bestellingen
| Methode en endpoint | ACL | Input | Resultaat en toepassing |
|---|---|---|---|
GET /orders/:orderId/b2b-context | orders | path: orderId | B2B-context van één native Magento-bestelling, bijvoorbeeld bedrijf, goedkeuringsstatus, limiet, export. |
GET /companies/:companyId/orders/b2b-context?websiteId=&approvalStatus= | orders | path: companyId; query: websiteId, opt. approvalStatus | Tabel met bestelcontexten van bedrijf, optioneel gefilterd op goedkeuringsstatus. |
5.10. RFQ en commerciële offertes
| Methode en endpoint | ACL | Input | Resultaat en toepassing |
|---|---|---|---|
GET /companies/:companyId/quotes?websiteId=&status= | quotes | path: companyId; query: websiteId, opt. status | RFQ en offertes van bedrijf, optioneel op status. |
POST /quotes | quotes | body: request — RFQ | Maakt concept-RFQ aan en retourneert deze. Voeg regels via apart endpoint toe. |
GET /quotes/:quoteId | quotes | path: quoteId | Details van RFQ/offerte. |
GET /quotes/:quoteId/items | quotes | path: quoteId | Tabel met RFQ-regels. |
POST /quotes/items | quotes | body: request — RFQ-regel | Voegt SKU en hoeveelheid, optionele gewenste/offerteprijs en opmerking toe. |
GET /quotes/:quoteId/comments | quotes | path: quoteId | RFQ-opmerkingen. De klant ziet alleen opmerkingen die als zichtbaar zijn gemarkeerd. |
POST /quotes/comments | quotes | body: request — RFQ-opmerking | Voegt bericht toe; authorType en visibleForCustomer bepalen auteur en zichtbaarheid. |
GET /quotes/:quoteId/history | quotes | path: quoteId | Geschiedenis van statuswijzigingen en RFQ-events. |
POST /quotes/:quoteId/submit | quotes | path: quoteId; body: request — RFQ-beslissing | Geeft concept-RFQ door voor prijsopgave. |
POST /quotes/:quoteId/make-offer | quotes | path: quoteId; body: request — RFQ-beslissing | Verkoper maakt/geeft offerte door; stel vóór aanroep de prijzen van regels vast. |
POST /quotes/:quoteId/accept | quotes | path: quoteId; body: request — RFQ-beslissing | Accepteert de actuele offerte. Maakt in dit contract geen REST-bestelling aan. |
POST /quotes/:quoteId/reject | quotes | path: quoteId; body: request — RFQ-beslissing | Wijst offerte/RFQ af. |
POST /quotes/:quoteId/cancel | quotes | path: quoteId; body: request — RFQ-beslissing | Annuleert RFQ als de actuele status dit toestaat. |
5.11. Integratieprofielen en -jobs
| Methode en endpoint | ACL | Input | Resultaat en toepassing |
|---|---|---|---|
GET /integrations/profiles?websiteId=&systemType= | system_integrations | query: websiteId, opt. systemType | Integratieprofielen voor website. |
POST /integrations/profiles | system_integrations | body: request — integratieprofiel | Slaat ERP/PIM/WMS-profiel enz. op en retourneert dit. |
POST /integrations/mappings | system_integrations | body: request — mapping | Slaat paar lokale ID ↔ externe ID op. |
GET /integrations/mappings/local?websiteId=&systemType=&entityType=&localId= | system_integrations | query: alle parameters verplicht | Zoekt mapping op basis van Magento-identifier. |
GET /integrations/mappings/external?websiteId=&systemType=&entityType=&externalId= | system_integrations | query: alle parameters verplicht | Zoekt mapping op basis van identifier van extern systeem. |
POST /integrations/jobs | system_integrations | body: request — job | Publiceert job voor uitvoering; idempotencyKey identificeert bedrijfsoperatie. |
GET /integrations/jobs?websiteId=&status= | system_integrations | query: websiteId, opt. status | Tabel met integratiejobs. |
GET /integrations/jobs/:jobId | system_integrations | path: jobId | Status en details van één job. |
POST /integrations/jobs/:jobId/process | system_integrations | path: jobId | Verwerkt job en retourneert actuele status. |
POST /integrations/jobs/:jobId/retry | system_integrations | path: jobId | Herhaalt job na fout, volgens de limiet van pogingen. |
GET /integrations/jobs/:jobId/logs | system_integrations | path: jobId | Uitvoeringslogs van job. |
GET /integrations/jobs/:jobId/errors | system_integrations | path: jobId | Domein-/technische fouten van job. |
6. Voorbeelden van aanroepen
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. Aanbevolen integratiescenario's
Aankoop op SKU
- Lees de websiteconfiguratie uit en sla het doorgegeven
websiteId,companyIden de valuta op. - Gebruik quick order voor gezamenlijke validatie van SKU's, hoeveelheden, zichtbaarheid en beschikbaarheid.
- Haal voor geaccepteerde regels de prijs uit
priceop met de juisteqty. - Maak RFQ aan, voeg regels toe en verstuur ze via
submitals de aankoop een offerte vereist. - Volg status en geschiedenis van RFQ; handel na acceptatie volgens het afgestemde Magento-bestelproces, omdat
V1geen endpoint voor het aanmaken van order aanbiedt.
Documenten en afrekening
- Haal de documentenlijst van het bedrijf op, optioneel gefilterd op
documentType. - Haal voor het geselecteerde document metadata en de bestandenlijst op; het bestandspad is niet automatisch een publieke URL — stem de manier van downloaden van de binary af met de shopbeheerder.
- Lees de limietstatus vóór het inkoopproces uit; alleen een integratie met ACL
credit_limitskan deze beheren.
Asynchrone operaties
- Sla integratieprofiel en identifier-mappings op.
- Publiceer een job met bedrijfsgerichte
idempotencyKeyen bewaarjobId. - Lees job en logs/fouten uit; roep
retrypas aan na analyse van de fout en verwijdering van de oorzaak.
8. Acceptatielijst vóór productie
- Het token heeft uitsluitend de vereiste ACL en is geen beheertoken dat door de UI wordt gebruikt.
- De integrator handelt
401,403,404, validatie422, conflict409en time-outs correct af. - Elke request in B2B-context geeft het juiste
websiteIddoor en bedrijfsgegevens gebruiken de juistecompanyId. - Prijzen, zichtbaarheid en beschikbaarheid worden gecontroleerd voordat het inkoopproces wordt aangemaakt.
- Het aanmaken van een bedrijf gebruikt
Idempotency-Key; integratiejobs hebben een stabieleidempotencyKeyin de body. - Logs bevatten geen tokens of gevoelige gegevens en de supportprocedure geeft
trace_iddoor. - Tests zijn uitgevoerd op een testomgeving met een bedrijf dat een actieve relatie met de B2B-website heeft.
9. Compatibiliteit
Het contract is geversioneerd via /V1. Uitbreiding van antwoorden met nieuwe velden is compatibel; de integrator moet onbekende velden tolereren. Een wijziging die een veld, de betekenis van een veld of een endpoint verwijdert, vereist een nieuwe API-versie. Bij verschillen tussen document en werkende installatie is het actieve contract webapi.xml van de betreffende moduleversie bindend.
Installatiehandleiding voor de module
Installatie en configuratie van Kowal B2B Suite
Deze handleiding is bedoeld voor de persoon die Kowal B2B Suite heeft gekocht en deze in een bestaande Magento Open Source-installatie moet starten. De handleiding leidt door twee fasen:
- technische installatie — uitgevoerd door een developer of serverbeheerder;
- bedrijfsconfiguratie — uitgevoerd in het Magento-paneel door de shopbeheerder.
Maak vóór de start een back-up van de Magento-database en bestanden. Wij raden aan de eerste start op een testomgeving uit te voeren en pas daarna naar productie te implementeren.
1. Wat u ontvangt en wat u nodig hebt
Kowal B2B Suite wordt geleverd als Composer-pakket kowal/metapackage-b2b-suite. Het bevat B2B-modules en het theme frontend/Kowal/b2b.
Vereisten
| Element | Vereiste |
|---|---|
| Magento | Magento Open Source 2.4.9 |
| PHP | 8.3 |
| Composer | Composer 2 |
| Servertoegang | SSH en de mogelijkheid om bin/magento uit te voeren |
| Magento | werkende catalogus, klanten, checkout, Sales, MSI en cron |
schrijftoegang tot var/ door het PHP-proces |
Van Kowal ontvangt u:
- adres van de privé Composer-repository — verder als
REPOSITORY_URL; - gebruikersnaam of toegangs-ID —
USERNAME; - toegangstoken —
ACCESS_TOKEN; - toegestaan versiebereik van het pakket.
Sla het token niet op in de Git-repository, in tickets of in de shellgeschiedenis die met anderen wordt gedeeld.
2. Technische installatie
Voer alle opdrachten uit in de hoofdmap van de bestaande Magento-installatie, als gebruiker met toegang tot de bestanden en de opdracht bin/magento.
2.1. Voorbereiding
- Controleer of Magento vóór de wijziging correct werkt.
- Leg de implementatiestatus vast en maak een back-up van de database en de mappen
app/etc,pub/mediaenvar. - Schakel op productie maintenance mode in voor de duur van de update:
bin/magento maintenance:enable2.2. Privé-repository toevoegen
Voeg de Kowal Composer-repository toe en configureer de ontvangen toegangsgegevens.
De toegangsgegevens voor de Composer-repository, het e-mailadres van de klant en het licentietoken, ontvangt u per e-mail na aankoop. Ze zijn ook beschikbaar in het klantenpaneel na inloggen op kowal.store. Vervang TWOJ_EMAIL_KLIENTA door het e-mailadres van uw account en TWOJ_TOKEN door het ontvangen token. Voer de opdrachten uit in de hoofdmap van Magento.
composer config repositories.kowal composer https://repo.kowal.storecomposer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'Composer slaat credentials doorgaans op in het lokale auth.json; voeg dit bestand niet toe aan Git.
2.3. Pakket installeren
Installeer de versie die samen met de licentie is verstrekt. Voor de huidige pakketlijn ziet een voorbeeldopdracht er als volgt uit:
composer require kowal/metapackage-b2b-suite:^0.2 --with-all-dependenciesVoer na het downloaden van afhankelijkheden de update van Magento-schema en configuratie uit:
bin/magento setup:upgradebin/magento cache:cleanVoer in production mode daarnaast uit:
bin/magento setup:di:compilebin/magento setup:static-content:deploy -f pl_PL en_USbin/magento cache:flushGebruik alleen de locales die actief zijn in de shop. Als de installatie een ander deploymentproces gebruikt, voeg de bovenstaande commando's dan toe aan de standaardprocedure.
2.4. Installatie verifiëren
bin/magento module:status | grep Kowalbin/magento indexer:statusIn het beheerpaneel moeten het menu B2B en het tabblad Stores > Configuration > Kowal > B2B verschijnen. Als ze ontbreken, controleer dan het resultaat van setup:upgrade, cache en de ACL-rollen van de beheerder.
2.5. Rechten voor PDF-bestanden
PDF's die door B2B worden gegenereerd gebruiken mPDF en mappen onder var/, waaronder var/tmp/kowal_b2b_mpdf en var/kowal_b2b_documents. Het PHP-proces moet deze kunnen aanmaken en beschrijven. Ontbrekende rechten uiten zich in een fout bij het genereren van document of PDF.
Schakel maintenance mode na afronding van de productie-implementatie uit:
bin/magento maintenance:disable3. Configuratie van de B2B-shopstructuur
3.1. Website en store view
De suite werkt binnen de scope van website, niet globaal. U kunt B2C en B2B in dezelfde Magento-installatie beheren, maar B2B hoort in een aparte website of in een bewust gekozen website voor zakelijke verkoop te werken.
- Maak of kies in Stores > Settings > All Stores de B2B-website, de store en de store view.
- Onthoud
website_id— deze wordt gebruikt door bedrijven, prijzen, documenten, API en integraties. - Wijs in Content > Design > Configuration het theme
frontend/Kowal/b2balleen toe aan de B2B store view. - Controleer of actieve valuta, belastingen, verzendmethoden en betaalmethoden voor dezelfde scope zijn geconfigureerd.
Wijs het B2B-theme niet toe aan de B2C store view als u de presentatielaag daarvan niet wilt wijzigen. Alleen de installatie van modules schakelt B2B-logica niet voor alle websites in.
3.2. B2B activeren
- Open Stores > Configuration > Kowal > B2B.
- Kies in de scope-schakelaar de juiste Website.
- Zet in de sectie General Enable B2B op
Yes. - Tijdens de implementatie kunt u Debug Mode inschakelen; schakel deze na tests uit.
- Stel in de scope Default Config de bewaartermijn van logs in.
- Sla de configuratie op en leeg de cache.
Na activering worden alle store views die bij deze website horen als B2B behandeld. Een bedrijf zonder actieve relatie met deze website krijgt er geen toegang toe.
3.3. Verkopersgegevens
Vul de gegevens van het verkopende bedrijf aan in Stores > Configuration > General > Store Information: naam, adres, telefoon en btw-nummer. Ze worden gebruikt in documenten en RFQ-PDF's. Vul ook het algemene e-mailadres van de afzender in de configuratie van Sales Emails en het e-maillogo aan, als dit in PDF's moet verschijnen.
4. Configuratie van de eerste B2B-klant
Gebruik onderstaande volgorde voor elk bedrijf. Dit helpt situaties te voorkomen waarin de klant een account heeft, maar geen aanbod ziet of de checkout niet kan doorlopen.
4.1. Bedrijf, personen en adressen
- Open B2B > Companies en maak een bedrijf aan.
- Geef naam, btw-nummer, externe ID als het bedrijf met ERP wordt gesynchroniseerd, status
Activeen toewijzing aan de B2B-website op. - Voeg een bedrijfsgebruiker toe of wijs een bestaande Magento-klant toe. Geef hem de juiste rol en activeer de toewijzing.
- Voeg in B2B > Company Addresses de bedrijfsadressen toe; markeer het standaard factuur- en verzendadres voor de B2B-website.
- Voeg in B2B > Company Contacts een actief hoofdcontact met e-mail en telefoon toe.
Factuuradres en hoofdcontact worden ook gebruikt in RFQ-PDF's. Ontbrekende gegevens blokkeren de PDF niet, maar het document is minder compleet.
4.2. Bedrijfsrollen
Geef gebruikers alleen de benodigde rechten. Een typische verdeling is:
| Rol | Voorbeeldtaken |
|---|---|
| Bedrijfsbeheerder | gebruikers, rollen, adressen, documenten en bedrijfsgeschiedenis |
| Inkoper | catalogus, quick order, winkelwagen, RFQ en bestellingen |
| Goedkeurder | beslissingen in de goedkeuringsworkflow |
| Boekhouding | documenten en afrekeninformatie |
Test elk accounttype, vooral de rechten om bestellingen te plaatsen en goed te keuren. Gebruik niet één gedeeld account voor het hele bedrijf.
5. Aanbod, prijzen en checkout
5.1. Catalogus en prijzen
- Controleer of Magento-producten aan de B2B-website zijn toegewezen, actief zijn en correcte MSI-gegevens hebben.
- Configureer prijslijsten of contractprijzen voor het bedrijf in B2B > Pricing (Price Lists, Price List Assignments of Contract Prices).
- Configureer cataloguszichtbaarheidsregels voor het bedrijf volgens het geïmplementeerde rechtenmodel en controleer daarna de zichtbaarheid op het klantaccount.
- Test op het bedrijfsaccount: zoeken op SKU, productzichtbaarheid en prijs voor hoeveelheid
1en voor de staffel.
De B2B-prijs is afhankelijk van bedrijf, website, valuta en hoeveelheid. Een product dat zichtbaar is in B2C hoeft niet beschikbaar te zijn voor de B2B-klant.
5.2. Verzending en betaling
- Schakel de vereiste verzend- en betaalmethoden in de standaard Magento-configuratie voor de B2B store view in.
- Voeg in B2B > Checkout regels voor beschikbare methoden voor bedrijf/website toe als u de keuze wilt beperken.
- Voer een winkelwagentest uit op de standaardadressen van het bedrijf.
Als het aanmaken van een bestelling vanuit RFQ automatisch aan beheerzijde moet werken, moet het bedrijf eenduidige standaardadressen en een actieve betaal- en verzendmethode hebben. Anders laadt de Suite gegevens in native Backend Order Create, waar de beheerder ontbrekende elementen aanvult.
5.3. Limieten en goedkeuringen
Deze functies zijn optioneel, maar moeten worden geconfigureerd voordat ze voor klanten worden ingeschakeld.
- Voeg in B2B > Credit > Payment Terms betalingstermijnen toe.
- Wijs in B2B > Credit > Credit Limits een limiet, valuta, status en betalingstermijn aan het bedrijf toe.
- Maak in B2B > Approvals > Rules een drempelbedragregel voor bedrijf en website.
- Wijs in B2B > Approvals > Approvers goedkeurders toe.
- Test een winkelwagen onder en boven de drempel en controleer of de beslissing van de goedkeurder het verdere proces wijzigt.
6. Documenten, PDF en RFQ
6.1. Magento-documenten
Kies in Stores > Configuration > Kowal > B2B > Documents de documentbron en bepaal welke documenten automatisch moeten worden gegenereerd: orderbevestigingen, facturen, pakbonnen en correcties. Stel ook de doelstatus van het document in.
In B2B > Documents > PDF Templates:
- controleer de actieve template voor elk type en elke website;
- maak een preview;
- pas HTML/CSS alleen aan als u iemand hebt die Magento-templates en mPDF CSS kent;
- genereer een testfactuur of bevestiging en controleer het downloaden vanaf het bedrijfsaccount.
6.2. RFQ en PDF-offerte
- Maak in B2B > Quotes > RFQ een test-RFQ aan voor een actief bedrijf en gebruiker.
- Voeg SKU's die voor het bedrijf zichtbaar zijn, hoeveelheid en offerteprijs toe.
- Stel de geldigheidsdatum in, stuur de offerte naar de klant en genereer PDF.
- Controleer de klantvariant: gegevens van verkoper/koper, regels, prijs, totaal en geldigheidsdatum.
- Controleer de beheerdersvariant: daarnaast commerciële notities, opmerkingen, geschiedenis en interne informatie over regels.
De klant-PDF mag geen notities van de verkoper of interne statushistorie bevatten.
7. Snelle bestellingen, imports en integraties
Snelle bestellingen
Controleer in B2B > Quick Order > Debug SKU de lijst SKU,qty voor bedrijf, website en valuta. Maak daarna een inkooplijst en test het gebruik ervan door de klant op de storefront.
Import en export
Definieer in B2B > Import/Export pas een profiel nadat de databron is vastgesteld. De profielconfiguratie is een JSON-object en moet bestandspaden bevatten die op de Magento-server toegankelijk zijn. Start eerst een import in testmodus en analyseer job en logs.
API-integraties
Bepaal vóór het aanmaken van een integratietoken de datascope en de eigenaar van de synchronisatie. Gebruik een aparte Magento-integratie voor elk ERP, PIM, WMS of middleware en geef alleen de benodigde B2B ACL. De volledige lijst van endpoints, tokens en beveiligingsregels staat in de API-documentatie voor integrators.
8. Acceptatiechecklist
Bevestig vóór productiegang:
- Kowal-modules zijn actief, cron werkt en cache en indexen zijn correct.
- B2B is uitsluitend voor de juiste website ingeschakeld.
- Het B2B-theme is uitsluitend aan de B2B store view toegewezen.
- Het testbedrijf heeft status Active, een gebruiker, rol, contact en standaardadressen.
- Het testproduct is actief, toegewezen aan de website, zichtbaar voor het bedrijf en heeft een correcte B2B-prijs.
- De klant kan inloggen, SKU zoeken, quick order gebruiken en het product aan de winkelwagen toevoegen.
- Checkout toont alleen toegestane verzend- en betaalmethoden.
- Limiet en goedkeuringsregel werken volgens het bedrijfsbeleid als deze functies worden gebruikt.
- Document en RFQ-PDF worden gegenereerd en zijn uitsluitend beschikbaar voor het juiste bedrijf.
- RFQ kan worden verzonden, geaccepteerd en doorgegeven aan het proces voor het aanmaken van een bestelling.
- Integraties hebben aparte tokens en beperkte ACL als ze worden gebruikt.
9. Meest voorkomende problemen
| Symptoom | Wat controleren |
|---|---|
| Er is geen B2B-menu | setup:upgrade, modulestatus, cache en ACL van de beheerder. |
| Bedrijf of klant ziet B2B niet | Of B2B actief is voor de juiste website en of het bedrijf een actieve relatie met die website heeft. |
| Product is niet zichtbaar of heeft geen prijs | Producttoewijzing aan website, actieve SKU, MSI-gegevens, catalogusregels, bedrijfsprijs, valuta en hoeveelheid. |
| Geen verzend- of betaalmethode | Standaard Magento-configuratie, scope van de B2B store view en B2B Checkout-regels. |
| PDF wordt niet gemaakt | Actieve PDF-template, mPDF-pakket, rechten op var/, verkopersgegevens en Magento-logs. |
| RFQ maakt bestelling niet automatisch aan | Standaardadressen van het bedrijf, eenduidige betaling en verzending; gebruik in overige gevallen Backend Order Create. |
API retourneert 403 | Het integratietoken heeft niet de vereiste ACL; gebruik geen beheertoken in een externe applicatie. |
Geef bij een supportmelding de Magento-versie, pakketversie, reproductiestappen, tijdstip van de gebeurtenis, veilig geanonimiseerde logs en eventuele trace_id door. Verstuur geen tokens of wachtwoorden.
10. Pakket bijwerken
- Lees de release-informatie die door Kowal is verstrekt.
- Voer de update eerst op een testomgeving uit.
- Maak een back-up, voer
composer update kowal/metapackage-b2b-suite --with-all-dependencies,bin/magento setup:upgradeuit en in productie ook DI-compilatie en deployment van statische assets. - Herhaal de acceptatiechecklist, met speciale aandacht voor prijzen, checkout, documenten en integraties.
Werk het pakket niet bij door bestanden handmatig naar app/code te kopiëren; dit veroorzaakt problemen met Composer en bemoeilijkt latere support.