Order Integration: Web Services

The GovX order web service allows you to pull your orders from GovX and then push order status and shipping information (tracking number, shipment method, shipment date, etc) back to GovX. The GovX order web service is easy to use from most systems and offers the most complete and seamless order integration option. 

 

Web Service Overview

The GovX Web Service is a SOAP based service. The SOAP endpoints can be consumed to generate XML order data automatically. These methods will provide the same level of functionality as an EDI integration.

There are three methods related to orders in the GovX web service. All three methods must be called in order to complete the order integration successfully.

Method Description
GetOrders Returns all new orders that have not been acknowledged as received. The GetOrders method is akin to the EDI 850.
SetOrderResponse Confirms receipt for each order, similar to an EDI 855
SetOrderStatus Sets shipped status and tracking info for each order, similar to an EDI 856

 

The web service will be called with an account that is specific to each partner and only that partner's orders will be accessible via the service.

The typical order of events to complete a successful order integration runs as follows:

  • Partner calls GetOrders method, requesting orders with the status of New using the credentials supplied by GovX.
  • For each new order returned by the GetOrders method, partner imports the order information into the integrating system and acknowledges receipt by calling the SetOrderResponse method.
  • Upon shipment of order, partner calls the SetOrderStatus method for each order to close the order and send the shipment and tracking details to GovX.
  • Upon receipt of the tracking information, GovX emails the customer a shipment notification including the tracking supplied in the SetOrderStatus.

 

Getting Started

Step 1 | Create Account

Before calling the GovX web service you will need to have a partner account created in GovX. Your GovX Brand Manager can provide you with the credentials. 

Step 2 | Accessing the Web Service

The Web Service is publicly available on both the staging and production servers using the following URI:

Staging server access is cookie protected. To access the staging server please visit http://staging.govx.com/getcookie.html first.

Please note that there are different credentials for staging and production services. Once the test cycle is complete, GovX will provide you with the appropriate production credentials.

WSDL: To access the WSDL for these services simply add the query string ?wsdl to the URL.

Step 3 | Testing

Before we launch the integration, we will run a few test orders end-to-end. The test orders will be initiated by GovX and will be deemed successful when we receive the SetOrderResponse and SetOrderStatus requests. 

Please note that all request elements should be in the sequence as mentioned in the following examples. If you do not want to pass an optional field, please leave it empty in the request. 

 

Methods

GetOrders method & data dictionary

GetOrders Header Data Dictionary

The order header represents order summary information for all the ordered items. The following data dictionary represents a valid GovX Order Header. Note: if GovX detects that an order is destined to an APO/FPO address the shipping method will be designated as USPS.

Field Name Type Length Description Format/Value
OrderID CHAR 21 GovX Order Number  
OrderDate CHAR 20 GovX Order Date MMDDYYYY HH:MM
CustomerNumber CHAR 15 GovX Customer Number  
ShipmentMethod CHAR 15 Shipping Method Ground, 2-Day, USPS
TaxAmount NUMBER 21 Tax Amount for the Order, will be blank if GovX collects and remits taxes Decimal 2
Freight NUMBER 21 Shipping Charges, agreed upon average shipping cost Decimal 2
CustomerName CHAR 65 Customer Name  
ShipToName CHAR 65 Ship To Name  
ShipToAddress1 CHAR 65 Shipping to Address 1  
ShipToAddress2 CHAR 65 Shipping to Address 2  
ShipToContact CHAR 65 Shipping to Contact  
ShipToCity CHAR 35 Shipping to City  
ShipToState CHAR 10 Shipping to State  
ShipToZipCode CHAR 10 Shipping to Zip Code  
ShipToPhoneNumber CHAR 21 Shipping to Phone Number  
SubTotal NUMBER 21 Order Sub Total, (Cost of goods) Decimal 2
OrderTotalAmount NUMBER 21 Order Total Amount(Cost of goods+Taxes+freight) Decimal 2

 

Order Item Data Dictionary

There can be multiple ordered items for an order header. The following data dictionary represents a valid GovX Order Item.

