Specyfikacja integracji PunchOut dla sklepów dedykowanych

1. Konfiguracja w PunchOut Rocket

Witryna sklepu

Ścieżki endpointów są dołączane do Site URL bez zmian, więc muszą zaczynać się od /. Przykład: Site URL https://your-store.example.com + /api/punchout/clone → https://your-store.example.com/api/punchout/clone.

Zamówienia zakupu (sekcja 6) i predefiniowane koszyki obejmuje plan Premium, także w bezpłatnym okresie próbnym: plan włącza je w witrynie, a strona klienta końcowego pokazuje sekcje Orders i Predefined Carts. Potwierdzenia i awiza wysyłki (sekcje 7–8) wymagają też opcji OC & ASN.

Klient końcowy

Każda firma kupująca jest klientem końcowym witryny. Oprócz danych protokołu (tożsamości cXML i shared secret lub użytkownik i hasło OCI) te pola dotyczą sklepu:

Pozostałe części stron witryny i klienta końcowego działają jak dla innych platform: zobacz dokumentację.

2. Endpoint klonowania

Ścieżka domyślna: /api/punchout/clone. Wywoływany, gdy klient otwiera sklep z systemu zakupowego. Sklep tworzy (lub wykorzystuje ponownie) użytkownika sklonowanego z username, powiązanego z tą sesją PunchOut, i zwraca adres SSO logujący tego użytkownika (sekcja 3).

Treść żądania

quantity i price są ciągami znaków: należy przekonwertować je przed użyciem.

Żądanie: utworzenie z wybranym artykułem

{
  "username": "buyer123",
  "api_key": "site-api-key-abc",
  "session_token": "sess-012345",
  "operation": "create",
  "end_customer_id": 2,
  "gateway_base_url": "https://middleware.example.com",
  "selected_item": {
    "supplier_part_id": "X-100",
    "supplier_part_auxiliary_id": "19853"
  }
}

Żądanie: edit, z koszykiem do odtworzenia

{
  "username": "buyer123",
  "api_key": "site-api-key-abc",
  "session_token": "sess-67890",
  "operation": "edit",
  "end_customer_id": 2,
  "gateway_base_url": "https://middleware.example.com",
  "cart_items": [
    {"sku": "ABC-001", "product_id": "19852", "quantity": "2", "price": "15.95",
     "description": "Example description", "currency": "EUR"},
    {"sku": "XYZ-002", "product_id": "19854", "quantity": "1", "price": "249.00",
     "description": "Another example description", "currency": "EUR"}
  ]
}

Odpowiedź powodzenia

HTTP 2xx

HTTP 200
{
  "status": "success",
  "sso_url": "https://your-store.example.com/punchout/sso?token=eyJ..."
}

sso_url to jedyne odczytywane pole: jest wymagane i musi być bezwzględnym adresem http:// lub https://. PunchOut Rocket kieruje tam przeglądarkę klienta (przez system zakupowy dla cXML, bezpośrednio dla OCI).

Odpowiedzi błędów

Każdy status spoza 2xx lub odpowiedź bez prawidłowego sso_url powoduje błąd PunchOut: klient otrzymuje błąd w systemie zakupowym. Odpowiedź (status i treść) jest zapisywana w dzienniku sesji PunchOut, więc komunikat powinien wyjaśniać przyczynę.

4. Przesyłanie koszyka (formularz automatycznego wysyłania)

Dla użytkownika PunchOut przycisk składania zamówienia nie może uruchamiać zwykłego procesu: wysyła koszyk do PunchOut Rocket. Sklep zwraca stronę HTML automatycznie wysyłającą ukryty formularz, najlepiej ze wskaźnikiem ładowania.

• URL: {gateway_base_url}/start-sso-checkout (gateway_base_url z żądania klonowania)
• Metoda: POST, application/x-www-form-urlencoded (zwykłe wysłanie formularza przeglądarki)
• Bez api_key: sesję identyfikują session_token i end_customer_id.

i zaczyna się od 0 i nie ma luk: PunchOut Rocket kończy odczyt przy pierwszym brakującym indeksie. Należy pamiętać o kodowaniu znaków specjalnych HTML w wartościach.

Przykładowa strona zwracana przy składaniu zamówienia

<!doctype html>
<html>
<body>
<p>Sending your cart to your procurement system…</p>
<form id="punchout_repost" method="post" action="https://middleware.example.com/start-sso-checkout">
  <input type="hidden" name="session_token" value="sess-012345"/>
  <input type="hidden" name="end_customer_id" value="2"/>
  <input type="hidden" name="products[0][sku]" value="ABC-001"/>
  <input type="hidden" name="products[0][product_id]" value="19852"/>
  <input type="hidden" name="products[0][description]" value="Example description"/>
  <input type="hidden" name="products[0][quantity]" value="2"/>
  <input type="hidden" name="products[0][price]" value="15.95"/>
  <input type="hidden" name="products[0][currency]" value="EUR"/>
  <input type="hidden" name="products[0][unit_of_measure]" value="EA"/>
  <input type="hidden" name="products[0][manufacturer_name]" value="3M"/>
  <input type="hidden" name="products[0][category_ids]" value="1145,3398"/>
  <input type="hidden" name="products[1][sku]" value="XYZ-002"/>
  <input type="hidden" name="products[1][product_id]" value="19854"/>
  <input type="hidden" name="products[1][description]" value="Another example description"/>
  <input type="hidden" name="products[1][quantity]" value="4"/>
  <input type="hidden" name="products[1][price]" value="10.90"/>
  <input type="hidden" name="products[1][currency]" value="EUR"/>
  <input type="hidden" name="products[1][manufacturer_name]" value="DEWALT"/>
  <input type="hidden" name="products[1][category_ids]" value="2146"/>
