Kowal B2B API — documentație REST completă

Versiunea contractului: V1 · Sursa de adevăr: Kowal_B2BApi/etc/webapi.xml · Destinatari: administratori de magazine, parteneri de implementare și echipe care integrează ERP, PIM, WMS sau un sistem de achiziții.

1. Scopul și limitele API

Kowal B2B API pune la dispoziție date și procese B2B care funcționează în Magento 2: companii, catalog și prețuri individuale, cumpărături rapide, documente, limită de credit comercial, aprobări, RFQ și cozi de integrare. Este un REST API pentru integrări de sistem; nu înlocuiește endpointurile standard Magento pentru catalog, coș, checkout și contul clientului.

Documentul descrie exclusiv endpointurile expuse în prezent de modul. Nu promite operațiuni pe care contractul V1 nu le oferă, de exemplu crearea unei comenzi prin REST, CRUD pentru liste de prețuri sau editarea configurației website.

2. Obținerea accesului și reguli de colaborare

2.1. Procesul de lansare a integrării

1. Integratorul transmite administratorului magazinului scopul integrării, mediul (test/producție), sistemul sursă, domeniul datelor și lista zonelor API necesare.
2. Administratorul creează sau configurează integrarea Magento, îi atribuie permisiuni ACL minime și transmite printr-un canal sigur: baseUrl, tokenul, websiteId, companyId (dacă se aplică), moneda și datele de test.
3. Integratorul execută testul GET /V1/kowal-b2b/websites/:websiteId/config, apoi teste funcționale pe mediul de test.
4. Înainte de producție, ambele părți stabilesc programul de sincronizare, dimensiunea maximă a datelor, retry, proprietarul datelor și modul de raportare a erorilor.
5. Tokenurile sunt păstrate exclusiv într-un seif de secrete; administratorul le rotește sau le retrage la schimbarea furnizorului, utilizatorului ori domeniului integrării.

2.2. Responsabilități

Nu folosi tokenul administratorului într-o aplicație client și nu partaja un singur token între sisteme independente. Fiecare integrare ar trebui să aibă propriul token și doar ACL necesare.

2.3. Permisiuni

Magento verifică tokenul Bearer și ACL atribuite utilizatorului administrativ sau integrării. Endpointurile B2B necesită una dintre următoarele grupe de permisiuni:

Domeniul trebuie să rezulte din scopul integrării. Exemplu: un sistem de achiziții are de obicei nevoie de products, prices, catalog_permissions, quick_order și quotes; un ERP care gestionează documente — documents și, dacă este proprietarul sincronizării, system_integrations.

3. Convenții tehnice

Adresă, headere și parametri

Adresa de bază are forma https://b2b.example.com/rest/V1. Toate căile de mai jos din document sunt indicate de la /V1; adresa completă a endpointului este BASE_URL + calea.

Authorization: Bearer Accept: application/jsonContent-Type: application/json

API folosește JSON. Numele din URL sunt camelCase (websiteId, companyId), iar câmpurile JSON corespund numelor parametrilor contractelor Magento. :companyId, :quoteId, :sku etc. sunt parametri de cale. În exemple, ? marchează un parametru opțional.

websiteId este necesar pentru operațiile dependente de canalul de vânzare. Trebuie să indice un website existent cu B2B activat. companyId indică o companie care trebuie să aibă o relație activă cu acel website când operația funcționează în contextul ei. API nu alege implicit website-ul sau compania.

Request body și idempotency

Magento serializează obiectul DTO sub numele parametrului metodei: majoritatea scrierilor acceptă {'request': {...}}; crearea companiei folosește {'company': {...}}; batch-ul de companii — {'companies': [...]}. Endpointurile cu argumente simple acceptă câmpuri fără wrapper, de exemplu {'websiteId': 1, 'currency': 'PLN', 'items': [...]}.

Headerul Idempotency-Key (max. 128 de caractere) este acceptat în prezent de POST /companies: reluarea cu aceeași cheie va returna compania creată anterior. Pentru jobul de integrare folosește câmpul request.idempotencyKey. Nu presupune idempotency automată pentru alte endpointuri de scriere; reia-le doar după stabilirea statusului operației.

Răspunsuri și erori

