Kowal B2B API — pełna dokumentacja REST

Wersja kontraktu: V1 · Źródło prawdy: Kowal_B2BApi/etc/webapi.xml · Odbiorcy: administratorzy sklepów, partnerzy wdrożeniowi i zespoły integrujące ERP, PIM, WMS lub system zakupowy.

1. Przeznaczenie i granice API

Kowal B2B API udostępnia dane i procesy B2B działające w Magento 2: firmy, katalog i ceny indywidualne, szybkie zakupy, dokumenty, limit kupiecki, akceptacje, RFQ oraz kolejki integracyjne. Jest to REST API do integracji systemowych; nie zastępuje standardowych endpointów Magento dla katalogu, koszyka, checkoutu i konta klienta.

Dokument opisuje wyłącznie endpointy aktualnie wystawione przez moduł. Brak w nim obietnicy operacji, których kontrakt V1 nie udostępnia, np. tworzenia zamówienia przez REST, CRUD cenników lub edycji konfiguracji website.

2. Uzyskanie dostępu i zasady współpracy

2.1. Proces uruchomienia integracji

1. Integrator przekazuje administratorowi sklepu cel integracji, środowisko (test/produkcja), system źródłowy, zakres danych oraz listę wymaganych obszarów API.
2. Administrator zakłada lub konfiguruje integrację Magento, przypisuje jej minimalne uprawnienia ACL i przekazuje bezpiecznym kanałem: baseUrl, token, websiteId, companyId (gdy dotyczy), walutę oraz dane testowe.
3. Integrator wykonuje test GET /V1/kowal-b2b/websites/:websiteId/config, a następnie testy funkcjonalne na środowisku testowym.
4. Przed produkcją obie strony uzgadniają harmonogram synchronizacji, maksymalny rozmiar danych, retry, właściciela danych i sposób zgłaszania błędów.
5. Tokeny są przechowywane wyłącznie w sejfie sekretów; administrator rotuje lub odbiera je przy zmianie dostawcy, użytkownika albo zakresu integracji.

2.2. Odpowiedzialności

Nie należy używać tokenu administratora w aplikacji klienckiej ani współdzielić jednego tokenu przez niezależne systemy. Każda integracja powinna mieć własny token i wyłącznie wymagane ACL.

2.3. Uprawnienia

Magento weryfikuje token Bearer oraz ACL przypisane do użytkownika administracyjnego lub integracji. Endpointy B2B wymagają jednej z poniższych grup uprawnień:

Zakres powinien wynikać z przeznaczenia integracji. Przykład: system zakupowy zwykle potrzebuje products, prices, catalog_permissions, quick_order i quotes; ERP obsługujący dokumenty — documents oraz, jeśli jest właścicielem synchronizacji, system_integrations.

3. Konwencje techniczne

Adres, nagłówki i parametry

Adres bazowy ma postać https://b2b.example.com/rest/V1. Wszystkie ścieżki dalej w dokumencie są podawane od /V1; pełny adres endpointu to BASE_URL + ścieżka.

Authorization: Bearer <token>
Accept: application/json
Content-Type: application/json

API używa JSON. Nazwy w URL są camelCase (websiteId, companyId), a pola JSON odpowiadają nazwom parametrów kontraktów Magento. :companyId, :quoteId, :sku itd. to parametry ścieżki. W przykładach ? oznacza parametr opcjonalny.

websiteId jest wymagany przy operacjach zależnych od kanału sprzedaży. Musi wskazywać istniejący website z włączonym B2B. companyId wskazuje firmę, która musi mieć aktywną relację z tym website, gdy operacja działa w jej kontekście. API nie wybiera domyślnego website ani firmy.

Request body i idempotencja

Magento serializuje obiekt DTO pod nazwą parametru metody: większość zapisów przyjmuje {"request": {...}}; tworzenie firmy używa {"company": {...}}; batch firm — {"companies": [...]}. Endpointy z prostymi argumentami przyjmują pola bez wrappera, np. {"websiteId": 1, "currency": "PLN", "items": [...]}.

Nagłówek Idempotency-Key (maks. 128 znaków) jest obecnie obsługiwany przez POST /companies: ponowienie z tym samym kluczem zwróci wcześniej utworzoną firmę. Dla joba integracyjnego użyj pola request.idempotencyKey. Nie zakładaj automatycznej idempotencji innych endpointów zapisu; ponawiaj je dopiero po ustaleniu statusu operacji.

Odpowiedzi i błędy

