The XML API allows you to interact with your Fulfillment Control Panel account from outside applications, shopping carts, and custom scripts.
Functions allow for submitting orders, requesting available inventory levels, checking for returns, and requesting order status and tracking numbers.
This document describes the available integration points and provides instructions for interacting the with API.
Data Requirements
The API expects to receive an HTTP POST request with Content-Type header set to “text/xml”. The raw post data should be the XML message. The API will respond with XML data containing a success or failure status and other details.
API Credentials
You will need your Merchant Id, Merchant Name, and Merchant Token which can be found within your Fulfillment Control Panel account by choosing My Settings from the Client Info menu.
Submitting Orders
Recommendations
Due to some limitations on how we parse the incoming orders, it is recommended that you only submit a single order per request:
Our parser will die at the first order that includes an error.
No orders are accepted if any errors are generated.
Only errors from the first rejected order are included in any XML responses.
Request URL
https://fcp.efulfillmentservice.com/xml/orders/
Request XML Sample
Response XML Samples
Success Response
Failure Response
If you would like to place a "hold" on submitted orders, or shipping options, the following example may be of use to you.
XML Request Element Details
|
Element |
Required |
Description |
|
OrderSubmitRequest |
Yes |
This element contains your API credentials and a list of orders to be submitted. |
|
Version |
Yes |
This element indicates the XML data version.
To submit a test order for validation purposes use: <Version>TEST</Version>. |
|
MerchantId |
Yes |
The unique ID number for your Fulfillment Control Panel account. |
|
MerchantName |
Yes |
The name of your account in our system. |
|
MerchantToken |
Yes |
Security token to protect against unauthorized orders. |
|
OrderList |
Yes |
Contains all Order elements to be submitted. |
|
Order |
Yes |
This element contains all the detail elements for each order. |
|
OrderNumber |
Yes |
Your identifying reference number for the order. The API will not accept duplicate values. |
|
ReferenceNumber |
No |
Secondary reference number such as a purchase order. |
|
ShippingMethod |
Yes |
EFS internal code for the requested shipping service. See Appendix A for a list of codes. |
|
Comments |
No |
Comments are printed on the packing slip included inside each shipment. |
|
ShippingAddress |
Yes |
This element contains all the detail elements for the destination address.
Has the same child elements as BillingAddress. |
|
BillingAddress |
No |
This element contains all the detail elements for the billing address.
Billing address is strictly used for reference.
Has the same child elements as ShippingAddress. |
|
FirstName |
Yes |
Customer first name. |
|
LastName |
Yes |
Customer last name. |
|
Company |
No |
Customer company name. |
|
Address1 |
Yes |
First address line. |
|
Address2 |
No |
Second address line. |
|
City |
Yes |
Customer city. |
|
State |
Yes |
Customer state or province. |
|
PostalCode |
Yes |
Customer postal code (where applicable). |
|
Country |
Yes |
Customer country code. Should match ISO 3166-1-alpha-2 codes found here: http://www.iso.org/iso/country_names_and_code_elements |
|
Phone |
No |
Customer phone number. |
|
|
No |
Customer email. |
|
ItemList |
Yes |
Contains all Item elements to be included with the order. |
|
Item |
Yes |
Contains the item detail elements for each item. |
|
Sku |
Yes |
Product SKU. Must exactly match product SKUs on record in the Fulfillment Control Panel. |
|
Quantity |
Yes |
Quantity to ship. |
Requesting Inventory Information
For inventory there are two types of requests having different XML structures and URLs.
Type 1 - Specific SKU(s)
Request URL
https://fcp.efulfillmentservice.com/xml/inventory/
Request Format
Response Format
This is the expected success response:
Type 2 - Complete List of Skus
Request URL
https://fcp.efulfillmentservice.com/xml/inventory/list/
Request Format
Response Format
This is the expected success response:
Requesting Order Status
Request Url
https://fcp.efulfillmentservice.com/xml/orders/status/
Request Format
Response Format
Response Element Details
|
Element |
Description |
|
OrderStatusResponse |
This element contains the Status, Description, and OrderList elements. |
|
Status |
Possible values include Success or Error. |
|
Description |
This element will contain details about an Error response. |
|
OrderList |
Contains all Order elements for requested OrderNumber. |
|
Order |
Contains the details of each requested OrderNumber. |
|
OrderNumber |
The customer identifier for each order from the original request. |
|
OrderReference |
Secondary reference number such as a purchase order. |
|
OrderConfirmation |
The EFS identifier for the order. |
|
OrderStatus |
The current status of the order. Possible values include Completed, Cancelled, Pending, Processing, Backorder, N/A. |
|
ShippingMethod |
This element contains the details regarding a requested shipping code and actual shipping method. |
|
Requested |
The requested shipping code for the order. |
|
Actual |
The actual shipping code used for the order. |
Requesting Returns Information Beta
This is a new feature with limited outside testing. For returns there are two types of requests having different XML structures and URLs. Response will be the same for both types.
Type 1 - Specific Order(s)
Request URL
https://fcp.efulfillmentservice.com/xml/orders/returns/
Request Format
Type 2 - List of Returns for a Date Range
Request URL
https://fcp.efulfillmentservice.com/xml/orders/returns/list/
Request Format
Note: Date range cannot exceed 31 days. Date format must be YYYY-MM-DD.
Response Format Example
Expected success response format:
For each Item the Good element denotes undamaged product returned to available inventory. The Hurt element represents damaged or unusable product.
Shipping Method Codes
Detailed information regarding rates and transit times for our domestic services can be found here.
Script Samples
PHP - Post Orders, Parse Response
The following code sample outlines the process to submit an order and parse the response data.
<?php
// Define Request URL
$requestUrl = "https://fcp.efulfillmentservice.com/xml/orders/" ;
// Define XML Request Data
$requestXml =<<<XML
<?xml version="1.0" encoding="utf-8"?>
<OrderSubmitRequest>
<Version>0.6</Version>
<MerchantId>7816</MerchantId>
<MerchantName>TestCo</MerchantName>
<MerchantToken>9491514bf3qwdqwxefe3af2b58b99</MerchantToken>
<OrderList>
<Order>
<OrderNumber>2013-09-17_004</OrderNumber>
<ReferenceNumber/>
<ShippingMethod>GROUND</ShippingMethod>
<Comments/>
<ShippingAddress>
<FirstName>Bertrand</FirstName>
<LastName>Humbletrack</LastName>
<Company/>
<Address1>805 Ayer Drive</Address1>
<Address2/>
<City>Detroit</City>
<State>MI</State>
<PostalCode>55092</PostalCode>
<Country>US</Country>
<Phone>3125551212</Phone>
<Email/>
</ShippingAddress>
<BillingAddress/>
<ItemList>
<Item>
<Sku>123a</Sku>
<Quantity>1</Quantity>
</Item>
</ItemList>
</Order>
</OrderList>
</OrderSubmitRequest>
XML;
// Define Content-Type Header
$headers[] = "Content-Type: text/xml" ;
// CURL Settings for the Request
$ch = curl_init() ;
curl_setopt($ch,CURLOPT_URL,$requestUrl) ;
curl_setopt($ch,CURLOPT_RETURNTRANSFER,1) ;
curl_setopt($ch,CURLOPT_HEADER,0) ;
curl_setopt($ch,CURLOPT_HTTPHEADER,$headers) ;
curl_setopt($ch,CURLOPT_POST,1);
curl_setopt($ch,CURLOPT_TIMEOUT,30) ;
curl_setopt($ch,CURLOPT_FRESH_CONNECT, 1);
curl_setopt($ch,CURLOPT_POSTFIELDS,$requestXml);
curl_setopt($ch,CURLOPT_SSL_VERIFYPEER, 0);
$return = curl_exec($ch) ;
// Optional Debug Info
//print_r(curl_getinfo($ch));
//echo "<br><br>cURL error number:" .curl_errno($ch);
//echo "<br><br>cURL error:" . curl_error($ch);
//echo "<br><br>";
curl_close($ch) ;
try
{
$response = new SimpleXMLElement($return);
if($response->Status == 'Success')
{
//Order was placed successfully
echo <<<HTML
<h1>Success!</h1>
<p>
<strong>EFS Confirmation #:</strong> {$response->OrderList->Order->OrderId}<br>
<strong>Status:</strong> {$response->OrderList->Order->OrderStatus}
</p>
HTML;
} else {
//Order failed
echo <<<HTML
<h1>Failure!</h1>
<p>
<strong>Description:</strong> {$response->Description}<br>
<strong>Error:</strong> {$response->Details->Error}<br>
<strong>Order:</strong> {$response->Details->Order}<br>
<strong>Value:</strong> {$response->Details->Value}<br>
<strong>Description:</strong> {$response->Details->Description}
</p>
HTML;
}
} catch (Exception $e) {
// Possible problem with XML response data
print_r($e);
}
0 Comments