Răspunsurile de succes sunt obiecte sau tablouri ale contractelor Magento. Câmpurile returnate de obiecte pot fi extinse compatibil; integrarea ar trebui să ignore câmpurile necunoscute. O eroare de business poate conține:

{ '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': []}

Nu loga tokenuri, date personale complete sau secrete de configurare. Raportarea către echipa magazinului ar trebui să includă timpul, metoda, calea fără secrete, statusul HTTP, trace_id și payloadul anonimizat.

4. Scheme de date de intrare

Schemele de mai jos sunt comune endpointurilor de referință. Câmpul fără ? este cerut de contract; ? înseamnă valoare opțională. Câmpurile metadata, config, configuration și payload sunt obiecte JSON.

5. Referință endpointuri

În tabele, ACL indică resursa minimă de permisiune Magento. Rezultat definește tipul răspunsului de succes.

5.1. Websites și configurare

5.2. Companii și utilizatori de companie

5.3. Produse, preț și vizibilitatea catalogului

5.4. Import și export pe fișiere

5.5. Comandă rapidă și liste de cumpărături

5.6. Documente și fișiere

5.7. Limită de credit comercial și termene de plată

5.8. Workflow de aprobare

5.9. Context B2B al comenzilor

5.10. RFQ și oferte comerciale

5.11. Profile și joburi de integrare

6. Exemple de apeluri

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&currency=$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. Scenarii de integrare recomandate

Achiziție după SKU

1. Citește configurarea website-ului și salvează websiteId, companyId și moneda transmise.
2. Folosește quick order pentru validarea colectivă a SKU, cantității, vizibilității și disponibilității.
3. Pentru pozițiile acceptate, preia prețul din price cu qty corespunzător.
4. Creează RFQ, adaugă pozițiile și trimite-le prin submit, dacă achiziția necesită ofertă.
5. Urmărește statusul și istoricul RFQ; după acceptare, urmează procesul de comandă Magento convenit, deoarece V1 nu expune endpoint de creare order.

Documente și decontări

1. Preia lista documentelor companiei, filtrând opțional după documentType.
2. Pentru documentul selectat, preia metadatele și lista de fișiere; calea fișierului nu este automat un URL public — modul de descărcare a binarului trebuie convenit cu administratorul magazinului.
3. Citește statusul limitei înaintea procesului de achiziție; doar integrarea cu ACL credit_limits o poate gestiona.

Operații asincrone

1. Salvează profilul de integrare și mapările identificatorilor.
2. Publică jobul cu idempotencyKey de business și păstrează jobId.
3. Citește jobul și logurile/erorile; apelează retry doar după analiza erorii și eliminarea cauzei acesteia.

8. Listă de recepție înainte de producție

• Tokenul are doar ACL necesare și nu este tokenul administratorului folosit de UI.
• Integratorul gestionează corect 401, 403, 404, validarea 422, conflictul 409 și timeouturile.
• Fiecare request în context B2B transmite websiteId corect, iar datele companiei folosesc companyId valid.
• Prețurile, vizibilitatea și disponibilitatea sunt verificate înainte de crearea procesului de achiziție.
• Crearea companiei folosește Idempotency-Key; joburile de integrare au un idempotencyKey stabil în body.
• Logurile nu conțin tokenuri sau date sensibile, iar procedura de suport transmite trace_id.
• Testele au fost efectuate pe mediul de testare pe o companie care are o relație activă cu website-ul B2B.

9. Compatibilitate

Contractul este versionat prin /V1. Extinderea răspunsului cu câmpuri noi este compatibilă; integratorul ar trebui să tolereze câmpurile necunoscute. O modificare care elimină un câmp, semnificația unui câmp sau un endpoint necesită o nouă versiune API. În caz de diferențe între document și instalarea funcțională, contractul activ webapi.xml al versiunii respective a modulului este cel obligatoriu.

Instalarea și configurarea Kowal B2B Suite

Acest manual este destinat persoanei care a cumpărat Kowal B2B Suite și trebuie să îl pornească într-o instalare Magento Open Source existentă. Te ghidează prin două etape:

1. instalarea tehnică — realizată de un developer sau administrator de server;
2. configurarea de business — realizată în panoul Magento de administratorul magazinului.