Odpowiedzi sukcesu są obiektami lub tablicami kontraktów Magento. Pola zwracane przez obiekty mogą być rozszerzane w kompatybilny sposób; integracja powinna ignorować nieznane pola. Błąd biznesowy może zawierać:

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

Nie loguj tokenów, pełnych danych osobowych ani sekretów konfiguracji. Zgłoszenie do zespołu sklepu powinno zawierać czas, metodę, ścieżkę bez sekretów, status HTTP, trace_id oraz zanonimizowany payload.

4. Schematy danych wejściowych

Poniższe schematy są wspólne dla endpointów referencyjnych. Pole bez ? jest wymagane przez kontrakt; ? oznacza wartość opcjonalną. Pola metadata, config, configuration i payload są obiektami JSON.

5. Referencja endpointów

W tabelach ACL oznacza minimalny zasób uprawnienia Magento. Wynik określa rodzaj odpowiedzi sukcesu.

5.1. Websites i konfiguracja

5.2. Firmy i użytkownicy firmowi

5.3. Produkty, cena i widoczność katalogu

5.4. Import i eksport plikowy

5.5. Szybkie zamówienie i listy zakupowe

5.6. Dokumenty i pliki

5.7. Limit kupiecki i terminy płatności

5.8. Workflow akceptacji

5.9. Kontekst B2B zamówień

5.10. RFQ i oferty handlowe

5.11. Profile i joby integracyjne

6. Przykłady wywołań

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łu
curl -sS "$BASE_URL/kowal-b2b/websites/$WEBSITE_ID/config" \
  -H "Authorization: Bearer $TOKEN" -H 'Accept: application/json'

# Cena kontraktowa firmy dla konkretnej ilości
curl -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 SKU
curl -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 RFQ
curl -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. Zalecane scenariusze integracyjne

Zakup po SKU

1. Odczytaj konfigurację website i zapisz przekazane websiteId, companyId, walutę.
2. Użyj quick order do zbiorczej walidacji SKU, ilości, widoczności i dostępności.
3. Dla zaakceptowanych pozycji pobierz cenę z price z właściwym qty.
4. Utwórz RFQ, dodaj pozycje i wyślij je przez submit, jeśli zakup wymaga oferty.
5. Śledź status i historię RFQ; po akceptacji postępuj zgodnie z uzgodnionym procesem zamówienia Magento, ponieważ V1 nie wystawia endpointu tworzenia order.

Dokumenty i rozliczenia

1. Pobierz listę dokumentów firmy, opcjonalnie filtrując documentType.
2. Dla wybranego dokumentu pobierz metadane i listę plików; ścieżka pliku nie jest automatycznie publicznym URL — sposób pobrania binarium uzgodnij z administratorem sklepu.
3. Odczytaj status limitu przed procesem zakupowym; tylko integracja z ACL credit_limits może nim zarządzać.

Operacje asynchroniczne

1. Zapisz profil integracji i mapowania identyfikatorów.
2. Opublikuj job z biznesowym idempotencyKey i zachowaj jobId.
3. Odczytuj job oraz logi/błędy; retry wywołuj dopiero po analizie błędu i usunięciu jego przyczyny.

8. Lista odbiorowa przed produkcją

• Token ma wyłącznie wymagane ACL i nie jest tokenem administratora używanym przez UI.
• Integrator poprawnie obsługuje 401, 403, 404, walidację 422, konflikt 409 i timeouty.
• Każdy request w kontekście B2B przekazuje właściwe websiteId, a dane firmy używają prawidłowego companyId.
• Ceny, widoczność i dostępność są sprawdzane przed utworzeniem procesu zakupowego.
• Tworzenie firmy używa Idempotency-Key; joby integracyjne mają stabilny idempotencyKey w body.
• Logi nie zawierają tokenów ani danych wrażliwych, a procedura wsparcia przekazuje trace_id.
• Testy zostały wykonane na środowisku testowym na firmie, która ma aktywną relację z B2B website.

9. Kompatybilność

Kontrakt jest wersjonowany przez /V1. Rozszerzenie odpowiedzi o nowe pola jest kompatybilne; integrator powinien tolerować pola nieznane. Zmiana usuwająca pole, znaczenie pola lub endpoint wymaga nowej wersji API. W razie rozbieżności między dokumentem a działającą instalacją wiążący jest aktywny kontrakt webapi.xml danej wersji modułu.

Instalacja i konfiguracja Kowal B2B Suite