Field Name Type Length Description Format/Value
OrderItemID NUMBER 21 GovX Order Item identifier  
OrderID CHAR 21 GovX Order Number  
ItemNumber CHAR 30 Manufacturer Material Number/UPC Code ALPHA NUMERIC
Quantity NUMBER 21 Item Quantity  
UnitPrice NUMBER 21 Item’s Unit Price (Cost of Goods) Decimal 2
ExtendedPrice NUMBER 21 Item’s Unit Price for all quantities Decimal 2
TaxAmount NUMBER 21 Tax Amount on line Item , will be blank if GovX collects and remits the Taxes Decimal 2
ItemDescription CHAR 100 The GovX Item Description

 

SignatureRequired BOOL 5 Indicates if signature is required on shipment delivery.

Boolean - true or false

 

GetOrders Sample Request

Input variables:

  • Username
  • Password
  • OrderStatus
    • New: will return all new orders
    • Open: will return all open orders which need a status update

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:govx="http://GovX.Service.Order3">

   <soapenv:Header/>

   <soapenv:Body>

     <govx:GetOrders>

         <govx:username>integrate@abc.com</govx:username>

         <govx:password>pass123</govx:password>        

         <govx:orderStatus>New</govx:orderStatus>

     </govx:GetOrders>

   </soapenv:Body>

</soapenv:Envelope> 

 

Sample Response

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">

   <s:Body>

     <GetOrdersResponse xmlns="http://GovX.Service.Order3">

         <GetOrdersResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

           <ErrorMessage i:nil="true"/>

           <Orders>

               <Order>

                 <OrderId>475938-ABC01</OrderId>

                 <OrderDate>2016-08-09T05:27:27.267</OrderDate>

                 <CustomerNumber>72063679</CustomerNumber>

                 <ShipmentMethod>GROUND</ShipmentMethod>

                 <TaxAmount>0</TaxAmount>

                 <Freight>0</Freight>

                 <CustomerName>KiQDwg nDiotyf</CustomerName>

                 <ShipToName>KiQDwg nDiotyf</ShipToName>

                 <ShipToAddress1>692 MvvQur CaeWS RIg</ShipToAddress1>

                 <ShipToAddress2 i:nil="true"/>

                 <ShipToContact i:nil="true"/>

                 <ShipToState>GA</ShipToState>

                 <ShipToCity>Kennesaw</ShipToCity>

                 <ShipToZipCode>30144</ShipToZipCode>

                 <ShipToPhoneNumber>888-888-8888</ShipToPhoneNumber>

                 <OrderSubTotal>62.00</OrderSubTotal>

                 <OrderTotalAmount>62.00</OrderTotalAmount>

                  <OrderItems>

                     <OrderItem>

                       <OrderItemId>736619</OrderItemId>

                       <OrderId>475938-ABC</OrderId>

                       <ItemNumber>672052158885</ItemNumber>

                       <Quantity>1</Quantity>

                       <UnitPrice>62.00</UnitPrice>

                       <ExtendedPrice>62.00</ExtendedPrice>

                       <TaxAmount>0.00</TaxAmount>

                       <ItemDescription>Dirk Polarized - Realtree - Happy Bronze Polarized</ItemDescription>

                       <GTIN/>

                      <SignatureRequired>true</SignatureRequired>

                     </OrderItem>

                     <OrderItem>

                       <OrderItemId>736618</OrderItemId>

                       <OrderId>475938-ABC01</OrderId>

                       <ItemNumber>073381038000</ItemNumber>

                       <Quantity>1</Quantity>

                       <UnitPrice>0.00</UnitPrice>

                       <ExtendedPrice>0.00</ExtendedPrice>

                       <TaxAmount>0.00</TaxAmount>

                       <ItemDescription>GovX Microfiber Bag</ItemDescription>

                       <GTIN/>

                     <SignatureRequired>false</SignatureRequired>

                     </OrderItem>

                 </OrderItems>

                 <VendorOrderNo i:nil="true"/>

               </Order>

          </GetOrdersResult>

     </GetOrdersResponse>

   </s:Body>

</s:Envelope> 

 

SetOrderResponse methods & data dictionary

SetOrderResponse Data Dictionary

Order loading log will be an acknowledgement for each and every transmitted Govx Order Request. The following data dictionary represents a valid Order Loading Log

Field Name Type Length Description Format/Value
OrderID CHAR 21 GovX Order Number  
LoadStatus CHAR 3 Loading status into Partner's System 000 – Successful
001 – Invalid Order Header format
002 – Invalid Order Item format
003 – Ship-to Address Error
004 – Material Error-Invalid items on the order
005 – Discontinued / Blocked items on the order
006 – Order already exists
999 - Others
VendorOrderNumber CHAR 21 Vendor Order number if the loading is successful  
Remarks CHAR 80 Remarks / Error Log from Vendor Order Creation Process  

 

