XML Integration Instructions - XML API v2

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

 

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.

Email

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);
}

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk