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
- Integrator przekazuje administratorowi sklepu cel integracji, środowisko (test/produkcja), system źródłowy, zakres danych oraz listę wymaganych obszarów API.
- 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.
- Integrator wykonuje test
GET /V1/kowal-b2b/websites/:websiteId/config, a następnie testy funkcjonalne na środowisku testowym.
- Przed produkcją obie strony uzgadniają harmonogram synchronizacji, maksymalny rozmiar danych, retry, właściciela danych i sposób zgłaszania błędów.
- 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
| Strona |
Odpowiedzialność |
| Administrator sklepu |
Konfiguracja B2B website, firmy i relacji firmy z website, tokenu oraz ACL; przekazanie danych testowych; decyzja o dostępie do danych. |
| Integrator |
Bezpieczne przechowywanie tokenu, poprawne użycie kontekstu websiteId/companyId, walidacja danych, obsługa błędów i ponowień, nieujawnianie danych innych firm. |
| Właściciel procesu biznesowego |
Uzgodnienie źródła prawdy dla cen, dokumentów, RFQ, limitów i statusów synchronizacji. |
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ń:
| ACL |
Zakres |
config |
Websites i feature flags |
companies, company_save, company_users, batch |
Firmy, ich użytkownicy i import wsadowy firm |
products, prices, catalog_permissions |
Katalog, dostępność, ceny i widoczność |
import_export, quick_order, documents |
Profile importu/eksportu, listy zakupowe i dokumenty |
credit_limits, approvals, orders, quotes |
Limit, workflow akceptacji, kontekst zamówień i RFQ |
system_integrations |
Profile, mapowania i joby integracyjne |
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": []
}
| HTTP |
Znaczenie |
Reakcja integratora |
400 / 422 |
Niepoprawne dane albo walidacja domenowa |
Popraw dane; nie ponawiaj bez zmiany payloadu. |
401 / 403 |
Brak lub niewystarczający token/ACL |
Nie ponawiaj; zgłoś administratorowi zakres tokenu. |
404 |
Zasób lub relacja w danym kontekście nie istnieje |
Zweryfikuj identyfikatory i kontekst website. |
409 |
Konflikt statusu lub duplikat |
Odczytaj aktualny stan przed decyzją o ponowieniu. |
5xx / timeout |
Błąd techniczny |
Zastosuj ograniczone retry z backoffem i zachowaj trace_id. |
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.
| DTO / wrapper |
Pola |
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 — pozycja RFQ |
quoteId, sku, productId?, name?, qty, requestedPrice?, offeredPrice?, comment?, metadata? |
request — decyzja RFQ |
customerId?, adminUserId?, message? |
request — komentarz RFQ |
quoteId, customerId?, adminUserId?, authorType, message, visibleForCustomer |
request — dokument |
websiteId, companyId, orderId?, orderIncrementId?, invoiceId?, invoiceIncrementId?, creditmemoId?, creditmemoIncrementId?, externalId?, documentNumber, documentType, status, issueDate?, dueDate?, grandTotal?, currency?, metadata? |
request — plik dokumentu |
documentId, fileName, filePath, mimeType, fileSize, checksum?, primary |
request — limit |
websiteId, companyId, termsId?, creditLimit, currency, active, status, metadata? |
request — ekspozycja limitu |
websiteId, companyId, sourceType, sourceId, sourceIncrementId?, amount, currency, dueDate?, metadata? |
request — warunki płatności |
websiteId, code, name, daysDue, active, description? |
request — reguła akceptacji |
websiteId, companyId, name, thresholdAmount, currency?, priority, active, metadata? |
request — akceptujący |
ruleId, customerId, sortOrder, active |
request — decyzja akceptacji |
approverCustomerId?, comment? |
request — wniosek akceptacji |
websiteId, companyId, orderId?, orderIncrementId?, requesterCustomerId?, grandTotal, currency, comment?, metadata? |
request — profil import/export |
websiteId, code, name, direction, entityType, format, behavior, active, configuration? |
request — profil integracji |
websiteId, code, name, systemType, adapterCode, direction, active, maxAttempts, config? |
request — mapowanie |
websiteId, systemType, entityType, localId, externalId, metadata? |
request — job integracyjny |
profileId, direction?, entityType, operation, idempotencyKey?, maxAttempts?, payload?, scheduledAt? |
5. Referencja endpointów
W tabelach ACL oznacza minimalny zasób uprawnienia Magento. Wynik określa rodzaj odpowiedzi sukcesu.
5.1. Websites i konfiguracja
| Metoda i endpoint |
ACL |
Wejście |
Wynik i zastosowanie |
GET /V1/kowal-b2b/websites |
config |
— |
Tablica website (websiteId, kod, nazwa, flaga B2B). Pobierz przed konfiguracją integracji. |
GET /V1/kowal-b2b/websites/:websiteId/config |
config |
path: websiteId |
Konfiguracja B2B website (m.in. enabled/debug/retencja logów). Wykonaj jako test dostępu. |
GET /V1/kowal-b2b/websites/:websiteId/features |
config |
path: websiteId |
Feature flags aktywne dla website; użyj do warunkowego włączania funkcji klienta. |
5.2. Firmy i użytkownicy firmowi
| Metoda i endpoint |
ACL |
Wejście |
Wynik i zastosowanie |
GET /companies?websiteId= |
companies |
query: websiteId |
Tablica firm przypisanych do website. |
POST /companies |
company_save |
body: company |
Tworzy firmę i relację z website; użyj Idempotency-Key przy ponowieniach. Zwraca firmę. |
POST /companies/batch |
batch |
body: companies — tablica company |
Tworzy wiele firm i zwraca wynik per element, w tym błędy. |
GET /companies/:companyId?websiteId= |
companies |
path: companyId; query: websiteId |
Firma zweryfikowana w kontekście website. |
PUT /companies/:companyId |
company_save |
path: companyId; body: company |
Aktualizuje dane i relację firmy dla company.websiteId. |
POST /companies/:companyId/activate?websiteId= |
company_save |
path: companyId; query: websiteId |
Aktywuje firmę w wskazanym website i zwraca firmę. |
POST /companies/:companyId/block?websiteId= |
company_save |
path: companyId; query: websiteId |
Blokuje firmę w wskazanym website i zwraca firmę. |
GET /companies/:companyId/users?websiteId= |
company_users |
path: companyId; query: websiteId |
Tablica przypisań klientów do firmy. |
PUT /companies/:companyId/users/:customerId |
company_users |
path: companyId, customerId; body: companyUser |
Nadaje/aktualizuje rolę i aktywność klienta w firmie; zwraca przypisanie. |
5.3. Produkty, cena i widoczność katalogu
| Metoda i endpoint |
ACL |
Wejście |
Wynik i zastosowanie |
GET /products?websiteId= |
products |
query: websiteId |
Tablica podstawowych produktów Magento dla website. |
GET /products/:sku?websiteId= |
products |
path: zakodowane sku; query: websiteId |
Produkt (id, sku, nazwa, typ, status, websites). |
GET /products/:sku/availability?websiteId= |
products |
path: sku; query: websiteId |
Dostępność i ilość sprzedażowa MSI dla SKU. |
GET /products/:sku/b2b-status?websiteId= |
products |
path: sku; query: websiteId |
Status B2B: przypisanie do website, tłumaczenia i dane stock. |
GET /reports/products/missing-translations?websiteId= |
products |
query: websiteId |
Raport SKU bez wymaganych tłumaczeń, z reason/details. |
GET /reports/products/missing-stock?websiteId= |
products |
query: websiteId |
Raport SKU bez wymaganych danych stock. |
GET /companies/:companyId/products/:sku/price?websiteId=¤cy=&qty= |
prices |
path: companyId, sku; query: websiteId, currency, opcj. qty (domyślnie 1) |
Wyjaśnienie ceny właściwej dla firmy, waluty i ilości; odczytuj przed zakupem. |
GET /companies/:companyId/products/:sku/visibility?websiteId= |
catalog_permissions |
path: companyId, sku; query: websiteId |
Wynik widoczności/zakupu SKU dla firmy. |
GET /companies/:companyId/catalog-visibility?websiteId= |
catalog_permissions |
path: companyId; query: websiteId |
Tablica pozycji indeksu widocznego katalogu firmy. |
POST /companies/:companyId/catalog-visibility/reindex?websiteId= |
catalog_permissions |
path: companyId; query: websiteId |
Przebudowuje indeks i zwraca liczbę zaindeksowanych pozycji. Operacja administracyjna. |
5.4. Import i eksport plikowy
| Metoda i endpoint |
ACL |
Wejście |
Wynik i zastosowanie |
GET /import-export/profiles?websiteId= |
import_export |
query: websiteId |
Tablica profili importu/eksportu website. |
POST /import-export/profiles |
import_export |
body: request — profil import/export |
Zapisuje profil i zwraca jego dane. |
POST /import-export/import/:profileId?sourceFile=&dryRun= |
import_export |
path: profileId; query: sourceFile, opcj. dryRun=false |
Uruchamia import pliku wskazanego po stronie środowiska Magento; zwraca job. Nie przesyła multipart. |
POST /import-export/export/:profileId?resultFile= |
import_export |
path: profileId; opcj. query: resultFile |
Tworzy job eksportu, opcjonalnie z docelową ścieżką pliku. |
GET /import-export/jobs?websiteId= |
import_export |
query: websiteId |
Tablica jobów import/export dla website. |
GET /import-export/jobs/:jobId |
import_export |
path: jobId |
Stan, wynik i dane pojedynczego joba. |
GET /import-export/jobs/:jobId/logs |
import_export |
path: jobId |
Logi diagnostyczne joba. |
5.5. Szybkie zamówienie i listy zakupowe
| Metoda i endpoint |
ACL |
Wejście |
Wynik i zastosowanie |
POST /companies/:companyId/quick-order/validate |
quick_order |
path: companyId; body: websiteId, currency, items (sku, qty) |
Waliduje wiele SKU w kontekście firmy: dostępność, widoczność i cenę; zwraca zbiorczy wynik. |
GET /companies/:companyId/shopping-lists?websiteId= |
quick_order |
path: companyId; query: websiteId |
Tablica list zakupowych firmy. |
POST /companies/:companyId/shopping-lists |
quick_order |
path: companyId; body: websiteId, name, opcj. customerId, isDefault=false |
Tworzy listę zakupową i zwraca ją. |
GET /shopping-lists/:listId/items |
quick_order |
path: listId |
Tablica pozycji wskazanej listy. |
POST /shopping-lists/:listId/items |
quick_order |
path: listId; body: currency, items (sku, qty) |
Dodaje pozycje do listy i zwraca zapisane pozycje. |
5.6. Dokumenty i pliki
| Metoda i endpoint |
ACL |
Wejście |
Wynik i zastosowanie |
GET /companies/:companyId/documents?websiteId=&documentType= |
documents |
path: companyId; query: websiteId, opcj. documentType |
Dokumenty firmy, opcjonalnie filtrowane typem. |
GET /documents/:documentId?companyId=&websiteId= |
documents |
path: documentId; query: companyId, websiteId |
Szczegóły dokumentu po sprawdzeniu przynależności firmy. |
POST /documents |
documents |
body: request — dokument |
Tworzy lub zapisuje metadane dokumentu i zwraca dokument. |
POST /documents/files |
documents |
body: request — plik dokumentu |
Rejestruje plik istniejący w storage Magento (nazwa, ścieżka, MIME, rozmiar), nie wysyła binariów. |
GET /documents/:documentId/files?companyId=&websiteId= |
documents |
path: documentId; query: companyId, websiteId |
Tablica metadanych plików dokumentu. |
GET /documents/:documentId/sync-logs |
documents |
path: documentId |
Logi synchronizacji dokumentu; przeznaczone dla integracji administracyjnej. |
5.7. Limit kupiecki i terminy płatności
| Metoda i endpoint |
ACL |
Wejście |
Wynik i zastosowanie |
GET /companies/:companyId/credit/status?websiteId=¤cy= |
credit_limits |
path: companyId; query: websiteId, currency |
Status limitu, wykorzystanie i dostępna kwota firmy. |
POST /credit-limits |
credit_limits |
body: request — limit |
Tworzy/aktualizuje limit firmy i zwraca limit. |
POST /credit/exposures |
credit_limits |
body: request — ekspozycja |
Rezerwuje ekspozycję limitu dla źródła (np. zamówienia) i zwraca ją. |
POST /credit/exposures/:exposureId/release |
credit_limits |
path: exposureId; opcj. body: message |
Zwalnia ekspozycję; zwraca jej stan. |
GET /payment-terms?websiteId= |
credit_limits |
query: websiteId |
Tablica aktywnych/znanych warunków płatności website. |
POST /payment-terms |
credit_limits |
body: request — warunki płatności |
Zapisuje warunki płatności i zwraca je. |
5.8. Workflow akceptacji
| Metoda i endpoint |
ACL |
Wejście |
Wynik i zastosowanie |
GET /companies/:companyId/approval/rules?websiteId=¤cy= |
approvals |
path: companyId; query: websiteId, opcj. currency |
Reguły akceptacji firmy dla kanału/waluty. |
POST /approval/rules |
approvals |
body: request — reguła |
Tworzy/aktualizuje regułę progową i zwraca ją. |
GET /approval/rules/:ruleId/approvers |
approvals |
path: ruleId |
Tablica przypisanych akceptujących, w kolejności sortOrder. |
POST /approval/approvers |
approvals |
body: request — akceptujący |
Zapisuje przypisanie klienta jako akceptującego. |
GET /companies/:companyId/approval/required?websiteId=&grandTotal=¤cy= |
approvals |
path: companyId; query: websiteId, grandTotal, currency |
Boolean: czy kwota wymaga akceptacji. |
POST /approval/requests |
approvals |
body: request — wniosek akceptacji |
Tworzy request dla zamówienia i zwraca go. |
GET /companies/:companyId/approval/requests?websiteId=&status= |
approvals |
path: companyId; query: websiteId, opcj. status |
Tablica requestów akceptacji firmy. |
POST /approval/requests/:requestId/approve |
approvals |
path: requestId; body: request — decyzja |
Zatwierdza request; zwraca jego aktualny stan. |
POST /approval/requests/:requestId/reject |
approvals |
path: requestId; body: request — decyzja |
Odrzuca request; zwraca jego aktualny stan. |
POST /approval/requests/:requestId/cancel |
approvals |
path: requestId; body: request — decyzja |
Anuluje request; zwraca jego aktualny stan. |
GET /approval/requests/:requestId/decisions |
approvals |
path: requestId |
Historia decyzji dla requestu. |
5.9. Kontekst B2B zamówień
| Metoda i endpoint |
ACL |
Wejście |
Wynik i zastosowanie |
GET /orders/:orderId/b2b-context |
orders |
path: orderId |
Kontekst B2B pojedynczego natywnego zamówienia Magento (np. firma, status akceptacji, limit, eksport). |
GET /companies/:companyId/orders/b2b-context?websiteId=&approvalStatus= |
orders |
path: companyId; query: websiteId, opcj. approvalStatus |
Tablica kontekstów zamówień firmy, opcjonalnie filtrowana statusem akceptacji. |
5.10. RFQ i oferty handlowe
| Metoda i endpoint |
ACL |
Wejście |
Wynik i zastosowanie |
GET /companies/:companyId/quotes?websiteId=&status= |
quotes |
path: companyId; query: websiteId, opcj. status |
RFQ i oferty firmy, opcjonalnie według statusu. |
POST /quotes |
quotes |
body: request — RFQ |
Tworzy robocze RFQ i zwraca je. Dodaj pozycje osobnym endpointem. |
GET /quotes/:quoteId |
quotes |
path: quoteId |
Szczegóły RFQ/oferty. |
GET /quotes/:quoteId/items |
quotes |
path: quoteId |
Tablica pozycji RFQ. |
POST /quotes/items |
quotes |
body: request — pozycja RFQ |
Dodaje SKU i ilość, opcjonalną cenę żądaną/ofertową oraz komentarz. |
GET /quotes/:quoteId/comments |
quotes |
path: quoteId |
Komentarze RFQ. Klient widzi tylko komentarze oznaczone jako widoczne. |
POST /quotes/comments |
quotes |
body: request — komentarz RFQ |
Dodaje wiadomość; authorType i visibleForCustomer określają autora i widoczność. |
GET /quotes/:quoteId/history |
quotes |
path: quoteId |
Historia zmian statusu i zdarzeń RFQ. |
POST /quotes/:quoteId/submit |
quotes |
path: quoteId; body: request — decyzja RFQ |
Przekazuje robocze RFQ do wyceny. |
POST /quotes/:quoteId/make-offer |
quotes |
path: quoteId; body: request — decyzja RFQ |
Handlowiec tworzy/przekazuje ofertę; przed wywołaniem ustal ceny pozycji. |
POST /quotes/:quoteId/accept |
quotes |
path: quoteId; body: request — decyzja RFQ |
Akceptuje aktualną ofertę. Nie tworzy w tym kontrakcie zamówienia REST. |
POST /quotes/:quoteId/reject |
quotes |
path: quoteId; body: request — decyzja RFQ |
Odrzuca ofertę/RFQ. |
POST /quotes/:quoteId/cancel |
quotes |
path: quoteId; body: request — decyzja RFQ |
Anuluje RFQ, jeśli pozwala na to bieżący status. |
5.11. Profile i joby integracyjne
| Metoda i endpoint |
ACL |
Wejście |
Wynik i zastosowanie |
GET /integrations/profiles?websiteId=&systemType= |
system_integrations |
query: websiteId, opcj. systemType |
Profile integracji dla website. |
POST /integrations/profiles |
system_integrations |
body: request — profil integracji |
Zapisuje profil ERP/PIM/WMS itp. i zwraca go. |
POST /integrations/mappings |
system_integrations |
body: request — mapowanie |
Zapisuje parę lokalny ID ↔ zewnętrzny ID. |
GET /integrations/mappings/local?websiteId=&systemType=&entityType=&localId= |
system_integrations |
query: wszystkie parametry wymagane |
Odszukuje mapowanie po identyfikatorze Magento. |
GET /integrations/mappings/external?websiteId=&systemType=&entityType=&externalId= |
system_integrations |
query: wszystkie parametry wymagane |
Odszukuje mapowanie po identyfikatorze systemu zewnętrznego. |
POST /integrations/jobs |
system_integrations |
body: request — job |
Publikuje job do wykonania; idempotencyKey identyfikuje operację biznesową. |
GET /integrations/jobs?websiteId=&status= |
system_integrations |
query: websiteId, opcj. status |
Tablica jobów integracyjnych. |
GET /integrations/jobs/:jobId |
system_integrations |
path: jobId |
Stan i szczegóły pojedynczego joba. |
POST /integrations/jobs/:jobId/process |
system_integrations |
path: jobId |
Przetwarza job i zwraca jego aktualny stan. |
POST /integrations/jobs/:jobId/retry |
system_integrations |
path: jobId |
Ponawia job po błędzie, zgodnie z jego limitem prób. |
GET /integrations/jobs/:jobId/logs |
system_integrations |
path: jobId |
Logi wykonania joba. |
GET /integrations/jobs/:jobId/errors |
system_integrations |
path: jobId |
Błędy domenowe/techniczne joba. |
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¤cy=$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
- Odczytaj konfigurację website i zapisz przekazane
websiteId, companyId, walutę.
- Użyj quick order do zbiorczej walidacji SKU, ilości, widoczności i dostępności.
- Dla zaakceptowanych pozycji pobierz cenę z
price z właściwym qty.
- Utwórz RFQ, dodaj pozycje i wyślij je przez
submit, jeśli zakup wymaga oferty.
- Ś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
- Pobierz listę dokumentów firmy, opcjonalnie filtrując
documentType.
- 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.
- Odczytaj status limitu przed procesem zakupowym; tylko integracja z ACL
credit_limits może nim zarządzać.
Operacje asynchroniczne
- Zapisz profil integracji i mapowania identyfikatorów.
- Opublikuj job z biznesowym
idempotencyKey i zachowaj jobId.
- 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.
