Kowal B2B API — dokumentacja dla integratorów klienta B2B

1. Dla kogo jest ten dokument

Ten dokument jest przeznaczony dla programistów i zespołów IT po stronie klienta B2B, którzy chcą zintegrować własny system zakupowy, ERP, WMS, aplikację wewnętrzną albo middleware ze sklepem B2B opartym o Kowal B2B API.

Dokument opisuje praktyczne użycie API w procesach sprzedażowo-zakupowych pomiędzy klientem B2B a sklepem B2B:

• pobieranie produktów dostępnych dla firmy,
• sprawdzanie cen indywidualnych,
• sprawdzanie widoczności i możliwości zakupu SKU,
• walidację szybkiego zamówienia po SKU,
• obsługę list zakupowych,
• pobieranie dokumentów handlowych,
• sprawdzanie limitu kupieckiego,
• obsługę zapytań ofertowych RFQ,
• odczyt kontekstu zamówień B2B,
• diagnostykę błędów integracyjnych.

Dokument nie opisuje instalacji modułu ani wewnętrznej architektury sklepu. Te elementy obsługuje administrator sklepu lub zespół wdrożeniowy.

2. Co trzeba otrzymać od administratora sklepu

Przed rozpoczęciem integracji poproś administratora sklepu B2B o:

Bez websiteId i companyId większość operacji B2B nie będzie możliwa, ponieważ API izoluje dane per kanał sprzedaży i per firma.

3. Podstawowe zasady API

3.1. Base URL

W dokumentacji endpointy są zapisywane skrótowo:

/V1/kowal-b2b/...

W wywołaniu użyj pełnego adresu:

https://b2b.example.com/rest/V1/kowal-b2b/...

Jeżeli sklep używa kodów store view w adresie API, administrator może przekazać wariant:

https://b2b.example.com/rest/{store_code}/V1/kowal-b2b/...

3.2. Format danych

API przyjmuje i zwraca JSON.

Standardowe nagłówki:

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

Dla metod GET wystarczy Authorization i Accept.

3.3. Kontekst firmy i website

W zapytaniach sprzedażowych prawie zawsze występują:

• websiteId — kanał B2B,
• companyId — firma klienta B2B,
• currency — waluta,
• sku — kod produktu,
• qty — ilość.

Przykład:

GET /V1/kowal-b2b/companies/10/products/B2B-SKU-001/price?websiteId=1&currency=PLN&qty=5

API nie powinno domyślnie zgadywać website ani firmy. To zabezpiecza instalacje, w których jeden sklep obsługuje równolegle B2C i B2B.

3.4. Idempotencja

Dla operacji zapisu, które mogą być ponawiane po timeoutach, stosuj nagłówek:

Idempotency-Key: unique-business-operation-id

Przykład:

Idempotency-Key: erp-rfq-2026-000123

Zastosowanie:

• utworzenie RFQ,
• dodanie dokumentu,
• operacje wywoływane automatycznie przez ERP albo system zakupowy klienta.

Wartość klucza powinna być unikalna dla operacji biznesowej, a nie dla pojedynczej próby HTTP.

4. Autoryzacja

API korzysta ze standardowego mechanizmu tokenów sklepu.

W praktyce integrator klienta B2B powinien otrzymać gotowy token od administratora sklepu albo proces jego uzyskania.

4.1. Użycie tokena

curl -X GET "$BASE_URL/kowal-b2b/websites/$WEBSITE_ID/config" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

4.2. Uprawnienia tokena

Token powinien mieć tylko te uprawnienia, które są potrzebne danej integracji.

Przykłady zakresów:

Jeżeli endpoint zwraca błąd autoryzacji, najpierw sprawdź zakres tokena u administratora sklepu.

5. Szybki start

Ustaw zmienne pomocnicze:

export BASE_URL="https://b2b.example.com/rest/V1"
export TOKEN="paste-token-here"
export WEBSITE_ID=1
export COMPANY_ID=10
export CUSTOMER_ID=25
export SKU="B2B-SKU-001"
export CURRENCY="PLN"

5.1. Sprawdź konfigurację B2B website

curl -X GET "$BASE_URL/kowal-b2b/websites/$WEBSITE_ID/config" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Cel:

• potwierdzić, że integracja używa właściwego websiteId,
• potwierdzić, że kanał B2B jest dostępny.

5.2. Pobierz produkt po SKU

