Kowal B2B API — documentazione REST completa

Versione del contratto: V1 · Fonte di verità: Kowal_B2BApi/etc/webapi.xml · Destinatari: amministratori di shop, partner di implementazione e team che integrano ERP, PIM, WMS o sistemi di acquisto.

1. Finalità e limiti dell’API

Kowal B2B API espone dati e processi B2B operanti in Magento 2: aziende, catalogo e prezzi individuali, acquisti rapidi, documenti, limite di credito commerciale, approvazioni, RFQ e code di integrazione. È una REST API per integrazioni di sistema; non sostituisce gli endpoint Magento standard per catalogo, carrello, checkout e account cliente.

Il documento descrive solo gli endpoint attualmente esposti dal modulo. Non contiene promesse di operazioni non rese disponibili dal contratto V1, ad esempio creazione di ordini tramite REST, CRUD dei listini o modifica della configurazione website.

2. Ottenimento dell’accesso e regole di collaborazione

2.1. Processo di avvio dell’integrazione

1. L’integratore comunica all’amministratore dello shop obiettivo dell’integrazione, ambiente (test/produzione), sistema sorgente, ambito dei dati ed elenco delle aree API richieste.
2. L’amministratore crea o configura l’integrazione Magento, le assegna i permessi ACL minimi e trasmette tramite canale sicuro: baseUrl, token, websiteId, companyId (se applicabile), valuta e dati di test.
3. L’integratore esegue il test GET /V1/kowal-b2b/websites/:websiteId/config, quindi i test funzionali nell’ambiente di test.
4. Prima della produzione, entrambe le parti concordano calendario di sincronizzazione, dimensione massima dei dati, retry, proprietario dei dati e modalità di segnalazione degli errori.
5. I token sono conservati esclusivamente in un secret vault; l’amministratore li ruota o revoca in caso di cambio fornitore, utente o ambito dell’integrazione.

2.2. Responsabilità

Non usare il token amministratore in un’applicazione client né condividere un unico token tra sistemi indipendenti. Ogni integrazione dovrebbe avere il proprio token e solo le ACL richieste.

2.3. Permessi

Magento verifica il token Bearer e le ACL assegnate all’utente amministrativo o all’integrazione. Gli endpoint B2B richiedono uno dei seguenti gruppi di permessi:

L’ambito dovrebbe derivare dallo scopo dell’integrazione. Esempio: un sistema di acquisto di solito ha bisogno di products, prices, catalog_permissions, quick_order e quotes; un ERP che gestisce documenti — documents e, se è proprietario della sincronizzazione, system_integrations.

3. Convenzioni tecniche

Indirizzo, header e parametri

L’indirizzo base ha la forma https://b2b.example.com/rest/V1. Tutti i percorsi nel resto del documento sono indicati a partire da /V1; l’indirizzo completo dell’endpoint è BASE_URL + percorso.

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

L’API usa JSON. I nomi nell’URL sono in camelCase (websiteId, companyId) e i campi JSON corrispondono ai nomi dei parametri dei contratti Magento. :companyId, :quoteId, :sku ecc. sono parametri di percorso. Negli esempi ? indica un parametro opzionale.

websiteId è richiesto per le operazioni dipendenti dal canale di vendita. Deve indicare un website esistente con B2B abilitato. companyId indica l’azienda che deve avere una relazione attiva con quel website quando l’operazione opera nel suo contesto. L’API non seleziona un website né un’azienda predefiniti.

Request body e idempotenza

Magento serializza l’oggetto DTO sotto il nome del parametro del metodo: la maggior parte delle scritture accetta {'request': {...}}; la creazione di un’azienda usa {'company': {...}}; il batch di aziende — {'companies': [...]}. Gli endpoint con argomenti semplici accettano campi senza wrapper, ad es. {'websiteId': 1, 'currency': 'PLN', 'items': [...]}.

L’header Idempotency-Key (max 128 caratteri) è attualmente supportato da POST /companies: un retry con la stessa chiave restituirà l’azienda creata in precedenza. Per un job di integrazione usa il campo request.idempotencyKey. Non assumere idempotenza automatica per altri endpoint di scrittura; ripetili solo dopo aver determinato lo stato dell’operazione.

Risposte ed errori

Le risposte di successo sono oggetti o array dei contratti Magento. I campi restituiti dagli oggetti possono essere estesi in modo compatibile; l’integrazione dovrebbe ignorare i campi sconosciuti. Un errore business può contenere:

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

Non registrare token, dati personali completi o segreti di configurazione. La segnalazione al team dello shop dovrebbe includere ora, metodo, percorso senza segreti, stato HTTP, trace_id e payload anonimizzato.

4. Schemi dei dati di input

Gli schemi seguenti sono comuni agli endpoint di riferimento. Un campo senza ? è richiesto dal contratto; ? indica un valore opzionale. I campi metadata, config, configuration e payload sono oggetti JSON.

5. Riferimento degli endpoint

Nelle tabelle ACL indica la risorsa di permesso Magento minima. Risultato definisce il tipo di risposta di successo.

5.1. Websites e configurazione

5.2. Aziende e utenti aziendali

5.3. Prodotti, prezzo e visibilità del catalogo

5.4. Import ed export file-based

5.5. Ordine rapido e liste di acquisto

5.6. Documenti e file

5.7. Limite di credito commerciale e condizioni di pagamento

5.8. Workflow di approvazione

5.9. Contesto B2B degli ordini

5.10. RFQ e offerte commerciali

5.11. Profili e job di integrazione

6. Esempi di chiamate

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. Scenari di integrazione consigliati

Acquisto tramite SKU

1. Leggi la configurazione del website e salva websiteId, companyId e valuta trasmessi.
2. Usa quick order per la validazione aggregata di SKU, quantità, visibilità e disponibilità.
3. Per le righe accettate, recupera il prezzo da price con il qty corretto.
4. Crea un RFQ, aggiungi righe e inviale tramite submit se l’acquisto richiede un’offerta.
5. Monitora stato e storico del RFQ; dopo l’accettazione procedi secondo il processo di ordine Magento concordato, perché V1 non espone un endpoint di creazione order.

Documenti e rendicontazione

1. Scarica l’elenco dei documenti dell’azienda, opzionalmente filtrando per documentType.
2. Per il documento selezionato, scarica metadati ed elenco dei file; il percorso file non è automaticamente un URL pubblico — concorda con l’amministratore dello shop la modalità di download del binario.
3. Leggi lo stato del limite prima del processo di acquisto; solo un’integrazione con ACL credit_limits può gestirlo.

Operazioni asincrone

1. Salva profilo di integrazione e mappature degli identificatori.
2. Pubblica un job con idempotencyKey business e conserva jobId.
3. Leggi job e log/errori; richiama retry solo dopo aver analizzato l’errore e rimosso la causa.

8. Checklist di accettazione prima della produzione

• Il token ha solo le ACL richieste e non è un token amministratore usato dalla UI.
• L’integratore gestisce correttamente 401, 403, 404, validazione 422, conflitto 409 e timeout.
• Ogni request nel contesto B2B trasmette il websiteId corretto e i dati aziendali usano il companyId corretto.
• Prezzi, visibilità e disponibilità vengono verificati prima di creare il processo di acquisto.
• La creazione dell’azienda usa Idempotency-Key; i job di integrazione hanno un idempotencyKey stabile nel body.
• I log non contengono token né dati sensibili e la procedura di supporto trasmette trace_id.
• I test sono stati eseguiti nell’ambiente di test su un’azienda che ha una relazione attiva con il B2B website.

9. Compatibilità

Il contratto è versionato tramite /V1. L’estensione della risposta con nuovi campi è compatibile; l’integratore dovrebbe tollerare campi sconosciuti. Una modifica che rimuove un campo, il significato di un campo o un endpoint richiede una nuova versione dell’API. In caso di discrepanza tra il documento e l’installazione attiva, fa fede il contratto attivo webapi.xml della versione del modulo.

Installazione e configurazione di Kowal B2B Suite

Questo manuale è destinato alla persona che ha acquistato Kowal B2B Suite e deve avviarlo in un’installazione Magento Open Source esistente. Guida attraverso due fasi:

1. installazione tecnica — eseguita da uno sviluppatore o da un amministratore server;
2. configurazione business — eseguita nel pannello Magento dall’amministratore dello shop.

Prima di iniziare, esegui una copia del database e dei file Magento. Consigliamo di effettuare il primo avvio in un ambiente di test e solo successivamente di implementarlo in produzione.

1. Cosa ricevi e di cosa hai bisogno

Kowal B2B Suite viene fornito come pacchetto Composer kowal/metapackage-b2b-suite. Contiene i moduli B2B e il theme frontend/Kowal/b2b.

Requisiti

Da Kowal riceverai:

• indirizzo del repository Composer privato — di seguito come REPOSITORY_URL;
• nome utente o identificatore di accesso — USERNAME;
• token di accesso — ACCESS_TOKEN;
• intervallo di versioni consentito del pacchetto.

Non salvare il token nel repository Git, nei ticket o nella cronologia della shell condivisa con altre persone.

2. Installazione tecnica

Esegui tutti i comandi nella directory principale dell’installazione Magento esistente, come utente con accesso ai file e al comando bin/magento.

2.1. Preparazione

1. Assicurati che Magento funzioni correttamente prima della modifica.
2. Registra lo stato del deployment ed esegui un backup del database e delle directory app/etc, pub/media e var.
3. In produzione, abilita la modalità maintenance durante l’aggiornamento:

bin/magento maintenance:enable

2.2. Aggiunta del repository privato

Aggiungi il repository Composer Kowal e configura le credenziali ricevute.

Riceverai via e-mail dopo l’acquisto i dati di accesso al repository Composer (indirizzo e-mail del cliente e token di licenza). Sono disponibili anche nel pannello cliente dopo l’accesso a kowal.store. Sostituisci TWOJ_EMAIL_KLIENTA con l’indirizzo e-mail del tuo account e TWOJ_TOKEN con il token ricevuto. Esegui i comandi nella directory principale di Magento.

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

Composer di solito salva le credenziali nel file locale auth.json; non aggiungere questo file a Git.

2.3. Installazione del pacchetto

Installa la versione fornita insieme alla licenza. Per la linea corrente del pacchetto, un comando di esempio è:

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

Dopo aver scaricato le dipendenze, esegui l’aggiornamento dello schema e della configurazione Magento:

bin/magento setup:upgradebin/magento cache:clean

In modalità produzione esegui inoltre:

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

Usa solo i locale attivi nello shop. Se l’installazione utilizza un processo di deployment diverso, includi i comandi sopra nella sua procedura standard.

2.4. Verifica dell’installazione

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

Nel pannello di amministrazione dovrebbe comparire il menu B2B e la scheda Stores > Configuration > Kowal > B2B. Se non sono presenti, controlla il risultato di setup:upgrade, la cache e i ruoli ACL dell’utente amministratore.

2.5. Permessi dei file PDF

I PDF generati dal B2B usano mPDF e directory sotto var/, tra cui var/tmp/kowal_b2b_mpdf e var/kowal_b2b_documents. Il processo PHP deve poterle creare e scrivere. La mancanza di questi permessi si manifesta con un errore di generazione del documento o del PDF.

Al termine del deployment in produzione, disabilita la maintenance:

bin/magento maintenance:disable

3. Configurazione della struttura dello shop B2B

3.1. Website e store view

La suite opera nell’ambito website, non globalmente. Puoi gestire B2C e B2B nella stessa installazione Magento, ma il B2B dovrebbe funzionare in un website separato o in un website di vendita aziendale scelto consapevolmente.

1. In Stores > Settings > All Stores crea o seleziona il website B2B, il relativo store e store view.
2. Ricorda il website_id — viene utilizzato da aziende, prezzi, documenti, API e integrazioni.
3. In Content > Design > Configuration assegna il theme frontend/Kowal/b2b solo alla B2B store view.
4. Verifica che valute attive, imposte, metodi di spedizione e metodi di pagamento siano configurati per lo stesso scope.

Non assegnare il theme B2B alla store view B2C se non vuoi modificarne il livello di presentazione. La semplice installazione dei moduli non abilita la logica B2B per tutti i website.

3.2. Attivazione del B2B

