Dokumentacja PunchOut Rocket

1. Wprowadzenie

Poradnik prowadzi przez konfigurację PunchOut Rocket od konta do pierwszej sesji PunchOut, aby sklep połączył się z systemami eProcurement klientów.

PunchOut Rocket to bramka SaaS łącząca sklep WooCommerce, Magento 2, PrestaShop, nopCommerce lub dedykowany z systemami zakupowymi takimi jak SAP Ariba, Coupa i Jaggaer przez cXML lub OCI. Klient rozpoczyna PunchOut z systemu zakupowego, kupuje w sklepie z cenami kontraktowymi i zwraca koszyk, aby utworzyć wniosek zakupowy.

Poradnik obejmuje pięć obszarów:

1. Zarządzanie kontem: rejestracja, panel, profil i dane rozliczeniowe, uwierzytelnianie dwuskładnikowe i odzyskiwanie hasła.
2. Konfiguracja witryny sklepu: sklep, plan i subskrypcja, ustawienia połączenia i funkcje planu.
3. Konfiguracja klientów końcowych: jeden klient końcowy na firmę kupującą, z predefiniowanymi koszykami i importem zamówień.
4. Konfiguracja wtyczki na platformie e-commerce.
5. Testy i monitorowanie: sesje testowe, dzienniki komunikacji i zamówień.

Końcowe sekcje wyjaśniają ramki, pliki cookie, reverse proxy i rozwiązania najczęstszych problemów. Protokoły opisuje cXML a OCI, a każde pojęcie znajduje się w słowniku.

2. Zarządzanie kontem

2.1 Rejestracja i pierwsze logowanie

1. Proszę otworzyć platform.punchoutrocket.com i kliknąć Register.
2. Należy wpisać imię i nazwisko, dane firmy i dane rozliczeniowe: kraj, adres, miasto, kod pocztowy, prowincję lub stan i numer VAT. Firmy włoskie wpisują też kod SDI lub adres PEC.
3. Należy wpisać adres email i bezpieczne hasło, a następnie kliknąć Create Account.
4. Po zalogowaniu otwiera się Dashboard.

30-dniowy bezpłatny okres próbny zaczyna się wraz z kontem i nie wymaga karty kredytowej. Podczas niego aktywne są wszystkie funkcje, także Premium (predefiniowane koszyki i import zamówień).

2.2 Dashboard

• Key metrics: liczba skonfigurowanych witryn sklepu i klientów końcowych.
• System overview: kolejny krok konfiguracji. Gdy witryna i pierwszy klient końcowy są gotowi, panel wyświetla You’re All Set!
• System info: obsługiwane środowiska, protokoły i platformy.
• Quick Actions: Test OCI PunchOut i Test CXML PunchOut otwierają strony testowe (zobacz sekcję 6.1).

2.3 Zarządzanie profilem i danymi rozliczeniowymi

Należy otworzyć My Account › My Profile z lewego paska bocznego.

• User information: można zmienić imię, nazwisko i hasło. Adres email jest nazwą użytkownika i nie można go zmienić.
• Company information: nazwa firmy, numer VAT, adres, miasto, kod pocztowy i prowincja lub stan. Te dane są na fakturach. Firmy włoskie muszą wpisać kod SDI lub adres PEC.
• Country: kraj określa sposób rozliczania VAT na fakturach (włoski VAT dotyczy tylko firm włoskich). Po ustawieniu może go zmienić tylko nasz zespół wsparcia.

Kliknięcie Save zapisuje zmiany. Nowe dane rozliczeniowe są też wysyłane do systemu płatności i obowiązują od kolejnej faktury.

2.4 Uwierzytelnianie dwuskładnikowe emailem (opcjonalne)

Uwierzytelnianie dwuskładnikowe jest opcjonalne i zalecane. Po włączeniu każde logowanie wymaga jednorazowego 6-cyfrowego kodu wysłanego na zarejestrowany adres email.

• Logowanie z 2FA: należy wpisać email i hasło, otworzyć email z kodem, wpisać go na stronie Enter One-time Code i kliknąć Verify. Kody wygasają po 5 minutach: po wygaśnięciu trzeba zalogować się ponownie, aby otrzymać nowy.
• Włączenie: z komunikatu bezpieczeństwa w Dashboard (Enable 2FA in My Profile) lub w My Profile należy zaznaczyć Enable OTP login verification w Two-Factor Authentication i kliknąć Save. Obowiązuje od następnego logowania.
• Wyłączenie: w My Profile należy odznaczyć to samo pole i kliknąć Save.

Przed włączeniem należy upewnić się, że jest dostęp do skrzynki email. Jeśli kod nie dociera, warto sprawdzić spam.

2.5 Zapomniane hasło

1. Na stronie logowania należy kliknąć Forgot your password?
2. Należy wpisać adres email konta i potwierdzić.
3. W otrzymanym emailu należy kliknąć link resetowania. Link jest ważny przez 4 godziny.
4. Należy wpisać nowe hasło. Zostanie też wysłany email potwierdzający zmianę.

3. Konfiguracja witryny sklepu

Należy dodać sklep, wybrać plan i uzupełnić ustawienia połączenia.

3.1 Dodanie witryny sklepu

W panelu Get Started w Dashboard należy kliknąć + Add Your First E-commerce Site (lub My Account › My E-commerce Sites › Add E-commerce Site) i uzupełnić:

• Site Name: wewnętrzna etykieta, np. „Sklep B2B mojej firmy”. Wyznacza też adres reverse proxy.
• Site URL: pełny adres sklepu, łącznie z https://.
• E-commerce Platform: platforma wybrana z listy, np. WooCommerce.
• Dane dostępowe połączenia dla platformy (zobacz 3.4).

Należy kliknąć Save.

3.2 Wybór planu i subskrypcji

Strona witryny pokazuje pozostałe dni okresu próbnego i status subskrypcji. Dostępne są dwa plany: Standard i Premium, który dodaje import zamówień zakupu i predefiniowane koszyki.

1. W Subscription Details należy kliknąć Subscribe · Standard lub Subscribe · Premium.
2. Należy wpisać dane płatności na bezpiecznej stronie płatności Stripe.
3. Po potwierdzeniu płatności należy kliknąć Back to Site Settings.

Po wyborze Standard funkcje Premium są wyłączane na końcu okresu próbnego: predefiniowane koszyki pozostają zapisane, ale nie są już oferowane klientom. Premium utrzymuje je aktywne.

Jeśli uzgodniliśmy indywidualną cenę, strona witryny oferuje zamiast tego jeden plan Custom. Plany i pakiety klientów są w cenniku.

3.3 Zmiana planu lub zarządzanie subskrypcją

Przy aktywnej subskrypcji opłacanej kartą strona witryny pokazuje:

• Upgrade to Premium: okno pokazuje kwotę do zapłaty dziś (proporcjonalną różnicę do daty odnowienia plus VAT), obciążaną kartę, cenę od następnego odnowienia i odblokowane funkcje. Po kliknięciu Pay and upgrade funkcje działają od razu.
• Downgrade to Standard: okno pokazuje saldo za niewykorzystany czas Premium, odliczane od kolejnej faktury, i funkcje wyłączane od razu. Dziś nic nie jest pobierane.
• Manage your subscription: otwiera bezpieczny portal klienta Stripe, gdzie można sprawdzić plan i kolejną datę płatności, zmienić metodę płatności, zaktualizować dane rozliczeniowe, pobrać faktury lub anulować subskrypcję.

3.4 Uzupełnienie ustawień witryny

Część ustawień zależy od platformy; te są wspólne dla wszystkich witryn:

• Use Reverse Proxy: domyślnie włączone. Podczas sesji PunchOut sklep jest udostępniany przez PunchOut Rocket, co omija blokady ramek i plików cookie systemów zakupowych bez zmian na serwerze. Zobacz sekcję 7.
• Reverse Proxy URL: tylko do odczytu, generowany z Site Name. To punkt wejścia sesji PunchOut; nie ustawia się go ręcznie.
• DUNS number and ANID (Ariba Network ID): opcjonalne identyfikatory cXML. Należy je wpisać, jeśli wymaga ich klient: są zwracane z koszykiem.
• API credentials: przechowywane w postaci zaszyfrowanej. Po zapisie widoczne są tylko ostatnie 4 znaki. Puste pole hasła zachowuje zapisaną wartość. Nowe hasła muszą mieć co najmniej 10 znaków.

WordPress / WooCommerce