curl -X GET "$BASE_URL/kowal-b2b/products/$SKU?websiteId=$WEBSITE_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Cel:

• sprawdzić, czy produkt istnieje,
• pobrać podstawowe dane produktu w kontekście B2B.

5.3. Sprawdź dostępność produktu

curl -X GET "$BASE_URL/kowal-b2b/products/$SKU/availability?websiteId=$WEBSITE_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Cel:

• sprawdzić dostępność sprzedażową produktu,
• wykorzystać dane magazynowe sklepu.

5.4. Sprawdź cenę B2B

curl -X GET "$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"

Cel:

• pobrać cenę właściwą dla firmy,
• uwzględnić walutę i ilość,
• sprawdzić źródło ceny, np. cena kontraktowa, cennik B2B albo fallback.

5.5. Sprawdź widoczność SKU dla firmy

curl -X GET "$BASE_URL/kowal-b2b/companies/$COMPANY_ID/products/$SKU/visibility?websiteId=$WEBSITE_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Cel:

• ustalić, czy firma może zobaczyć produkt,
• ustalić, czy firma może zobaczyć cenę,
• ustalić, czy produkt można dodać do koszyka lub zamówienia.

5.6. Zweryfikuj koszyk po SKU

curl -X POST "$BASE_URL/kowal-b2b/companies/$COMPANY_ID/quick-order/validate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "websiteId": 1,
    "currency": "PLN",
    "items": [
      {
        "sku": "B2B-SKU-001",
        "qty": 5
      },
      {
        "sku": "B2B-SKU-002",
        "qty": 2
      }
    ]
  }'

Cel:

• sprawdzić kilka pozycji jednocześnie,
• wykryć niedostępne SKU,
• wykryć produkty niewidoczne dla firmy,
• pobrać ceny i komunikaty walidacyjne przed utworzeniem zamówienia w systemie klienta.

6. Najczęstszy proces integracyjny: zakup po SKU

Typowy proces automatyzacji zakupów wygląda tak:

1. System klienta zna companyId, websiteId i walutę.
2. System klienta wysyła listę SKU i ilości do walidacji quick order.
3. API zwraca status każdej pozycji.
4. System klienta odrzuca lub oznacza pozycje błędne.
5. System klienta pobiera ceny B2B dla zaakceptowanych pozycji.
6. System klienta tworzy RFQ, listę zakupową albo przekazuje dane do dalszego procesu zakupowego.
7. Po realizacji zamówienia system klienta pobiera dokumenty handlowe i statusy B2B zamówień.

Rekomendacja: nie pobieraj ceny i widoczności wyłącznie pojedynczymi requestami, jeśli użytkownik importuje duży plik SKU. Najpierw użyj walidacji quick order.

7. Produkty, ceny i widoczność

7.1. Lista produktów

GET /V1/kowal-b2b/products?websiteId=...

Zastosowanie:

• synchronizacja katalogu do systemu klienta,
• budowa lokalnej wyszukiwarki produktów,
• odświeżanie listy SKU.

7.2. Produkt po SKU

GET /V1/kowal-b2b/products/:sku?websiteId=...

Zastosowanie:

• pobranie danych jednego SKU,
• walidacja ręcznie wpisanego kodu produktu.

7.3. Dostępność produktu

GET /V1/kowal-b2b/products/:sku/availability?websiteId=...

Zastosowanie:

• sprawdzenie dostępności przed zakupem,
• walidacja importu zamówienia,
• informowanie użytkownika o brakach magazynowych.

7.4. Cena produktu dla firmy

GET /V1/kowal-b2b/companies/:companyId/products/:sku/price?websiteId=...&currency=...&qty=...

Zastosowanie:

• pobranie ceny indywidualnej,
• sprawdzenie progów ilościowych,
• uzgodnienie ceny w systemie zakupowym klienta.

7.5. Widoczność produktu

GET /V1/kowal-b2b/companies/:companyId/products/:sku/visibility?websiteId=...

Zastosowanie:

• sprawdzenie, czy firma może kupić produkt,
• odróżnienie błędu „produkt nie istnieje” od „produkt niedostępny dla tej firmy”,
• kontrola uprawnień katalogowych B2B.

8. Quick order i listy zakupowe

8.1. Walidacja quick order

POST /V1/kowal-b2b/companies/:companyId/quick-order/validate

Body:

{
  "websiteId": 1,
  "currency": "PLN",
  "items": [
    {
      "sku": "B2B-SKU-001",
      "qty": 5
    }
  ]
}

Zastosowanie:

• import zamówienia z CSV/XLSX po stronie klienta,
• walidacja koszyka w aplikacji zakupowej,
• kontrola widoczności, ceny i dostępności przed dalszym procesem.

8.2. Pobranie list zakupowych firmy

GET /V1/kowal-b2b/companies/:companyId/shopping-lists?websiteId=...

Zastosowanie:

• synchronizacja list stałych produktów,
• budowa cyklicznych zamówień,
• odtworzenie koszyka w systemie klienta.

8.3. Utworzenie listy zakupowej

POST /V1/kowal-b2b/companies/:companyId/shopping-lists

Przykład:

{
  "websiteId": 1,
  "name": "Stałe zamówienie magazynowe",
  "customerId": 25,
  "isDefault": false
}

8.4. Dodanie pozycji do listy

POST /V1/kowal-b2b/shopping-lists/:listId/items

Przykład:

{
  "currency": "PLN",
  "items": [
    {
      "sku": "B2B-SKU-001",
      "qty": 5
    }
  ]
}

9. RFQ i oferty

RFQ pozwala klientowi B2B wysłać zapytanie ofertowe, a sprzedawcy przygotować odpowiedź cenową.

9.1. Utworzenie RFQ

POST /V1/kowal-b2b/quotes

Przykład:

{
  "request": {
    "websiteId": 1,
    "companyId": 10,
    "customerId": 25,
    "externalId": "CLIENT-RFQ-2026-0001",
    "title": "Zapytanie ofertowe na produkty magazynowe",
    "currency": "PLN",
    "customerNote": "Prosimy o ofertę dla ilości kwartalnych.",
    "metadata": {
      "source": "client-erp"
    }
  }
}

9.2. Dodanie pozycji RFQ

POST /V1/kowal-b2b/quotes/items

Przykład:

{
  "request": {
    "quoteId": 100,
    "sku": "B2B-SKU-001",
    "qty": 100,
    "requestedPrice": null,
    "comment": "Cena dla dostawy cyklicznej"
  }
}

9.3. Złożenie RFQ

POST /V1/kowal-b2b/quotes/:quoteId/submit

Przykład:

{
  "request": {
    "customerId": 25,
    "message": "Zapytanie gotowe do wyceny."
  }
}

9.4. Odczyt statusu i historii

GET /V1/kowal-b2b/quotes/:quoteId
GET /V1/kowal-b2b/quotes/:quoteId/items
GET /V1/kowal-b2b/quotes/:quoteId/comments
GET /V1/kowal-b2b/quotes/:quoteId/history

Zastosowanie:

• śledzenie statusu zapytania,
• pobranie odpowiedzi handlowca,
• synchronizacja oferty do systemu klienta.

10. Dokumenty handlowe

API dokumentów pozwala klientowi pobierać dokumenty przypisane do jego firmy.

Typowe dokumenty:

• faktura,
• korekta,
• WZ,
• potwierdzenie zamówienia.

10.1. Lista dokumentów firmy

GET /V1/kowal-b2b/companies/:companyId/documents?websiteId=...&documentType=...

Przykład:

curl -X GET "$BASE_URL/kowal-b2b/companies/$COMPANY_ID/documents?websiteId=$WEBSITE_ID&documentType=invoice" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

10.2. Szczegóły dokumentu

GET /V1/kowal-b2b/documents/:documentId?companyId=...&websiteId=...

10.3. Pliki dokumentu

GET /V1/kowal-b2b/documents/:documentId/files?companyId=...&websiteId=...

Zastosowanie:

• pobranie PDF faktury,
• archiwizacja dokumentów w ERP klienta,
• automatyczne księgowanie po stronie klienta.

11. Limity kupieckie i płatności

11.1. Status limitu firmy

GET /V1/kowal-b2b/companies/:companyId/credit/status?websiteId=...&currency=...

Zastosowanie:

• sprawdzenie dostępnego limitu przed zakupem,
• pokazanie operatorowi, czy zamówienie może zostać złożone,
• synchronizacja danych kredytowych do ERP klienta.

11.2. Warunki płatności

GET /V1/kowal-b2b/payment-terms?websiteId=...

Zastosowanie:

• pobranie dostępnych warunków płatności,
• prezentacja warunków w systemie zakupowym klienta.

12. Akceptacje zamówień

Jeżeli firma korzysta z workflow akceptacji, API pozwala sprawdzić, czy dana wartość koszyka wymaga zatwierdzenia.

12.1. Sprawdzenie wymogu akceptacji

GET /V1/kowal-b2b/companies/:companyId/approval/required?websiteId=...&grandTotal=...&currency=...

Zastosowanie:

• ostrzeżenie użytkownika przed wysłaniem zamówienia,
• skierowanie koszyka do wewnętrznego workflow klienta,
• synchronizacja statusu akceptacji.

12.2. Lista requestów akceptacji

GET /V1/kowal-b2b/companies/:companyId/approval/requests?websiteId=...&status=...

12.3. Historia decyzji

GET /V1/kowal-b2b/approval/requests/:requestId/decisions

13. Zamówienia B2B

API kontekstu zamówień pozwala odczytać informacje B2B powiązane ze standardowym zamówieniem sklepu.

13.1. Kontekst B2B zamówienia

GET /V1/kowal-b2b/orders/:orderId/b2b-context

13.2. Zamówienia firmy z kontekstem B2B

GET /V1/kowal-b2b/companies/:companyId/orders/b2b-context?websiteId=...&approvalStatus=...

Zastosowanie:

• synchronizacja zamówień do ERP klienta,
• sprawdzenie statusu akceptacji,
• sprawdzenie statusu eksportu albo obsługi B2B.

14. Obsługa błędów

API zwraca standardowe odpowiedzi HTTP.

Najczęstsze statusy:

Najważniejsze kody domenowe:

Przykład odpowiedzi błędu:

{
  "code": "b2b.product.not_visible",
  "message": "Product is not visible for selected company.",
  "details": {
    "website_id": 1,
    "company_id": 10,
    "sku": "B2B-SKU-001"
  }
}

15. Dobre praktyki integracyjne

• Przechowuj websiteId, companyId i currency w konfiguracji integracji.
• Nie zakładaj, że produkt widoczny w B2C jest dostępny dla firmy B2B.
• Zawsze sprawdzaj cenę B2B dla konkretnej ilości.
• Przy imporcie wielu SKU używaj quick order validate zamiast wielu osobnych requestów.
• Stosuj Idempotency-Key dla operacji zapisu.
• Loguj request URL, status HTTP i odpowiedź błędu.
• Nie loguj tokenów, haseł ani pełnych danych wrażliwych.
• Obsługuj ponowienie requestu po timeoutach.
• Odróżniaj błąd techniczny od błędu biznesowego, np. brak ceny albo brak widoczności SKU.
• Uzgodnij z administratorem sklepu limity zapytań i maksymalny rozmiar paczki danych.

16. Minimalny zestaw testów integracyjnych

Przed uruchomieniem produkcyjnym wykonaj testy:

• poprawna autoryzacja tokenem,
• błędny token zwraca 401 albo 403,
• pobranie konfiguracji website,
• pobranie produktu po SKU,
• pobranie dostępności SKU,
• pobranie ceny B2B dla qty=1,
• pobranie ceny B2B dla większej ilości,
• sprawdzenie SKU widocznego dla firmy,
• sprawdzenie SKU niewidocznego dla firmy,
• walidacja quick order dla poprawnych SKU,
• walidacja quick order dla błędnego SKU,
• pobranie dokumentów firmy,
• utworzenie RFQ i dodanie pozycji,
• odczyt historii RFQ,
• pobranie statusu limitu kupieckiego,
• próba operacji z błędnym websiteId,
• próba operacji z błędnym companyId.

17. Katalog endpointów dla automatyzacji zakupów

17.1. Konfiguracja

17.2. Produkty i ceny

17.3. Quick order i listy

17.4. RFQ i oferty

17.5. Dokumenty, limity i zamówienia

18. Zakres dokumentu

Dokument koncentruje się na integracji zakupowej po stronie klienta B2B. Opisuje praktyczne użycie API, wymagane identyfikatory, przykłady requestów, obsługę błędów i typowe scenariusze automatyzacji.

Informacje wdrożeniowe sklepu, konfiguracja panelu administracyjnego i szczegóły techniczne instalacji są obsługiwane osobno przez zespół utrzymujący sklep B2B.