</form>
<script>document.getElementById('punchout_repost').submit();</script>
</body>
</html>

PunchOut Rocket wysyła koszyk do systemu zakupowego i kończy sesję. Sesja przyjmuje tylko jeden koszyk:

7. Endpoint stanu zamówień

Ścieżka domyślna: /api/punchout/order-status. Wywoływany tylko dla klientów końcowych z włączonym „Send order status updates”, dla zamówień utworzonych przez sekcję 6: co godzinę przez 60 dni od zamówienia i od razu po powiadomieniu (sekcja 8). Wymaga opcji OC & ASN. Na podstawie odpowiedzi PunchOut Rocket wysyła do systemu zakupowego klienta:

• potwierdzenie zamówienia (cXML ConfirmationRequest), jednorazowo, gdy zamówienie jest przyjęte lub anulowane;
• awizo wysyłki (cXML ShipNoticeRequest) dla każdej nowej wysyłki potwierdzonego zamówienia.

PunchOut Rocket pamięta, co wysłał: należy zawsze odpowiadać aktualnym stanem zamówienia, a PunchOut Rocket ustali, co jest nowe.

Żądanie: order_id to identyfikator zwrócony przez endpoint tworzenia zamówień

{"api_key": "site-api-key-abc", "order_id": "100045"}

Odpowiedź powodzenia

HTTP 200

HTTP 200
{
  "status": "success",
  "order_status": "shipped",
  "items": ["5501", "5502"],
  "quantities": [
    {"order_item_id": "5501", "quantity": 2},
    {"order_item_id": "5502", "quantity": 1}
  ],
  "shipments": [
    {
      "id": "SH-1",
      "shipped_at": "2026-11-12T09:30:00+01:00",
      "carrier": "UPS",
      "tracking": "1Z999AA10123456784",
      "items": [{"order_item_id": "5501", "quantity": 2}]
    }
  ]
}

Potwierdzenie jest wysyłane raz, gdy zamówienie po raz pierwszy ma stan processing, shipped lub delivered:

• akceptuje całe zamówienie, gdy każdy wiersz PO jest w nim obecny w całości;
• w przeciwnym razie akceptuje każdy wiersz w ilości obecnej w zamówieniu i odrzuca resztę (usunięte artykuły, zmniejszone ilości). Ilość podniesiona ponad PO jest potwierdzana w ilości z PO;
• jeśli nie pozostał żaden wiersz, nic nie jest wysyłane: należy użyć cancelled, aby odrzucić zamówienie.

Późniejsze zmiany artykułów nie są ponownie potwierdzane: zamówienie należy edytować przed przyjęciem.

Wysyłkę należy zgłaszać dopiero po nadaniu. Zmiany po jej zgłoszeniu nie są wysyłane ponownie. Jeśli system zakupowy odrzuci potwierdzenie lub awizo, PunchOut Rocket wysyła je ponownie przy kolejnej kontroli i nie wysyła dalszych komunikatów do chwili akceptacji.

9. Lista kontrolna przed uruchomieniem

1. Należy skonfigurować witrynę (sekcja 1) i wpisać ten sam klucz API w sklepie.
2. Utworzyć klienta końcowego i ustawić jego „E-commerce User to Clone”.
3. Kliknąć „Update from e-commerce” w jego Category Mapping i zmapować kategorie; ustawić Default UNSPSC.
4. Przetestować PunchOut formularzem testowym cXML w panelu administracyjnym: create, potem edit z koszykiem, a następnie zwrócić koszyk.
5. Dla zamówień zakupu (plan Premium): wysłać testowy OrderRequest i sprawdzić zamówienie w sklepie.
6. Dla aktualizacji stanu (opcja OC & ASN): włączyć „Send order status updates” u klienta końcowego, przeprowadzić zamówienie testowe przez używane stany i sprawdzić, czy system klienta odbiera potwierdzenie i awiza wysyłki.

Warto pamiętać:

• Użytkownicy PunchOut nie mogą kończyć procesu składania zamówienia w sklepie: koszyk wraca do systemu zakupowego (sekcja 4), a zamówienie dociera później przez sekcję 6.
• Zamówienia odebrane przez sekcję 6 są już zatwierdzone przez system zakupowy klienta: nie wymagają płatności online.

Potrzebny klient testowy lub przegląd implementacji? Porozmawiaj z naszymi programistami lub zleć nam wdrożenie w ramach Go-Live Assist.