PunchOut OCI i cXML - integracja sklepu z SAP Ariba, Coupa

W skrócie

• 1. PunchOut = mechanizm, gdzie klient pozostaje w swoim systemie zakupowym i jednocześnie przegląda twój katalog
• 2. Protokoły: OCI (SAP-owy klasyk, HTML form), cXML (Ariba, Coupa, Jaggaer - XML over HTTPS)
• 3. Workflow: setup request → klient w sklepie → transfer cart → purchase order
• 4. Koszt wdrożenia: 30-80 tys. zł dla średniego scope
• 5. Time-to-launch: 2-4 miesiące (z testami u klienta korporacyjnego)

Workflow PunchOut krok po kroku

1. Klient w SAP Ariba
   - Kupiec szuka produktów
   - Widzi tile "Procure from Supplier ACME" (twój sklep skonfigurowany)
   - Klika

2. Ariba wysyła PunchOutSetupRequest
   - cXML XML do twojego endpointu /punchout/setup
   - Zawiera: identifier klienta (BuyerCookie, From, To), credentials (shared secret)

3. Twój sklep odbiera setup request
   - Waliduje shared secret
   - Tworzy sesję dla klienta (z kontekstem: kto, jaki cennik)
   - Zwraca PunchOutSetupResponse z URL przekierowania

4. Ariba przekierowuje klienta
   - Klient ląduje w twoim sklepie zalogowany automatycznie
   - Widzi swój katalog (cennik kontraktowy, restricted assortment)

5. Klient buduje koszyk
   - Standardowy UX twojego sklepu (PDP, PLP, koszyk)
   - Filtry, search, kategorie

6. Klient klika "Transfer to Cart"
   - W trybie PunchOut zamiast "Złóż zamówienie"
   - Twój sklep generuje cXML PunchOutOrderMessage z listą produktów
   - Przekierowuje przeglądarkę z form POST do Ariby

7. Ariba odbiera koszyk
   - Pokazuje w panelu kupca
   - Workflow akceptacji w Aribie (budżet, kierownik, finanse)

8. Po akceptacji w Aribie
   - Ariba generuje PurchaseOrder (cXML)
   - Wysyła do twojego endpointu /punchout/po
   - Twój sklep waliduje, konwertuje na zamówienie wewnętrzne
   - Zamówienie idzie do ERP (faktura, realizacja)

Cały workflow trwa typowo 30 sekund-15 minut (zależnie od korporacyjnego workflow akceptacji po stronie klienta).

OCI vs. cXML

Dwa protokoły, różne pochodzenie:

OCI (Open Catalog Interface).

• Pochodzenie: SAP, koniec lat 90.
• Format: HTML form fields (NEW_ITEM-DESCRIPTION[1], NEW_ITEM-PRICE[1])
• Transmisja: HTTP POST z form data
• Używane głównie przez klasyczny SAP SRM
• Wciąż obecne w starszych instalacjach

cXML (commerce XML).

• Pochodzenie: Ariba, lata 2000.
• Format: pure XML
• Transmisja: HTTPS POST z XML body
• Używane przez SAP Ariba, Coupa, Jaggaer, Mercateo, większość nowoczesnych systemów zakupowych
• Standard dzisiaj

Większość nowych integracji to cXML. OCI wciąż występuje w starszych SAP-owych projektach.

cXML Setup Request - przykład

<?xml version="1.0"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.060/cXML.dtd">
<cXML payloadID="12345.67890@buyer.com" timestamp="2026-06-17T10:30:00+02:00">
  <Header>
    <From>
      <Credential domain="DUNS">
        <Identity>123456789</Identity>
      </Credential>
    </From>
    <To>
      <Credential domain="DUNS">
        <Identity>987654321</Identity>
      </Credential>
    </To>
    <Sender>
      <Credential domain="DUNS">
        <Identity>123456789</Identity>
        <SharedSecret>twoj_shared_secret</SharedSecret>
      </Credential>
      <UserAgent>Ariba Network</UserAgent>
    </Sender>
  </Header>
  <Request>
    <PunchOutSetupRequest operation="create">
      <BuyerCookie>session-cookie-abc-123</BuyerCookie>
      <Extrinsic name="User">Jan Kowalski</Extrinsic>
      <Extrinsic name="UserEmail">j.kowalski@klient.pl</Extrinsic>
      <BrowserFormPost>
        <URL>https://buyer.com/punchout-return</URL>
      </BrowserFormPost>
      <SupplierSetup>
        <URL>https://yoursklep.pl/punchout/setup</URL>
      </SupplierSetup>
    </PunchOutSetupRequest>
  </Request>
</cXML>

Twój sklep odbiera ten XML, parsuje, autoryzuje, tworzy sesję, zwraca PunchOutSetupResponse z URL przekierowania.

Architektura wdrożenia

[Klient w SAP Ariba]
    |
    | (1) HTTPS POST: cXML PunchOutSetupRequest
    v
[Twój sklep - endpoint /punchout/setup]
    |
    +-- waliduje shared secret
    +-- tworzy sesję PunchOut (z kontekstem: klient, cennik, allowed catalog)
    +-- zwraca cXML PunchOutSetupResponse z URL
    |
    | (2) Browser redirect
    v
[Klient w twoim sklepie]
    |
    | (3) klient buduje koszyk, klika "Transfer to Cart"
    v
[Twój sklep generuje PunchOutOrderMessage cXML]
    |
    | (4) Browser POST do URL w Ariba
    v
[SAP Ariba - odbiera koszyk]
    |
    | (5) Workflow akceptacji w Aribie
    v
