PunchOut Integration
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: PunchOut SetupResponse
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 Populates Workspace
Inside of Adaptive Catalog, the user will either populate the newly created PunchOut workspace with a bill of materials, or select an existing workspace. Once ready, they will click the Submit button to proceed.
Step 4: PunchOutOrderMessage
When the user clicks the Submit button in Adaptive Catalog, they will be directed to the supplied BrowserPostForm.URL with the following payload as an HTTP POST.
<?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>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.