Ten podręcznik jest przeznaczony dla osoby, która kupiła Kowal B2B Suite i ma go uruchomić w istniejącej instalacji Magento Open Source. Prowadzi przez dwa etapy:

1. instalacja techniczna — wykonywana przez developera lub administratora serwera;
2. konfiguracja biznesowa — wykonywana w panelu Magento przez administratora sklepu.

Przed rozpoczęciem wykonaj kopię bazy danych i plików Magento. Pierwsze uruchomienie zalecamy przeprowadzić na środowisku testowym, a dopiero później wdrożyć na produkcję.

1. Co otrzymujesz i czego potrzebujesz

Kowal B2B Suite jest dostarczany jako pakiet Composer kowal/metapackage-b2b-suite. Zawiera moduły B2B oraz theme frontend/Kowal/b2b.

Wymagania

Od Kowal otrzymasz:

• adres prywatnego repozytorium Composer — dalej jako REPOSITORY_URL;
• nazwę użytkownika lub identyfikator dostępu — USERNAME;
• token dostępu — ACCESS_TOKEN;
• dozwolony zakres wersji pakietu.

Nie zapisuj tokenu w repozytorium Git, w ticketach ani w historii powłoki współdzielonej z innymi osobami.

2. Instalacja techniczna

Wszystkie polecenia wykonuj w katalogu głównym istniejącej instalacji Magento, jako użytkownik mający dostęp do plików oraz do polecenia bin/magento.

2.1. Przygotowanie

1. Upewnij się, że Magento działa poprawnie przed zmianą.
2. Zapisz stan wdrożenia i wykonaj backup bazy danych oraz katalogów app/etc, pub/media i var.
3. Na produkcji włącz tryb maintenance na czas aktualizacji:

bin/magento maintenance:enable

2.2. Dodanie prywatnego repozytorium

Dodaj repozytorium Composer Kowal i skonfiguruj otrzymane dane dostępowe.

Dane dostępowe do repozytorium Composer (adres e-mail klienta i token licencyjny) otrzymasz e-mailem po zakupie. Są również dostępne w panelu klienta po zalogowaniu na kowal.store. Zastąp TWOJ_EMAIL_KLIENTA adresem e-mail swojego konta, a TWOJ_TOKEN otrzymanym tokenem. Polecenia wykonaj w katalogu głównym Magento.

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

Composer zwykle zapisuje poświadczenia w lokalnym auth.json; nie dodawaj tego pliku do Git.

2.3. Instalacja pakietu

Zainstaluj wersję przekazaną wraz z licencją. Dla bieżącej linii pakietu przykładowe polecenie ma postać:

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

Po pobraniu zależności wykonaj aktualizację schematu i konfiguracji Magento:

bin/magento setup:upgrade
bin/magento cache:clean

W trybie produkcyjnym wykonaj dodatkowo:

bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f pl_PL en_US
bin/magento cache:flush

Użyj tylko tych locale, które są aktywne w sklepie. Jeżeli instalacja korzysta z innego procesu deploymentu, dołącz powyższe komendy do jego standardowej procedury.

2.4. Weryfikacja instalacji

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

W panelu administracyjnym powinno pojawić się menu B2B oraz zakładka Stores > Configuration > Kowal > B2B. Jeżeli ich nie ma, sprawdź wynik setup:upgrade, cache oraz role ACL użytkownika administratora.

2.5. Uprawnienia plików PDF

PDF-y generowane przez B2B używają mPDF i katalogów pod var/, w tym var/tmp/kowal_b2b_mpdf oraz var/kowal_b2b_documents. Proces PHP musi mieć możliwość ich utworzenia i zapisu. Brak tych uprawnień objawia się błędem generowania dokumentu lub PDF.

Po zakończeniu wdrożenia produkcyjnego wyłącz maintenance:

bin/magento maintenance:disable

3. Konfiguracja struktury sklepu B2B

3.1. Website i store view

Suite działa w zakresie website, a nie globalnie. Możesz prowadzić B2C i B2B w tej samej instalacji Magento, lecz B2B powinno działać w osobnym website lub w świadomie wybranym website sprzedaży firmowej.

1. W Stores > Settings > All Stores utwórz lub wybierz website B2B, jego store oraz store view.
2. Zapamiętaj website_id — jest używany przez firmy, ceny, dokumenty, API i integracje.
3. W Content > Design > Configuration przypisz theme frontend/Kowal/b2b tylko do B2B store view.
4. Sprawdź, że aktywne waluty, podatki, metody dostawy i metody płatności są skonfigurowane dla tego samego scope.

