Articles in this section

Punchout Technical Details (cXML)

  • Updated

1. Implement the PunchOut setup handling (see PunchOutSetupRequest and PunchOutSetupResponse below). This should be available at the url configured above (e.g. https://supplier.com/PunchoutSetup).

  • You should authenticate the request based on the supplied Sender identity and Shared secret.
  • The contents of the supplied <BuyerCookie>, <BrowserFormPost>, <To> and <From> elements need to be remembered (see Example PunchOutSetupRequest below).
  • The contents of the returned PunchOutSetupResponse must contain the StartPage/URL element which will be the url the buyer's browser will be redirected to.
Note: The PunchOutSetupRequest message will not be submitted from the buyer's browser but from a server-side process. This means that a browser session for the buyer cannot be created at this point. The browser session can be created when the buyer first visits the StartPage/URL.

 

2. Implement the 'return shopping cart' functionality (see Example PunchOutOrderMessage below).

  • The cXML header should contain the <To> and <From> elements with switched contents from the PunchOutSetupRequest (see examples below).
  • The cXML header should contain the <Sender> element containing:
    • the <Credential> element with a domain of unimarket-user and
    • the <Identity> element containing the unimarket integration username.
  • The <BuyerCookie> element from the PunchOutSetupRequest must be included.
  • An <ItemIn> element for each item in your shopping cart must be created.
  • Submit the constructed PunchOutOrderMessage to the url specified in the <BrowserFormPost> element in the original PunchOutSetupRequest.
    • The preferred submit parameter name is cxml-urlencoded.
Note: The PunchOutOrderMessage message must be submitted from the buyers browser and not from a server-side process (this is required to preserve the buyers cookies).

 

3. Use the Test link to initiate a PunchOut to your store.

Example cXML messages

Example PunchOutSetupRequest (Unimarket --> Supplier)

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.020/cXML.dtd">
<cXML payloadID="907bd336-5242-4e90-8214-4873449f5f17" timestamp="" xml:lang="en-US">
  <Header>
    <From>
      <Credential domain="[FROM_DOMAIN]">
        <Identity>[FROM_IDENTITY]</Identity>
      </Credential>
    </From>
    <To>
      <Credential domain="[TO_DOMAIN]">
        <Identity>[TO_IDENTITY]</Identity>
      </Credential>
    </To>
    <Sender>
      <Credential domain="[SENDER_DOMAIN]">
        <Identity>[SENDER_IDENTITY]</Identity>
        <SharedSecret>[SENDER_SECRTET]</SharedSecret>
      </Credential>
      <UserAgent>Unimarket</UserAgent>
    </Sender>
  </Header>
  <Request deploymentMode="production">
    <PunchOutSetupRequest operation="create">
      <BuyerCookie>907bd336-5242-4e90-8214-4873449f5f17</BuyerCookie>
      <Extrinsic name="User">buyer-username</Extrinsic>
      <Extrinsic name="UserEmail">buyer@email.com</Extrinsic>
      <Extrinsic name="UniqueName">buyer-username</Extrinsic>
      <BrowserFormPost>
        <URL>http://community.unimarket-staging.com/ws/cXMLRoundtrip.htm?storeId=216</URL>
      </BrowserFormPost>
      <SupplierSetup>
        <URL>[https://supplier.com/RoundtripSetup]</URL>
      </SupplierSetup>
    </PunchOutSetupRequest>
  </Request>
</cXML>

Example response to PunchOutSetupRequest (Supplier --> Unimarket)

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.020/cXML.dtd">
<cXML payloadID="2009-11-02T13:27:53+10:00" timestamp="2009-11-02T13:27:53+10:00">
  <Response>
    <Status code="200" text="OK"/>
    <PunchOutSetupResponse>
      <StartPage>
        <URL>[https://supplier.com/StartPage]</URL>
      </StartPage>
    </PunchOutSetupResponse>
  </Response>
</cXML>

Example PunchOutOrderMessage (Supplier --> Unimarket)

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.020/cXML.dtd">
<cXML payloadID="2009-11-02T13:29:53+10:00" timestamp="2009-11-02T13:29:53+10:00">
  <Header>
    <From>
      <Credential domain="[TO_DOMAIN]">
        <Identity>[TO_IDENTITY]</Identity>
      </Credential>
    </From>
    <To>
      <Credential domain="[FROM_DOMAIN]">
        <Identity>[FROM_IDENTITY]</Identity>
      </Credential>
    </To>
    <Sender>
      <Credential domain="unimarket-user">
        <Identity>[UNIMARKET_INTEGRATION_USER_ID]</Identity>
      </Credential>
      <UserAgent>Supplier</UserAgent>
    </Sender>
  </Header>
  <Message>
    <Status code="200" text="OK">The shopping session completed successfully.</Status>
    <PunchOutOrderMessage>
      <BuyerCookie>907bd336-5242-4e90-8214-4873449f5f17</BuyerCookie>
      <PunchOutOrderMessageHeader operationAllowed="edit">
        <Total>
          <Money currency="NZD">6.58</Money>
        </Total>
      </PunchOutOrderMessageHeader>
      <ItemIn quantity="1" lineNumber="1">
        <ItemID>
          <SupplierPartID>33005141</SupplierPartID>
        </ItemID>
        <ItemDetail>
          <UnitPrice>
            <Money currency="NZD">5.85</Money>
          </UnitPrice>
          <Description xml:lang="en">Reynard antibacterial hand spray pens pkt 3</Description>
          <UnitOfMeasure>EACH</UnitOfMeasure>
          <Classification domain="SPSC">00000000</Classification>          
        </ItemDetail>
      </ItemIn>
    </PunchOutOrderMessage>
  </Message>
</cXML>