Înainte de a începe, fă o copie a bazei de date și a fișierelor Magento. Recomandăm ca prima pornire să fie efectuată pe un mediu de testare, iar abia apoi implementată în producție.

1. Ce primești și de ce ai nevoie

Kowal B2B Suite este livrat ca pachet Composer kowal/metapackage-b2b-suite. Conține module B2B și tema frontend/Kowal/b2b.

Cerințe

De la Kowal vei primi:

• adresa repository-ului privat Composer — în continuare REPOSITORY_URL;
• numele de utilizator sau identificatorul de acces — USERNAME;
• tokenul de acces — ACCESS_TOKEN;
• intervalul permis de versiuni ale pachetului.

Nu salva tokenul în repository-ul Git, în tickete sau în istoricul shell-ului partajat cu alte persoane.

2. Instalare tehnică

Execută toate comenzile în directorul rădăcină al instalării Magento existente, ca utilizator care are acces la fișiere și la comanda bin/magento.

2.1. Pregătire

1. Asigură-te că Magento funcționează corect înainte de modificare.
2. Salvează starea implementării și fă backup bazei de date și directoarelor app/etc, pub/media și var.
3. În producție, activează modul maintenance pe durata actualizării:

bin/magento maintenance:enable

2.2. Adăugarea repository-ului privat

Adaugă repository-ul Composer Kowal și configurează datele de acces primite.

Datele de acces la repository-ul Composer (adresa de e-mail a clientului și tokenul de licență) le vei primi prin e-mail după achiziție. Sunt disponibile și în panoul clientului după autentificare pe kowal.store. Înlocuiește TWOJ_EMAIL_KLIENTA cu adresa de e-mail a contului tău, iar TWOJ_TOKEN cu tokenul primit. Execută comenzile în directorul rădăcină Magento.

composer config repositories.kowal composer https://repo.kowal.storecomposer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'

Composer salvează de obicei credențialele în fișierul local auth.json; nu adăuga acest fișier în Git.

2.3. Instalarea pachetului

Instalează versiunea transmisă împreună cu licența. Pentru linia curentă a pachetului, comanda exemplu este:

composer require kowal/metapackage-b2b-suite:^0.2 --with-all-dependencies

După descărcarea dependențelor, execută actualizarea schemei și configurării Magento:

bin/magento setup:upgradebin/magento cache:clean

În modul producție, execută suplimentar:

bin/magento setup:di:compilebin/magento setup:static-content:deploy -f pl_PL en_USbin/magento cache:flush

Folosește doar acele locale care sunt active în magazin. Dacă instalarea folosește un alt proces de deployment, include comenzile de mai sus în procedura sa standard.

2.4. Verificarea instalării

bin/magento module:status | grep Kowalbin/magento indexer:status

În panoul de administrare ar trebui să apară meniul B2B și fila Stores > Configuration > Kowal > B2B. Dacă lipsesc, verifică rezultatul setup:upgrade, cache-ul și rolurile ACL ale utilizatorului administrator.

2.5. Permisiuni pentru fișiere PDF

PDF-urile generate de B2B folosesc mPDF și directoare din var/, inclusiv var/tmp/kowal_b2b_mpdf și var/kowal_b2b_documents. Procesul PHP trebuie să le poată crea și scrie. Lipsa acestor permisiuni se manifestă prin eroare la generarea documentului sau PDF-ului.

După finalizarea implementării în producție, dezactivează maintenance:

bin/magento maintenance:disable

3. Configurarea structurii magazinului B2B

3.1. Website și store view

Suite funcționează la nivel de website, nu global. Poți opera B2C și B2B în aceeași instalare Magento, însă B2B ar trebui să funcționeze într-un website separat sau într-un website de vânzare către companii ales în mod conștient.

1. În Stores > Settings > All Stores creează sau selectează website-ul B2B, store-ul și store view-ul acestuia.
2. Reține website_id — este folosit de companii, prețuri, documente, API și integrări.
3. În Content > Design > Configuration atribuie tema frontend/Kowal/b2b doar store view-ului B2B.
4. Verifică dacă monedele active, taxele, metodele de livrare și metodele de plată sunt configurate pentru același scope.

