PunchOut Overview

Adaptive Catalog supports both the cXML PunchOut protocol as well as a more modern JSON based PunchOut. These systems allow users to seamlessly navigate from their quoting tool, CRM, or any other system to Adaptive Catalog to find products, and return with the full product details.

cXML PunchOut Process

Step 1: PunchOutSetupRequest

Call https://api.adaptivecatalog.com/api/punchout/setup/xml with the following request:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.040/cXML.dtd">
<cXML payloadID="[email protected]" timestamp="2018-10-09T02:06:05+00:00">
  <Header>
    <From>
      <Credential domain="NetworkId">
        <Identity>[email protected]</Identity>
      </Credential>
    </From>
    <To>
      <Credential domain="NetworkId">
        <Identity>[email protected]</Identity>
      </Credential>
    </To>
    <Sender>
      <Credential domain="NetworkId">
        <Identity>{USER EMAIL}</Identity>
        <SharedSecret>{API KEY}</SharedSecret>
      </Credential>
      <UserAgent>Application Name v1.2.3</UserAgent>
    </Sender>
  </Header>
  <Request deploymentMode="production">
    <PunchOutSetupRequest operation="create">
      <BuyerCookie>550bce3e592023b2e7b015307f965133</BuyerCookie>
      <BrowserFormPost>
        <URL>{YOUR POST URL}</URL>
      </BrowserFormPost>
    </PunchOutSetupRequest>
  </Request>
</cXML>

The only fields that Adaptive Catalog will currently read are

Header.Sender.Credential.Identity	The Adaptive Catalog user email address
Header.Sender.Credential.SharedSecret	The Adaptive Catalog API Key
Request.PunchoutSetupRequest.BrowserFormPost.URL	The URL to send the cXML response to upon submission
Header.From.Credential.Domain	Returned with the PunchOutOrderMessage. Can be any string value.
Header.From.Credential.Identity	Returned with the PunchOutOrderMessage. Can be any string value. Generally a username / email.

Step 2: PunchOutSetupResponse

Upon successful validation of the API key and username, Adaptive Catalog will return a cXML PunchOutSetupResponse. You should then direct your users to the Response.Status.PunchOutSetupResponse.StartPage.URL to create their bill of materials.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cXML.org/schemas/cXML/1.2.040/cXML.dtd">
<cXML payloadID="[email protected]" timestamp="2018-04-07T16:16:53-05:00">
  <Response>
    <Status code="200" text="OK"></Status>
      <PunchOutSetupResponse>
        <StartPage>
          <URL>https://app.adaptivecatalog.com/punchout?sessionKey={SESSIONKEY}</URL>
        </StartPage>
      </PunchOutSetupResponse>
  </Response>
</cXML>

Step 3: User Creates Workspace

Inside of Adaptive Catalog, the user will either create a new workspace and assemble the bill of materials, or select an existing workspace. Once ready, they will click the Submit button to proceed.

Step 4: PunchOutOrderMessage

<?xml version="1.0" encoding="UTF-8"?>
<cXML version="1.1" payloadID="2011-04-06T13:15:[email protected]" timestamp="2011-04-06T13:15:06">
   <Header>
      <From>
         <Credential domain="DUNS">
            <Identity>128293714</Identity>
         </Credential>
      </From>
      <To>
         <Credential domain="NetworkId">
            <Identity>YOURIDENTITY</Identity>
         </Credential>
      </To>
      <Sender>
         <Credential domain="DUNS">
            <Identity>128293714</Identity>
            <SharedSecret>nopassword</SharedSecret>
         </Credential>
         <UserAgent>Dell cXML V1.1</UserAgent>
      </Sender>
   </Header>
   <Message deploymentMode="test">
      <PunchOutOrderMessage>
         <PunchOutOrderMessageHeader operationAllowed="edit">
            <Total>
               <Money currency="USD">1453.00</Money>
            </Total>
         </PunchOutOrderMessageHeader>
         <ItemIn quantity="1">
            <ItemID>
               <SupplierPartID>223-4511</SupplierPartID>
               <SupplierPartAuxiliaryID>1006910622287\1</SupplierPartAuxiliaryID>
            </ItemID>
            <ItemDetail>
               <UnitPrice>
                  <Money currency="USD">1453.00</Money>
               </UnitPrice>
               <Description xml:lang="en">OptiPlex 755 Energy Smart Minitower</Description>
               <UnitOfMeasure>EA</UnitOfMeasure>
               <Classification domain="UNSPSC">43211507</Classification>
               <ManufacturerPartID>223-4511</ManufacturerPartID>
               <ManufacturerName>Dell</ManufacturerName>
               <Extrinsic name="Image">{URL}</Extrinsic>
               <Extrinsic name="Notes">These are item notes</Extrinsic>
            </ItemDetail>
         </ItemIn>
                 <ItemIn quantity="1">
            <ItemID>
               <SupplierPartID>32023</SupplierPartID>
               <SupplierPartAuxiliaryID>392002</SupplierPartAuxiliaryID>
            </ItemID>
            <ItemDetail>
               <UnitPrice>
                  <Money currency="USD">894.00</Money>
               </UnitPrice>
               <Description xml:lang="en">Dell UltraSharp 4K 27" Display</Description>
               <UnitOfMeasure>EA</UnitOfMeasure>
               <Classification domain="UNSPSC">43211507</Classification>
               <ManufacturerPartID>303002</ManufacturerPartID>
               <ManufacturerName>Dell</ManufacturerName>
               <Extrinsic name="Image">{URL}</Extrinsic>
               <Extrinsic name="Notes">These are item notes</Extrinsic>
            </ItemDetail>
         </ItemIn>
      </PunchOutOrderMessage>
   </Message>