1. Apri Stores > Configuration > Kowal > B2B.
2. Nel selettore scope scegli il Website corretto.
3. Nella sezione General imposta Enable B2B su Yes.
4. Durante l’implementazione puoi abilitare Debug Mode; disabilitalo dopo i test.
5. Nello scope Default Config imposta il periodo di retention dei log.
6. Salva la configurazione e pulisci la cache.

Dopo l’attivazione, tutte le store view appartenenti a questo website vengono trattate come B2B. Un’azienda senza una relazione attiva con questo website non potrà accedervi.

3.3. Dati del venditore

Completa i dati dell’azienda venditrice in Stores > Configuration > General > Store Information: nome, indirizzo, telefono e partita IVA/codice fiscale. Sono usati nei documenti e nei PDF RFQ. Completa anche l’indirizzo e-mail generale del mittente nella configurazione Sales Emails e il logo e-mail, se deve comparire nei PDF.

4. Configurazione del primo cliente B2B

Applica la seguente sequenza per ogni azienda. Permette di evitare una situazione in cui il cliente ha un account ma non vede l’offerta o non può procedere al checkout.

4.1. Azienda, persone e indirizzi

1. Apri B2B > Companies e crea un’azienda.
2. Inserisci nome, partita IVA/codice fiscale, identificatore esterno (se l’azienda è sincronizzata con ERP), stato Active e assegnazione al B2B website.
3. Aggiungi un utente dell’azienda o assegna un cliente Magento esistente. Assegnagli il ruolo corretto e attiva l’assegnazione.
4. In B2B > Company Addresses aggiungi gli indirizzi dell’azienda; contrassegna l’indirizzo di fatturazione e di spedizione predefinito per il website B2B.
5. In B2B > Company Contacts aggiungi un contatto principale attivo con e-mail e telefono.

L’indirizzo di fatturazione e il contatto principale sono usati anche nei PDF RFQ. La mancanza di dati non blocca il PDF, ma il documento sarà meno completo.

4.2. Ruoli aziendali

Assegna agli utenti solo le autorizzazioni necessarie. Una suddivisione tipica è:

Testa l’account di ogni tipo, soprattutto il permesso di inviare ordini e approvazioni. Non usare un unico account condiviso per tutta l’azienda.

5. Offerta, prezzi e checkout

5.1. Catalogo e prezzi

1. Assicurati che i prodotti Magento siano assegnati al B2B website, attivi e con dati MSI corretti.
2. Configura listini o prezzi contrattuali per l’azienda nell’area B2B > Pricing (Price Lists, Price List Assignments o Contract Prices).
3. Configura le regole di visibilità del catalogo per l’azienda secondo il modello di autorizzazioni implementato, quindi verifica la visibilità sull’account cliente.
4. Testa sull’account aziendale: ricerca SKU, visibilità del prodotto e prezzo per quantità 1 e per soglia quantitativa.

Il prezzo B2B dipende da azienda, website, valuta e quantità. Un prodotto visibile in B2C non deve necessariamente essere disponibile per il cliente B2B.

5.2. Spedizione e pagamento

1. Abilita i metodi di spedizione e pagamento richiesti nella configurazione standard Magento per la B2B store view.
2. In B2B > Checkout aggiungi regole dei metodi disponibili per azienda/website, se vuoi limitarne la scelta.
3. Esegui un test del carrello sugli indirizzi predefiniti dell’azienda.

Se la creazione dell’ordine da RFQ deve funzionare automaticamente lato amministratore, l’azienda deve avere indirizzi predefiniti univoci, un metodo di pagamento e di spedizione attivo. In caso contrario la suite caricherà i dati nel Backend Order Create nativo, dove l’amministratore completa gli elementi mancanti.

5.3. Limiti e approvazioni

Queste funzionalità sono opzionali, ma dovrebbero essere configurate prima di abilitarle per i clienti.

1. In B2B > Credit > Payment Terms aggiungi le condizioni di pagamento.
2. In B2B > Credit > Credit Limits assegna all’azienda limite, valuta, stato e termine di pagamento.
3. In B2B > Approvals > Rules crea una regola di soglia importo per azienda e website.
4. In B2B > Approvals > Approvers assegna le persone approvatrici.
5. Testa il carrello sotto e sopra la soglia e verifica se la decisione dell’approvatore modifica il processo successivo.