Nie przypisuj theme B2B do store view B2C, jeśli nie chcesz zmieniać jego warstwy prezentacji. Sama instalacja modułów nie włącza logiki B2B dla wszystkich website.

3.2. Aktywacja B2B

1. Otwórz Stores > Configuration > Kowal > B2B.
2. W przełączniku scope wybierz właściwy Website.
3. W sekcji General ustaw Enable B2B na Yes.
4. Na czas wdrożenia możesz włączyć Debug Mode; wyłącz go po testach.
5. W scope Default Config ustaw okres retencji logów.
6. Zapisz konfigurację i wyczyść cache.

Po aktywacji wszystkie store view należące do tego website są traktowane jako B2B. Firma bez aktywnej relacji z tym website nie uzyska do niego dostępu.

3.3. Dane sprzedawcy

Uzupełnij dane firmy sprzedającej w Stores > Configuration > General > Store Information: nazwę, adres, telefon oraz NIP. Są używane w dokumentach i PDF RFQ. Uzupełnij również ogólny adres e-mail nadawcy w konfiguracji Sales Emails oraz logo e-mail, jeśli ma pojawiać się w PDF.

4. Konfiguracja pierwszego klienta B2B

Poniższą kolejność stosuj dla każdej firmy. Pozwala uniknąć sytuacji, w której klient ma konto, ale nie widzi oferty lub nie może przejść checkoutu.

4.1. Firma, osoby i adresy

1. Otwórz B2B > Companies i utwórz firmę.
2. Podaj nazwę, NIP, identyfikator zewnętrzny (jeśli firma jest synchronizowana z ERP), status Active oraz przypisanie do B2B website.
3. Dodaj użytkownika firmy lub przypisz istniejącego klienta Magento. Nadaj mu właściwą rolę i aktywuj przypisanie.
4. W B2B > Company Addresses dodaj adresy firmy; oznacz domyślny adres rozliczeniowy i wysyłkowy dla website B2B.
5. W B2B > Company Contacts dodaj aktywny kontakt główny z e-mailem i telefonem.

Adres rozliczeniowy i kontakt główny są również używane w PDF RFQ. Brak danych nie blokuje PDF, ale dokument będzie mniej kompletny.

4.2. Role firmowe

Nadaj użytkownikom tylko potrzebne uprawnienia. Typowy podział to:

Przetestuj konto każdego typu, zwłaszcza uprawnienie do składania zamówień i akceptacji. Nie używaj jednego wspólnego konta dla całej firmy.

5. Oferta, ceny i checkout

5.1. Katalog i ceny

1. Upewnij się, że produkty Magento są przypisane do B2B website, aktywne i mają poprawne dane MSI.
2. Skonfiguruj cenniki lub ceny kontraktowe dla firmy w obszarze B2B > Pricing (Price Lists, Price List Assignments lub Contract Prices).
3. Skonfiguruj reguły widoczności katalogu dla firmy zgodnie z wdrożonym modelem uprawnień, a następnie sprawdź widoczność na koncie klienta.
4. Przetestuj na koncie firmy: wyszukanie SKU, widoczność produktu i cenę dla ilości 1 oraz dla progu ilościowego.

Cena B2B zależy od firmy, website, waluty i ilości. Produkt widoczny w B2C nie musi być dostępny dla klienta B2B.

5.2. Dostawa i płatność

1. Włącz wymagane metody dostawy i płatności w standardowej konfiguracji Magento dla B2B store view.
2. W B2B > Checkout dodaj reguły dostępnych metod dla firmy/website, jeśli chcesz ograniczyć wybór.
3. Przeprowadź test koszyka na domyślnych adresach firmy.

Jeśli tworzenie zamówienia z RFQ ma działać automatycznie po stronie administratora, firma musi mieć jednoznaczne domyślne adresy, aktywną metodę płatności i dostawy. W przeciwnym razie Suite załaduje dane do natywnego Backend Order Create, gdzie administrator uzupełnia brakujące elementy.

5.3. Limity i akceptacje

Te funkcje są opcjonalne, ale powinny być skonfigurowane przed włączeniem ich klientom.

1. W B2B > Credit > Payment Terms dodaj terminy płatności.
2. W B2B > Credit > Credit Limits przypisz firmie limit, walutę, status i termin płatności.
3. W B2B > Approvals > Rules utwórz regułę progu kwotowego dla firmy i website.
4. W B2B > Approvals > Approvers przypisz osoby akceptujące.
5. Przetestuj koszyk poniżej i powyżej progu oraz sprawdź, czy decyzja akceptującego zmienia dalszy proces.