SetOrderResponse Sample Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:govx="http://GovX.Service.Order3">

   <soapenv:Header/>

   <soapenv:Body>

     <govx:SetOrderResponse>

         <govx:orderSetResponseRequest>

           <govx:Username>integrate@vendor.com</govx:Username>

           <govx:Password>abc123</govx:Password>

           <govx:OrderId>12345</govx:OrderId>

           <govx:LoadStatus>000</govx:LoadStatus>

           <govx:VendorOrderNumber>525425</govx:VendorOrderNumber>

           <govx:Remarks>PO received</govx:Remarks>

           <govx:IsHashed>false</govx:IsHashed>           

         </govx:orderSetResponseRequest>

     </govx:SetOrderResponse>

   </soapenv:Body>

</soapenv:Envelope> 

 

SetOrderResponse Sample Response

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">

   <s:Body>

     <SetOrderResponseResponse xmlns="http://GovX.Service.Order3">

         <SetOrderResponseResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

           <ErrorMessage i:nil="true"/>

           <ResultStatus>Success</ResultStatus>

         </SetOrderResponseResult>

     </SetOrderResponseResponse>

   </s:Body>

</s:Envelope> 

 

SetOrderStatus method & data dictionary

SetOrderResponse Data Dictionary

SetOrderStatus updates should be posted to GovX on a predetermined frequency to update GovX’s Order management systems with the latest order statuses. The following data dictionary represents a valid SetOrderStatus method update.

Note: The ItemNumber is not required, but omitting the ItemNumber will update all items on the order for the partner with the same shipped date, status and tracking number. Omission of the ItemNumber is assumed the order has shipped complete and the requested quantities on the order will be used as the shipped quantities. If the ItemNumber is not supplied then the supplied quantity will be ignored.

Once the shipped status is replied on a message you will not be permitted to submit a status other than shipped again for the order.

Field Name Type Length Description Format/Value
OrderID CHAR 21 GovX Order Number  
VendorOrderNumber CHAR 21 Vendor Order number if the loading is successful  
Status CHAR 15 Current Status of the Order Shipped, Cancelled, Returned
ItemNumber CHAR 30 Material UPC code  
Quantitiy NUMBER 21 Order quantity  
ShipDate CHAR 20 Promised ship date / Date shipped, if already done. MMDDYYYY HH:MM
ShipMethod CHAR 10 Carrier SCAC Code UPS,USPS,FedEx and other Standard carrier Alpha Code
Freight NUMBER 21 Actual Freight Amount for shipping the OrderItem Decimal 2
TrackingNumber CHAR 30 Shipment Tracking number  
URL CHAR 256 Tracking no link  

 

SetOrderStatus Sample Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:govx="http://GovX.Service.Order3">

   <soapenv:Header/>

   <soapenv:Body>

     <govx:SetOrderStatus>

         <govx:orderSetStatusRequest>

           <govx:Username>integrate@vendor.com</govx:Username>

           <govx:Password>abc123</govx:Password>

           <govx:OrderId>525624-VEN01</govx:OrderId>

           <govx:VendorOrderNumber>12345</govx:VendorOrderNumber>

           <govx:Status>Shipped</govx:Status>

           <govx:ItemNumber>GVX001741</govx:ItemNumber>

           <govx:Quantity>1</govx:Quantity>

           <govx:ShipDate>2016-10-13T17:41:41.636</govx:ShipDate>

           <govx:ShipMethod>USPS</govx:ShipMethod>

           <govx:Freight>1</govx:Freight>

           <govx:TrackingNumber>9400110200830322034581</govx:TrackingNumber>

           <govx:IsHashed>false</govx:IsHashed>

         </govx:orderSetStatusRequest>

     </govx:SetOrderStatus>

   </soapenv:Body>

</soapenv:Envelope>  

 

SetOrderStatus Sample Response

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">

   <s:Body>

     <SetOrderStatusResponse xmlns="http://GovX.Service.Order3">

         <SetOrderStatusResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

           <ErrorMessage i:nil="true"/>

           <ResultStatus>Success</ResultStatus>

       </SetOrderStatusResult>

     </SetOrderStatusResponse>

   </s:Body>

</s:Envelope>

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.