6. Documenti, PDF e RFQ

6.1. Documenti Magento

In Stores > Configuration > Kowal > B2B > Documents scegli la fonte dei documenti e decidi quali documenti devono essere generati automaticamente: conferme d’ordine, fatture, documenti di consegna e note di credito. Imposta anche lo stato di destinazione del documento.

In B2B > Documents > PDF Templates:

1. verifica il template attivo per ogni tipo e website;
2. esegui l’anteprima;
3. adatta HTML/CSS solo se hai una persona che conosce i template Magento e CSS mPDF;
4. genera una fattura o una conferma di test e verifica il download dall’account aziendale.

6.2. RFQ e offerta PDF

1. In B2B > Quotes > RFQ crea un RFQ di test per un’azienda e un utente attivi.
2. Aggiungi SKU visibili per l’azienda, quantità e prezzo offerto.
3. Imposta la data di validità, invia l’offerta al cliente e genera il PDF.
4. Verifica la variante cliente: dati venditore/acquirente, righe, prezzo, totale e data di validità.
5. Verifica la variante amministratore: inoltre note commerciali, commenti, storico e informazioni interne sulle righe.

Il PDF cliente non può contenere note del commerciale né storico interno degli stati.

7. Ordini rapidi, import e integrazioni

Ordini rapidi

In B2B > Quick Order > Debug SKU verifica la lista SKU,qty per azienda, website e valuta. Quindi crea una lista di acquisto e testane l’uso da parte del cliente sullo storefront.

Import ed export

In B2B > Import/Export definisci un profilo solo dopo aver stabilito la fonte dati. La configurazione del profilo è un oggetto JSON e deve contenere percorsi file accessibili sul server Magento. Esegui prima l’import in modalità test e analizza job e log.

Integrazioni API

Prima di creare un token di integrazione, definisci l’ambito dei dati e il proprietario della sincronizzazione. Usa un’integrazione Magento separata per ogni ERP, PIM, WMS o middleware e assegnale solo le ACL B2B necessarie. L’elenco completo di endpoint, token e regole di sicurezza si trova nella documentazione API per integratori.

8. Checklist di accettazione

Prima dell’avvio in produzione conferma che:

• I moduli Kowal sono attivi, cron funziona e cache e indici sono corretti.
• Il B2B è abilitato esclusivamente per il website corretto.
• Il theme B2B è assegnato esclusivamente alla B2B store view.
• L’azienda di test ha stato Active, utente, ruolo, contatto e indirizzi predefiniti.
• Il prodotto di test è attivo, assegnato al website, visibile per l’azienda e ha un prezzo B2B corretto.
• Il cliente può accedere, cercare SKU, usare quick order e aggiungere il prodotto al carrello.
• Il checkout mostra solo i metodi di spedizione e pagamento consentiti.
• Il limite e la regola di approvazione funzionano secondo la policy aziendale, se queste funzionalità sono usate.
• Il documento e il PDF RFQ vengono generati e sono disponibili solo per l’azienda corretta.
• Il RFQ può essere inviato, accettato e trasferito al processo di creazione dell’ordine.
• Le integrazioni hanno token separati e ACL limitate, se usate.

9. Problemi più comuni

Quando contatti il supporto, indica versione Magento, versione del pacchetto, passaggi per riprodurre il problema, ora dell’evento, log anonimizzati in modo sicuro ed eventuale trace_id. Non inviare token né password.

10. Aggiornamento del pacchetto

1. Consulta le informazioni di versione fornite da Kowal.
2. Esegui prima l’aggiornamento in ambiente di test.
3. Esegui un backup, composer update kowal/metapackage-b2b-suite --with-all-dependencies, bin/magento setup:upgrade e in produzione anche compilazione DI e deployment degli asset statici.
4. Ripeti la checklist di accettazione, con particolare attenzione a prezzi, checkout, documenti e integrazioni.

Non aggiornare il pacchetto copiando manualmente i file in app/code; questo causa problemi con Composer e rende più difficile il supporto successivo.