[Po akceptacji - Ariba wysyła PurchaseOrder cXML]
    |
    | (6) HTTPS POST do twojego endpointu /punchout/po
    v
[Twój sklep tworzy zamówienie, wysyła do ERP]

Co musisz zbudować po stronie sklepu

1. Endpoint setup (/punchout/setup):

• Odbiera PunchOutSetupRequest
• Parsuje cXML (biblioteki: php-cxml, lub własny SimpleXML)
• Waliduje shared secret
• Identyfikuje klienta (po From / Identity / Extrinsic fields)
• Tworzy sesję PHP (lub JWT) z kontekstem PunchOut
• Zwraca PunchOutSetupResponse z URL przekierowania

2. Tryb PunchOut w sklepie:

• Detection sesji PunchOut (specjalny cookie / session flag)
• Customizacja UI (przycisk "Transfer to Cart" zamiast "Złóż zamówienie")
• Wyświetla katalog zgodny z kontraktem klienta

3. Endpoint transfer (cart → Ariba):

• Generuje cXML PunchOutOrderMessage z koszyka
• Form POST z body cXML do URL otrzymanego w setup'ie

4. Endpoint Purchase Order (/punchout/po):

• Odbiera cXML PurchaseOrder od Ariby
• Waliduje (signature, shared secret)
• Konwertuje na zamówienie wewnętrzne (przemapowanie pól)
• Wysyła do ERP normalnie (kolejka, integracja)

Implementacja w platformach

Adobe Commerce:

• Częściowo wbudowane (Magento_PunchOut module dla niektórych use-case'ów)
• Najczęściej extension komercyjna (Aheadworks PunchOut, Webkul)

Magento Open Source:

• Custom development
• Lub extension komercyjna

Shopware Enterprise B2B Suite:

• Wbudowane OCI support
• cXML wymaga rozszerzenia

Custom (Symfony / Laravel):

• Library php-cxml lub własny SimpleXML
• Symfony Workflow dla state management
• 4-8 tygodni pracy dewelopera dla MVP

Testowanie z klientem korporacyjnym

To największe wyzwanie. Klient SAP-owy ma:

• Środowisko TEST i PROD w Aribie
• Własne procedury testowania (sometimes 4-6 tygodni)
• Wymóg shared secret zarejestrowany u nich
• Procedury bezpieczeństwa (whitelist IP, mTLS jako opcja)

Typowy timeline:

1. Kick-off z klientem (2 tyg.)
2. Konfiguracja shared secret + URL endpoint (1 tyg.)
3. Pierwsze testy setup → klient w sklepie (2 tyg.)
4. Testy transfer to cart (2 tyg.)
5. Testy purchase order (2 tyg.)
6. End-to-end z prawdziwym workflow akceptacji (2 tyg.)
7. UAT + go-live (2-4 tyg.)

Razem 13-17 tygodni od kick-off do produkcji. Może być dłużej, jeśli klient SAP-owy ma slow change management.

Najczęstsze problemy

1. Shared secret hardcoded w kodzie. Niebezpieczne. Trzymaj w environment variable / vault.

2. Brak walidacji XML schema. Klient wysłał uszkodzony cXML, twój parser się rozsypał. Zawsze walidacja przed parsowaniem.

3. Encoding cXML. Polskie znaki w opisach produktów. UTF-8 wszędzie obowiązkowe.

4. Brak audit trail PunchOut. Zamówienie z PunchOut ma inną ścieżkę niż klasyczne. Loguj wszystkie cXML in/out dla debugowania.

5. Tryb PunchOut wycieka do regularnych klientów. Klient nie z Ariby przypadkowo zalogowany w trybie PunchOut. Pewna detection sesji.

6. PurchaseOrder bez autentykacji. Ktoś z zewnątrz wysyła fake PO. Twój sklep robi fake zamówienie. Walidacja shared secret obowiązkowa.

Koszt wdrożenia

MVP PunchOut (cXML, jeden klient):

• 30-50 tys. zł
• 2-3 miesiące

Pełny PunchOut (cXML + OCI, wielu klientów konfigurowanych):

• 60-100 tys. zł
• 3-5 miesięcy

Utrzymanie roczne:

• 8-20 tys. zł (każdy nowy klient = trochę konfiguracji + testów)

ROI: jeden poważny klient SAP-owy z kontraktem 500 tys. - 5 mln zł rocznie = inwestycja PunchOut zwraca się w tygodniach.

FAQ

Czy PunchOut wymaga zalogowanego klienta w moim sklepie? Nie wprost. PunchOut tworzy automatyczną sesję dla klienta z kontekstem (cennik, restricted catalog). Klient nie loguje się klasycznie.

Czy mogę mieć kilku klientów PunchOut? Tak. Każdy klient = osobna konfiguracja (shared secret, URL, kontekst). Skala: dziesiątki klientów PunchOut bez problemu.

PunchOut a EDI - różnica? EDI = wymiana dokumentów (zamówienie, faktura) asynchronicznie. PunchOut = interaktywne przeglądanie katalogu. Czasem oba dla tego samego klienta.

Czy Coupa to ten sam standard co Ariba? Tak, oba używają cXML. Różnice w niektórych field-ach, ale baza taka sama.

Czy mogę używać PunchOut bez SAP-a po mojej stronie? Tak. Twoja platforma (Magento, Shopware, custom) implementuje cXML. SAP jest tylko po stronie klienta korporacyjnego.

Co dalej

• Słownik PunchOut: Czym jest PunchOut
• Pillar procesów B2B: Procesy zakupowe B2B
• Integracja z SAP: Integracja z SAP S/4HANA
• Platforma: pillar /platformy-ecommerce-b2b