• API Username: użytkownik WordPress używany przez PunchOut Rocket dla REST API.
• API Password: hasło aplikacji tego użytkownika, utworzone w profilu zgodnie z dokumentacją haseł aplikacji WordPress.

Magento 2 / Adobe Commerce

• API Username: administrator Magento używany dla REST API.
• API Password: hasło tego administratora.

nopCommerce, PrestaShop 8+ i platformy dedykowane

• API Key: należy kliknąć Generate, aby utworzyć unikalny tajny klucz, skopiować go i wkleić w ustawieniach wtyczki PunchOut Rocket (lub integracji dedykowanej). Po zapisie widoczne są tylko ostatnie 4 znaki.
• Dla sklepu dedykowanego integrację opisuje specyfikacja integracji.

3.5 Funkcje planu

Sekcja Features strony witryny pokazuje funkcje zawarte w planie lub bezpłatnym okresie próbnym:

• Predefined carts: można przygotować gotowe koszyki dla każdego klienta końcowego, a klienci wysyłają je do systemu zakupowego jednym kliknięciem (zobacz 4.5).
• OrderRequest: witryna przyjmuje zamówienia zakupu cXML klientów i tworzy odpowiadające im zamówienia w sklepie (zobacz 4.6).

Funkcje wynikają z planu i nie można ich tu zmieniać: konfiguruje się je dla każdego klienta końcowego.

Brakuje czasu na samodzielną konfigurację? Go-Live Assist: nasz zespół skonfiguruje połączenie za Państwa.

4. Konfiguracja klientów końcowych

Klient końcowy to jedna z Państwa firm kupujących, otwierająca katalog z systemu zakupowego. Każdy klient końcowy ma własne ustawienia połączenia.

4.1 Utworzenie nowego klienta końcowego

Na stronie edycji witryny należy znaleźć Associated End Customers i kliknąć + Add End Customer. Można też użyć My Account › My End Customers.

4.2 Ustawienia ogólne

• Name: etykieta firmy klienta.
• Email: kontaktowy adres email klienta (opcjonalnie).
• E-commerce User to Clone: email lub nazwa dedykowanego użytkownika sklepu. Jego rola i uprawnienia wyznaczają katalog i ceny widoczne dla klienta: podczas PunchOut bramka otwiera sklep z sesją tego użytkownika.
• Ecommerce Site: witryna, w której kupuje ten klient.
• Protocol: cXML lub OCI, zgodnie z wymaganiami systemu klienta.
• Default UNSPSC: kod klasyfikacji wysyłany dla produktów, których kategoria nie ma przypisanego kodu.
• Default Lead Time: szacowany czas dostawy w dniach, wysyłany z każdym artykułem koszyka.
• EA Override and BX Override: zastępują domyślne jednostki miary (EA — sztuka, BX — pudełko) kodami oczekiwanymi przez system klienta, np. PCE.

4.3 Konfiguracja protokołu (cXML i OCI)

Należy wpisać dane dostępowe od działu zakupów klienta. Muszą dokładnie odpowiadać danym w jego systemie.

• cXML: From Identity, Sender Identity, Shared Secret, opcjonalne pola extrinsic i CXML URL do przekazania klientowi jako adres konfiguracji PunchOut.
• OCI: parametry logowania klucz–wartość, w tym użytkownik i hasło, opcjonalne pola zwracane z koszykiem i OCI URL do przekazania klientowi.

Gdzie znaleźć wartości dla każdego systemu: SAP Ariba, Coupa, Jaggaer, SAP przez OCI.

4.4 Mapowanie kategorii

1. Należy kliknąć Update from e-commerce, aby zaimportować drzewo kategorii.
2. W miarę możliwości należy wpisać właściwy kod UNSPSC dla każdej kategorii.

Zmapowane kategorie zapewniają systemowi klienta dokładniejsze dane produktów oraz poprawne zatwierdzanie i raportowanie zakupów. Zobacz kategorie PunchOut i UNSPSC.

4.5 Predefiniowane koszyki Premium

Predefiniowany koszyk to gotowa lista produktów dla jednego klienta końcowego, np. comiesięczne uzupełnienie biura. Na początku sesji PunchOut klient może wysłać ją do systemu zakupowego jednym kliknięciem, bez przeglądania sklepu.