Nu atribui tema B2B unui store view B2C dacă nu vrei să îi schimbi stratul de prezentare. Simpla instalare a modulelor nu activează logica B2B pentru toate website-urile.

3.2. Activarea B2B

1. Deschide Stores > Configuration > Kowal > B2B.
2. În selectorul de scope alege Website-ul corespunzător.
3. În secțiunea General setează Enable B2B la Yes.
4. Pe durata implementării poți activa Debug Mode; dezactivează-l după teste.
5. În scope Default Config setează perioada de retenție a logurilor.
6. Salvează configurația și curăță cache-ul.

După activare, toate store view-urile care aparțin acelui website sunt tratate ca B2B. O companie fără o relație activă cu acest website nu va obține acces la el.

3.3. Datele vânzătorului

Completează datele companiei vânzătoare în Stores > Configuration > General > Store Information: nume, adresă, telefon și cod fiscal. Sunt folosite în documente și în PDF RFQ. Completează și adresa generală de e-mail a expeditorului în configurarea Sales Emails și logo-ul de e-mail, dacă trebuie să apară în PDF.

4. Configurarea primului client B2B

Folosește ordinea de mai jos pentru fiecare companie. Ajută la evitarea situației în care clientul are cont, dar nu vede oferta sau nu poate trece prin checkout.

4.1. Companie, persoane și adrese

1. Deschide B2B > Companies și creează compania.
2. Introdu numele, codul fiscal, identificatorul extern (dacă firma este sincronizată cu ERP), statusul Active și atribuirea la website-ul B2B.
3. Adaugă utilizatorul companiei sau atribuie un client Magento existent. Acordă-i rolul potrivit și activează atribuirea.
4. În B2B > Company Addresses adaugă adresele companiei; marchează adresa implicită de facturare și de livrare pentru website-ul B2B.
5. În B2B > Company Contacts adaugă un contact principal activ, cu e-mail și telefon.

Adresa de facturare și contactul principal sunt folosite și în PDF RFQ. Lipsa datelor nu blochează PDF-ul, dar documentul va fi mai puțin complet.

4.2. Roluri de companie

Acordă utilizatorilor doar permisiunile necesare. O împărțire tipică este:

Testează contul fiecărui tip, mai ales permisiunea de plasare a comenzilor și de aprobare. Nu folosi un singur cont comun pentru întreaga companie.

5. Oferta, prețuri și checkout

5.1. Catalog și prețuri

1. Asigură-te că produsele Magento sunt atribuite website-ului B2B, sunt active și au date MSI corecte.
2. Configurează listele de prețuri sau prețurile contractuale pentru companie în zona B2B > Pricing (Price Lists, Price List Assignments sau Contract Prices).
3. Configurează regulile de vizibilitate a catalogului pentru companie conform modelului de permisiuni implementat, apoi verifică vizibilitatea în contul clientului.
4. Testează în contul companiei: căutarea SKU, vizibilitatea produsului și prețul pentru cantitatea 1 și pentru pragul cantitativ.

Prețul B2B depinde de companie, website, monedă și cantitate. Un produs vizibil în B2C nu trebuie neapărat să fie disponibil pentru clientul B2B.

5.2. Livrare și plată

1. Activează metodele necesare de livrare și plată în configurarea standard Magento pentru B2B store view.
2. În B2B > Checkout adaugă reguli pentru metodele disponibile pentru companie/website, dacă vrei să limitezi opțiunile.
3. Efectuează un test de coș pe adresele implicite ale companiei.

Dacă crearea comenzii din RFQ trebuie să funcționeze automat din partea administratorului, compania trebuie să aibă adrese implicite clare, metodă activă de plată și de livrare. În caz contrar, Suite va încărca datele în Backend Order Create nativ, unde administratorul completează elementele lipsă.

5.3. Limite și aprobări

Aceste funcții sunt opționale, dar ar trebui configurate înainte de a fi activate pentru clienți.

1. În B2B > Credit > Payment Terms adaugă termenele de plată.
2. În B2B > Credit > Credit Limits atribuie companiei limita, moneda, statusul și termenul de plată.
3. În B2B > Approvals > Rules creează regula pragului valoric pentru companie și website.
4. În B2B > Approvals > Approvers atribuie persoanele aprobatoare.
5. Testează coșul sub și peste prag și verifică dacă decizia aprobatorului schimbă procesul ulterior.

