Implementation · Eezee Developers

To proceed, make sure that you have the following information ready:

NOTE: Without finishing all 3 steps, you will not be able to test your punchout implementation.

5 Basic Steps to Punchout

There are 5 steps to implementing punchout for your E-Procurement system.

1. Punch Out Setup Request
2. Punch Out Setup Response
3. Redirect to E-Commerce site
4. Add to cart
5. Punch Out Order Message

`1. Punch Out Setup Request`

To start the process, send a Punch Out Setup Request (POSReq) to your supplier's punchout url. The API details, required fields and sample XML document are available below.

API Details

The table below details the HTTP request to the PUNCHOUT_URL_PROVIDED_BY_SUPPLIER.

Property	Value
URL	`PUNCHOUT_URL_PROVIDED_BY_SUPPLIER`
Request Type	"POST"
Content-Type	"application/xml"
BODY CONTENT	XML Document ( See Below )

POSReq XML Document Required Fields

The table below documents all the required fields for a POSReq document to be valid.

As it can be quite tough documenting XML documents, please search under column # from the table below to find where it is in the POSReq sample xml document.

#	Property	Description
{POSReq1}	`*.From.Credential.Identity`	Buyer's Id
{POSReq2}	`*.To.Credential.Identity`	Seller's Id
{POSReq3}	`*.Sender.Credential.Identity`	System's Id
{POSReq4}	`*.Sender.Credential.SharedSecret`	Shared secret
{POSReq5}	`*.PunchOutSetupRequest.BuyerCookie`	A cookie that will be passed back in the POOM when the user has confirmed their cart.
{POSReq6}	`*.PunchOutSetupRequest.Extrinsic[name="UserEmail"]`	The user's email
{POSReq7}	`*.PunchOutSetupRequest.Extrinsic[name="UniqueName"]`	The user's name
{POSReq8}	`*.PunchOutSetupRequest.BrowserFormPost.URL`	The webhook endpoint to send the POOM.
{POSReq9}	`*.PunchOutSetupRequest.ShipTo.Address[addressID]`	The address identifier of the place where the goods will be delivered to.

Sample POSReq XML Document

<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.038/cXML.dtd">
<cXML payloadID="0a109a9d-5302-4a06-9d6d-d9756bc77b96" timestamp="2019-05-16T21:26:43-07:00" xml:lang="en_US">
    <Header>
        <From>
            <Credential domain="NetworkID">
                <!-- {POSReq1} --> 
                <Identity>EZ01098002779-T</Identity> 
            </Credential>
        </From>
        <To>
            <Credential domain="NetworkID">
                <!-- {POSReq2} -->
                <Identity>EZ01459860382-T</Identity>
            </Credential>
        </To>
        <Sender>
            <Credential domain="AribaNetworkUserId">
                <!-- {POSReq3} -->
                <Identity>sysadmin@ariba.com</Identity>
                <!-- {POSReq4} -->
                <SharedSecret>YOUR_SHARED_SECRET</SharedSecret>
            </Credential>
            <UserAgent>CAN BE ANYTHING</UserAgent>
        </Sender>
    </Header>
    <Request>
        <PunchOutSetupRequest operation="create">
            <!-- {POSReq5} -->
            <BuyerCookie>your_unique_browser_cookie_to_identify_user_later</BuyerCookie>
            <Extrinsic name="CostCenter">670</Extrinsic>
            <!-- {POSReq6} -->
            <Extrinsic name="UserEmail">test@eezee.com.sg</Extrinsic>
            <!-- {POSReq7} -->
            <Extrinsic name="UniqueName">catalog_tester</Extrinsic>
            
            <BrowserFormPost>
                <!-- {POSReq8} -->
                <URL>https://example-eezee.com.sg/handle-punchout-order-message-endpoint</URL>
            </BrowserFormPost>

            <SupplierSetup>
                <URL>https://api.eezee.sg/api/link-to-punchout</URL>
            </SupplierSetup>

            <ShipTo>
                <!-- {POSReq9} -->
                <Address addressID="26"></Address>
            </ShipTo>
            <SelectedItem>
                <ItemID>
                    <SupplierPartID>AAA</SupplierPartID>
                    <SupplierPartAuxiliaryID/>
                </ItemID>
            </SelectedItem>
        </PunchOutSetupRequest>
    </Request>
</cXML>>

`2. Punch Out Setup Response`

After sending a punchout setup request to the seller, an XML document containing the Punch Out Setup Response ( POSRes ) will be sent back which contains a url where your system should redirect users to "log" users into the seller as a punchout buyer.

POSRes XML Document Schema

#	Property	Description
{POSRes1}	`*.StartPage.URL`	One time use url to login into seller's E-Commerce website.

Sample POSRes XML document

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.038/cXML.dtd">
<cXML payloadID="ae5ee976-a971-4dd0-b359-196ef1d99a6b" timestamp="2019-12-09 16:12:68" xml:lang="en_US">
    <Response>
        <Status code="200" text="Success"/>
        <PunchOutSetupResponse>
            <StartPage>
                <!-- {POSRes1} -->
                <URL>https://api.eezee.sg/api/user/link-to-login/9UYGO87TFIOTRFGHI9876TFGO9YTGHI8</URL>
            </StartPage>
        </PunchOutSetupResponse>
    </Response>
</cXML>

`3. Redirect to E-Commerce site`

After receiving the POSRes, redirect users to the url at cXML.Response.Status.PunchOutSetupResponse (https://api.eezee.sg/api/user/link-to-login/9UYGO87TFIOTRFGHI9876TFGO9YTGHI8).

Your seller's E-Commerce site will then proceed to log the user in using the link. The user can now proceed to source for items and proceed for a Request To Buy (RTB) process.

Note: The link extracted from cXML.Response.Status.PunchOutSetupResponse can only be used once.

`4. Add to cart`

This portion should be very straight forward.

Source for what you need and add to cart.

`5. Punch Out Order Message`

When you arrive at your seller's check out page, it should display a button that indicates that you will be redirected back to your E-Procurement Software.

Check Out page displaying a product and a check out button.

After clicking that button, a Punch Out Order Message (POOM) encoded in base64 will be sent via HTTPS POST request to the webhook endpoint {POSReq8} provided in the POSReq.

POOM Webhook Details

Property	Value
URL	`WEBHOOK_URL_PROVIDED_BY_BUYER_IN_POSReq` in {POSReq8}
Request Type	"POST"
BODY CONTENT	XML Document formatted in base64 ( See Below )

POOM XML Document Schema

#	Property	Description
{POOM1}	`*.From.Credential.Identity`	Seller's id. NOT the Buyer's id
{POOM2}	`*.To.Credential.Identity`	The Buyer's id. NOT Seller's id
{POOM3}	`*.Sender.Credential.Identity`	Seller's id
{POOM4}	`*.BuyerCookie`	Value received from POSReq {POSReq5}.
{POOM5}	`*.Total.Money[currency]`	ISO currency code
{POOM6}	`*.Total.Money`	Total Price for the entire order
{POOM7}	`*.ItemIn[quantity]`	Quantity of items purchased
{POOM8}	`*.ItemIn.ItemId.SupplierPartID`	Seller product unique id
{POOM9}	`*.ItemIn.ItemId.SupplierPartAuxiliaryID`	Seller cart unique id
{POOM10}	`*.ItemIn.ItemDetail.UnitPrice.Money[currency]`	ISO currency code
{POOM11}	`*.ItemIn.ItemDetail.UnitPrice.Money`	Unit Price for 1 product
{POOM12}	`*.ItemIn.ItemDetail.Description`	Product Title
{POOM13}	`*.ItemIn.ItemDetail.Classification[domain="UNSPSC"]`	Product category taxonomy according to https://www.unspsc.org
{POOM14}	`*.ItemIn.ItemDetail.LeadTime`	Delivery Lead time in days
{POOM15}	`*.ItemIn.SupplierID`	Seller's id. Same as {POOM1}

Sample POOM XML Document

Below is a sample of a POOM document. In production systems, the POOM will be encoded in base64 and sent to the webhook url {POSReq8}.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cXML.org/schemas/cXML/1.2.024/cXML.dtd">
<cXML payloadID="UUID"

        timestamp="2019-10-17 18:10:70" version="1.2.024" xml:lang="en_US">
    <Header>
        <From>
            <Credential domain="NetworkID">
                <!-- {POOM1} -->
                <Identity>XXXXXX-T</Identity>
            </Credential>
        </From>
        <To>
            <Credential domain="NetworkID">
                <!-- {POOM2} -->
                <Identity>YYYYYY-T</Identity>
            </Credential>
        </To>
        <Sender>
            <Credential domain="NetworkID">
                <!-- {POOM3} -->
                <Identity>XXXXXX-T</Identity>
            </Credential>
            <UserAgent>Eezee Punchout</UserAgent>
        </Sender>
    </Header>
    <Message deploymentMode="test">
        <PunchOutOrderMessage>
            <!-- {POOM4} -->
            <BuyerCookie>YOUR_COOKIE_VALUE</BuyerCookie>
            <PunchOutOrderMessageHeader
                operationAllowed="edit" quoteStatus="final">
                <Total>
                    <!-- {POOM5} -->
                    <!-- {POOM6} -->
                    <Money currency="SGD">444.86</Money>
                </Total>
            </PunchOutOrderMessageHeader>
            <!-- {POOM7} -->
            <ItemIn quantity="1">
                <ItemID>
                    <!-- {POOM8} -->
                    <SupplierPartID>5b35b4af4c8c63033d8aea45</SupplierPartID>
                    <!-- {POOM9} -->
                    <SupplierPartAuxiliaryID>5d8b2c564500c71e5a586abf</SupplierPartAuxiliaryID>
                </ItemID>
                <ItemDetail>
                    <UnitPrice>
                        <!-- {POOM10} -->
                        <!-- {POOM11} -->
                        <Money currency="SGD">444.86</Money>
                    </UnitPrice>

                    <!-- {POOM12} -->
                    <Description xml:lang="en_US">Karcher 3 in 1 Spray Extraction SE4001 - Add ons Paper Filter Bags - pkt-5  </Description>
                    <UnitOfMeasure>EA</UnitOfMeasure>

                    <!-- {POOM13} -->
                    <Classification domain="UNSPSC">47121800</Classification>

                    <!-- {POOM14} -->
                    <LeadTime>3</LeadTime>
                </ItemDetail>

                <!-- {POOM15} -->
                <SupplierID domain="NetworkID">XXXXXX-T</SupplierID>
            </ItemIn>
        </PunchOutOrderMessage>
    </Message>
</cXML>