Punchout

  • Punchout (Roundtrip) Integration

    Overview

    Punchout (Roundtrip) functionality allows suppliers to maintain branded content on their own web site and provide buyers with the ability to automatically login by clicking a link within Unimarket. During the login process Unimarket passes the supplier site credentials which authenticate the buyer and allow the supplier to display buyer / account specific items and pricing.

    After products are selected by the buyer, the Punchout service sends the required item details back into Unimarket for purchasing. At this point, the order is routed through the normal requisition and approval processes and eventually converted into a purchase order that is sent back to the supplier for order fulfillment.

    Unimarket supports 2 types of Punchout (Roundtrip) catalog integration:

    1. cXML (preferred)
    2. OCI

    cXML Punch-Out

    For a more in-depth look at cXML PunchOut please see the cXML specification.

     

    Implementation Steps

    Login in to your store and select Create Catalog from the Catalogs menu.

    1image.jpg

     

    Basic Information

    Enter a catalog a name and description (optional). This is the information the customer will see in Unimarket before they click on the Punchout (Roundtrip) link. Select Roundtrip from the Catalog Type drop down menu and choose the Roundtrip Type (cXML or OCI).

    2image.jpg

     

    Punchout (Roundtrip) Credentials

    Configure the Punchout (Roundtrip) URL, Settings and Header Values. Header values are determined by you depending on how you would like to process the PunchOutSetupRequest from Unimarket.

    • URL: Your Punchout (Roundtrip Request) URL.
    • Allow Decimal Quantities: Only enable if your Punchout catalog contains decimal quantity products, (e.g. "1.5 yards of lumber").
    • Product re-use allowed: Leave enabled unless you will also have Punchout Order integration, and that integration does not allow for the same roundtrip product to be re-ordered (i.e. if the customer wants to order the same product again, they need to revisit your Punchout site).
    • Mime Type: Most Punchouts use text/xml.

    3image.jpg

      

    Assign Catalog to Customers

    Select which customer will have access to your new catalog. When the customer has assigned Buyer Groups to the new catalog, it will become available in their marketplace.

    4image.jpg

     

    Upload Index Catalog

    If you plan on using Punchout (Roundtrip) Search functionality, at this point you should upload your Index Catalog. Alternatively if you do not plan on using Punchout (Roundtrip) Search functionality, you can click Finish to create your Punchout (Roundtrip).

    5image.jpg

    Note: For more information on Roundtrip Search, please see Level 2 Punchout Search.

     

    Test Roundtrip

    Once you have configured the Punchout (Roundtrip) you can test using the Actions menu on the top right. If there are issues with the setup you can click View Details to view the error message. You can then amend the roundtrip setup by clicking Edit.

    6image.jpg

    Technical Details (cXML)

    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>

    OCI Punch-Out

    For an OCI (Open Catalog Interface) Punchout follow the steps above, however select Roundtrip Type 'OCI'. Setup of the OCI punch-out requires a URL, Username and Password. Details on the OCI standard can be found here.