</cXML>

A list of extrinsic fields currently included are:

Field	Description
Image	A URL to the product image
Notes	HTML encoded product description

JSON PunchOut Process

While the procedure for the JSON PunchOut process is similar, the calls are slightly different and more information is provided.

Check out our demo application for an example of how the punchout flow works in practice: https://github.com/adaptivecatalog/ac-examples-punchout

Step 1: Call the JSON PunchOut Setup Endpoint

First make a POST call to https://api.adaptivecatalog.com/api/jsonpunchout/setup endpoint with the following information:

{
    "company": "{USER'S COMPANY NAME}",
    "username": "{USER'S ADAPTIVE CATALOG USERNAME}",
    "apiKey": "{USER'S API KEY}",
    "callbackUrl": "{URL FOR YOUR CALLBACK ENDPOINT}"
}

If the API Key, username, and company all match, Adaptive Catalog will respond with the redirect URL including a session key. Your app should redirect to this URL on the front-end, which will bring the user to Adaptive Catalog.

{
    "url": "{URL}"
}

Step 2: User Creates Workspace

Inside of Adaptive Catalog, the user will either create a new workspace and assemble the bill of materials, or select an existing workspace. Once ready, they will click the Submit button to proceed.

Step 3: PunchOut Callback

Clicking Submit from the application when in JSON Punchout mode will POST the payload below to the callback endpoint specified in your setup request. Your application will need to store this information for later use.

Payload From Adaptive Catalog:

{
    "id": "{ID FOR THIS PUNCHOUT RESPONSE}"
  "items": [
        {
      "id": "{ADAPTIVE CATALOG PRODUCT ID}",
      "description": "{FULL PRODUCT DESCRIPTION IN HTML}",
      "manufacturerName": "{PRODUCT MANUFACTURER}",
      "manufacturerPartNumber": "{PRODUCT MFP}",
      "msrp": 0.0,
      "name": "{PRODUCT NAME}",
      "imageUrl": "{URL TO PRODUCT IMAGE}",
      "category": "{PRODUCT CATEGORY}",
      "subCategory": "{PRODUCT SUB-CATEGORY}",
            "vendorName": "{PRODUCT VENDOR NAME FROM BEST AVAILABLE VENDOR}",
            "vendorPartNumber": "{PRODUCT VENDOR NAME FROM BEST AVAILABLE VENDOR}",
      "attributes": {
        "key1": "value1",
        "key2": "value2",
        "key3": "value3"
      },
      "facets": {
        "key1": "value1",
        "key2": "value2",
        "key3": "value3"
      },
      "segment": "{HIGH LEVEL PRODUCT CATEGORY}",
            "unitPrice": "{PRICE SPECIFIED IN WORKSPACE}",
            "quantity": "{QUANTITY SPECIFIED IN WORKSPACE}"
        }
  ]
}

Your App’s Response:

"https://myappfrontend.com/punchout?{Possible Parameters}"

Step 4: PunchOut Redirect

Your endpoint that receives this payload will then return a URL that Adaptive Catalog will redirect to on the front-end. We recommend including a parameter that will reference the stored callback payload from the previous step (ex: https://myappfrontend.com/punchout?id={punchoutId}). From here, it is up to you to decide how you’d like to display the data from the punchout in your application.