6. Dokumenty, PDF i RFQ

6.1. Dokumenty Magento

W Stores > Configuration > Kowal > B2B > Documents wybierz źródło dokumentów i zdecyduj, które dokumenty mają być generowane automatycznie: potwierdzenia zamówień, faktury, WZ i korekty. Ustaw też docelowy status dokumentu.

W B2B > Documents > PDF Templates:

1. sprawdź aktywny szablon dla każdego typu i website;
2. wykonaj podgląd;
3. dostosuj HTML/CSS wyłącznie, gdy masz osobę znającą szablony Magento i CSS mPDF;
4. wygeneruj testową fakturę lub potwierdzenie i sprawdź pobranie z konta firmy.

6.2. RFQ i oferta PDF

1. W B2B > Quotes > RFQ utwórz testowe RFQ dla aktywnej firmy i użytkownika.
2. Dodaj widoczne dla firmy SKU, ilość oraz cenę ofertową.
3. Ustaw termin ważności, prześlij ofertę klientowi i wygeneruj PDF.
4. Sprawdź wariant klienta: dane sprzedawcy/nabywcy, pozycje, cena, suma i termin ważności.
5. Sprawdź wariant administratora: dodatkowo notatki handlowe, komentarze, historię oraz wewnętrzne informacje o pozycjach.

PDF klienta nie może zawierać notatek handlowca ani wewnętrznej historii statusów.

7. Szybkie zamówienia, importy i integracje

Szybkie zamówienia

W B2B > Quick Order > Debug SKU sprawdź listę SKU,qty dla firmy, website i waluty. Następnie utwórz listę zakupową i przetestuj jej użycie przez klienta na storefront.

Import i eksport

W B2B > Import/Export zdefiniuj profil dopiero po ustaleniu źródła danych. Konfiguracja profilu jest obiektem JSON i musi zawierać ścieżki plików dostępne na serwerze Magento. Najpierw uruchom import w trybie testowym oraz przeanalizuj job i logi.

Integracje API

Przed utworzeniem tokenu integracyjnego ustal zakres danych i właściciela synchronizacji. Użyj osobnej integracji Magento dla każdego ERP, PIM, WMS lub middleware i nadaj jej wyłącznie potrzebne ACL B2B. Pełna lista endpointów, tokenów i zasad bezpieczeństwa znajduje się w dokumentacji API dla integratorów.

8. Checklista odbiorowa

Przed uruchomieniem produkcyjnym potwierdź:

• Moduły Kowal są aktywne, cron działa, a cache i indeksy są poprawne.
• B2B jest włączone wyłącznie dla właściwego website.
• Theme B2B jest przypisany wyłącznie do B2B store view.
• Firma testowa ma status Active, użytkownika, rolę, kontakt i domyślne adresy.
• Produkt testowy jest aktywny, przypisany do website, widoczny dla firmy i ma poprawną cenę B2B.
• Klient może zalogować się, wyszukać SKU, użyć quick order i dodać produkt do koszyka.
• Checkout pokazuje tylko dopuszczalne metody dostawy i płatności.
• Limit i reguła akceptacji działają zgodnie z polityką firmy, jeśli te funkcje są używane.
• Dokument oraz PDF RFQ generują się i są dostępne wyłącznie dla właściwej firmy.
• RFQ można wysłać, zaakceptować i przekazać do procesu utworzenia zamówienia.
• Integracje mają osobne tokeny i ograniczone ACL, jeśli są używane.

9. Najczęstsze problemy

Przy zgłoszeniu do wsparcia podaj wersję Magento, wersję pakietu, kroki odtworzenia, godzinę zdarzenia, bezpiecznie zanonimizowane logi i ewentualny trace_id. Nie przesyłaj tokenów ani haseł.

10. Aktualizacja pakietu

1. Zapoznaj się z informacją o wersji przekazaną przez Kowal.
2. Wykonaj aktualizację najpierw na środowisku testowym.
3. Wykonaj backup, composer update kowal/metapackage-b2b-suite --with-all-dependencies, bin/magento setup:upgrade, a w produkcji także kompilację DI i deployment zasobów statycznych.
4. Powtórz checklistę odbiorową, ze szczególnym uwzględnieniem cen, checkoutu, dokumentów i integracji.

Nie aktualizuj pakietu przez ręczne kopiowanie plików do app/code; powoduje to problemy z Composerem oraz utrudnia późniejsze wsparcie.