Sekcja jest widoczna, gdy plan (lub bezpłatny okres próbny) obejmuje predefiniowane koszyki. Najpierw należy zapisać klienta końcowego, a następnie:

1. Kliknąć Add cart.
2. Wpisać cart name i opcjonalnie description: klient widzi oba pola.
3. Opcjonalnie ustawić Expires on: po tej dacie koszyk nie jest oferowany. Puste pole oznacza koszyk bez daty wygaśnięcia.
4. Dodać produkty, po jednym w wierszu: SKU, Description, Quantity, Unit price i opcjonalnie kod UNSPSC. Suma jest obliczana w trakcie wpisywania.
5. Opcjonalnie dodać image produktu w każdym wierszu przyciskiem obrazu (PNG, JPEG, GIF lub WebP, do 5 MB).
6. Kliknąć Save w koszyku. Każdy koszyk jest zapisywany osobno.

Import wierszy z Excela

• Należy kliknąć Download template, aby pobrać przykładowy plik .xlsx.
• Należy wypełnić kolumny SKU, Description, Quantity, Unit price i UNSPSC (SKU i Description są wymagane), a następnie kliknąć Import from Excel: wiersze zostaną dodane do koszyka.
• Odczytywany jest tylko pierwszy arkusz, do 1000 wierszy. Rozpoznawane są też włoskie nazwy kolumn (Codice, Descrizione, Quantità, Prezzo).

Co widzi klient

Gdy klient rozpoczyna PunchOut (nową sesję, nie edycję istniejącego koszyka) i ma przynajmniej jeden ważny koszyk, przed sklepem otwiera się strona wyboru:

• klient może wyszukiwać koszyki według nazwy, opisu lub SKU produktu;
• Show items pokazuje produkty ze zdjęciem, SKU, ilością i ceną;
• Use this cart wysyła koszyk bezpośrednio do systemu zakupowego, tak jak po zakończeniu procesu w sklepie;
• Continue to the e-commerce otwiera sklep jak zwykle.

Link strony wyboru jest ważny przez 8 godzin od rozpoczęcia sesji.

4.6 Import zamówień przez cXML OrderRequest Premium

Z OrderRequest zamówienia zakupu zatwierdzone w systemie zakupowym klienta trafiają do sklepu jako zwykłe zamówienia. Nie trzeba wpisywać ich ręcznie.

Sekcja Order request Integration klienta końcowego pokazuje:

• Order request URL: adres do przekazania klientowi dla jego zamówień zakupu. Jest ten sam dla wszystkich klientów końcowych witryny: każde zamówienie jest dopasowywane według From identity cXML.
• Shipping Method i Payment Method: metody używane dla zamówień tworzonych w sklepie.

Dla Magento i PrestaShop należy wpisać obie metody do importu zamówień. Dla sklepu dedykowanego obie są przekazywane do endpointu tworzenia zamówień: zobacz specyfikację integracji.

Należy kliknąć Check Logs w tej samej sekcji, aby zobaczyć odebrane zamówienia (zobacz 6.3).

Brakuje czasu na samodzielną konfigurację? Go-Live Assist: nasz zespół skonfiguruje połączenie za Państwa.

5. Konfiguracja wtyczki na platformie e-commerce

1. Należy pobrać i zainstalować wtyczkę PunchOut Rocket dla swojej platformy.
2. Otworzyć stronę ustawień wtyczki w administracji sklepu (w Magento w ustawieniach Sales).
3. Wpisać dane połączenia z sekcji 3.4 i zapisać.

Sklep jest gotowy do odbioru żądań PunchOut.

• WooCommerce: połączenie korzysta z użytkownika API i hasła aplikacji wpisanych w ustawieniach witryny (3.4). Strona wtyczki potwierdza, gdy PunchOut Rocket jest skonfigurowany i gotowy do użycia.
• Magento 2: ustawienia rozszerzenia są w Stores › Configuration › Sales › Punchout Rocket, w grupie Gateway.
• nopCommerce i PrestaShop: należy wkleić klucz API wygenerowany w ustawieniach witryny (3.4) do konfiguracji wtyczki lub modułu i zapisać.

Obsługiwane wersje są na stronie zgodności. Sklep musi być udostępniany przez HTTPS.

Brakuje czasu na samodzielną konfigurację? Go-Live Assist: nasz zespół skonfiguruje połączenie za Państwa.