6. Documente, PDF și RFQ

6.1. Documente Magento

În Stores > Configuration > Kowal > B2B > Documents alege sursa documentelor și decide ce documente trebuie generate automat: confirmări de comandă, facturi, avize de livrare și corecții. Setează și statusul țintă al documentului.

În B2B > Documents > PDF Templates:

1. verifică șablonul activ pentru fiecare tip și website;
2. fă previzualizarea;
3. adaptează HTML/CSS doar dacă ai o persoană care cunoaște șabloanele Magento și CSS mPDF;
4. generează o factură sau o confirmare de test și verifică descărcarea din contul companiei.

6.2. RFQ și ofertă PDF

1. În B2B > Quotes > RFQ creează un RFQ de test pentru o companie și un utilizator activ.
2. Adaugă SKU vizibile pentru companie, cantitatea și prețul ofertat.
3. Setează termenul de valabilitate, trimite oferta clientului și generează PDF.
4. Verifică varianta pentru client: datele vânzătorului/cumpărătorului, pozițiile, prețul, totalul și termenul de valabilitate.
5. Verifică varianta administratorului: suplimentar notele comerciale, comentariile, istoricul și informațiile interne despre poziții.

PDF-ul clientului nu poate conține notele agentului de vânzări sau istoricul intern al statusurilor.

7. Comenzi rapide, importuri și integrări

Comenzi rapide

În B2B > Quick Order > Debug SKU verifică lista SKU,qty pentru companie, website și monedă. Apoi creează o listă de cumpărături și testează utilizarea ei de către client pe storefront.

Import și export

În B2B > Import/Export definește profilul numai după stabilirea sursei de date. Configurarea profilului este un obiect JSON și trebuie să conțină căi de fișiere disponibile pe serverul Magento. Mai întâi rulează importul în modul de test și analizează jobul și logurile.

Integrări API

Înainte de a crea tokenul de integrare, stabilește domeniul datelor și proprietarul sincronizării. Folosește o integrare Magento separată pentru fiecare ERP, PIM, WMS sau middleware și acordă-i doar ACL B2B necesare. Lista completă de endpointuri, tokenuri și reguli de securitate se află în documentația API pentru integratori.

8. Checklist de recepție

Înainte de lansarea în producție confirmă:

• Modulele Kowal sunt active, cron funcționează, iar cache-ul și indecșii sunt corecți.
• B2B este activat exclusiv pentru website-ul corect.
• Tema B2B este atribuită exclusiv store view-ului B2B.
• Compania de test are status Active, utilizator, rol, contact și adrese implicite.
• Produsul de test este activ, atribuit website-ului, vizibil pentru companie și are preț B2B corect.
• Clientul se poate autentifica, poate căuta SKU, poate folosi quick order și poate adăuga produsul în coș.
• Checkout-ul afișează doar metodele de livrare și plată permise.
• Limita și regula de aprobare funcționează conform politicii companiei, dacă aceste funcții sunt folosite.
• Documentul și PDF RFQ se generează și sunt disponibile exclusiv pentru compania corectă.
• RFQ poate fi trimis, acceptat și transmis către procesul de creare a comenzii.
• Integrările au tokenuri separate și ACL limitate, dacă sunt folosite.

9. Cele mai frecvente probleme

La raportarea către suport, furnizează versiunea Magento, versiunea pachetului, pașii de reproducere, ora evenimentului, loguri anonimizate în siguranță și eventualul trace_id. Nu trimite tokenuri sau parole.

10. Actualizarea pachetului

1. Consultă informațiile despre versiune transmise de Kowal.
2. Execută actualizarea mai întâi pe mediul de testare.
3. Fă backup, composer update kowal/metapackage-b2b-suite --with-all-dependencies, bin/magento setup:upgrade, iar în producție și compilarea DI și deployment-ul resurselor statice.
4. Repetă checklist-ul de recepție, cu accent special pe prețuri, checkout, documente și integrări.

Nu actualiza pachetul prin copiere manuală de fișiere în app/code; acest lucru provoacă probleme cu Composer și îngreunează suportul ulterior.