6. Testy i monitorowanie

6.1 Test sesji PunchOut

Przed przekazaniem adresów URL klientowi można zasymulować jego system zakupowy:

1. W Dashboard, w Quick Actions, należy kliknąć Test CXML PunchOut lub Test OCI PunchOut.
2. Należy wyszukać i wybrać Ecommerce Site, a następnie End Customer: dane dostępowe są wypełniane z jego konfiguracji.
3. Wysłać żądanie testowe: sklep otwiera się tak jak dla klienta i można dodawać produkty oraz zwrócić koszyk.

6.2 Dzienniki komunikacji

1. Należy otworzyć stronę konfiguracji klienta końcowego.
2. W Protocol Configuration kliknąć Check Logs.

Dziennik zawiera każdą sesję PunchOut z czasem, adresem IP i przeglądarką. Dla każdej sesji można otworzyć wymienione komunikaty: żądanie konfiguracji z systemu zakupowego, odpowiedź konfiguracji, koszyk ze sklepu i koszyk odesłany do klienta. To pierwszy punkt kontroli, gdy połączenie nie działa.

6.3 Dzienniki zamówień Premium

W sekcji Order request Integration klienta końcowego należy kliknąć Check Logs. Dla każdego zamówienia zakupu widoczne są czas, numer PO, wynik, numer zamówienia utworzonego w sklepie, zamówienie odebrane z systemu zakupowego i wysłana odpowiedź.

7. Ramki, systemy zakupowe i reverse proxy

Dlaczego systemy zakupowe używają ramek

SAP Ariba, Coupa, Jaggaer i inne systemy często otwierają sklep dostawcy w ramce, aby klient nie opuszczał systemu zakupowego. Powoduje to dwa problemy przeglądarki:

• frame-ancestors: Content Security Policy sklepu nie pozwala portalowi zakupowemu wyświetlać go w ramce, więc ramka pozostaje pusta.
• Pliki cookie SameSite: przeglądarka odrzuca pliki cookie sklepu w ramce, więc klient zostaje wylogowany lub traci koszyk.

Jak reverse proxy rozwiązuje problem

1. Klient klika PunchOut w systemie zakupowym, który wysyła żądanie cXML lub OCI.
2. PunchOut Rocket udostępnia strony sklepu we własnej domenie, więc przeglądarka widzi jedno zaufane źródło.
3. Pliki cookie są własne, więc reguły SameSite ich nie blokują.
4. Klient kupuje jak zwykle, a koszyk wraca do systemu zakupowego przez cXML lub OCI.

Nie trzeba zmieniać konfiguracji serwera.

Wyłączenie wtyczek optymalizacyjnych osadzających pliki

Wtyczki minifikacji takie jak Autoptimize mogą osadzać CSS lub JavaScript jako URI danych Base64. Gdy proxy przepisuje adresy URL, te pliki przestają działać: układ wygląda nieprawidłowo lub skrypty przestają działać.

• Rozwiązanie: przed połączeniem należy wyłączyć minifikację HTML, łączenie CSS i JS oraz osadzanie zasobów w kodzie strony. Przykłady: Autoptimize, opcje „Combine files” w WP Rocket, minifikacja HTML w LiteSpeed Cache. Wtyczki pamięci podręcznej stron, które nie zmieniają adresów URL zasobów, zwykle nie sprawiają problemów.
• Jak sprawdzić: w źródle strony należy wyszukać data:text/css;base64, lub data:application/javascript;base64,.

Wyłączenie reverse proxy (zaawansowane)

Proxy jest domyślnie włączone i zalecamy pozostawić je aktywne. Po wyłączeniu system klienta otwiera serwer bezpośrednio i trzeba skonfigurować:

• nagłówek Content-Security-Policy: frame-ancestors dopuszczający domenę portalu zakupowego;
• SameSite=None; Secure w plikach cookie sesji i logowania.

Ustawienia różnią się dla każdego systemu zakupowego i wymagają aktualizacji dla każdej nowej domeny portalu. W większości paneli hostingu są w ustawieniach nagłówków serwera i plików cookie. Szczegóły w poradniku o błędzie iframe.

8. Rozwiązywanie problemów

Problem nadal występuje? Prosimy napisać na support@punchoutrocket.com, podając nazwę klienta końcowego i czas sesji z dziennika.