Distribution Center Transport SOAP Service for 3rd party fulfillment integration

Introduction

The purpose of this document is to introduce the web services that can be used to interface a 3rd party logistics company or internal fulfillment operation with UltraCart. Most fulfillment integrations rely upon UltraCart implementing the production of files and transmitting them to fulfillment companies in the format that they already support. With this method the fulfillment company can now write code in any programming language to communicate with UltraCart to retrieve orders, acknowledge receipt of the order and post back shipping information. This document is intended for software developers. It is not meant to either explain programming or the usage of web services for a specific language.

Configuration

The web service transport is like any other transport in the fact that it must be configured for a particular distribution center. This configuration is performed:

You must set the transport to “Web Service” and configure the three required options: key,  bidirectional, send credit card information.

API user?

You do not need to setup a API user to use this API. The required credentials are listed below:

Web Service Location

The WSDL (web service description language) file is located at the following URL:

https://secure.ultracart.com/axis/services/DctServiceV4?wsdl

Methods

Order getOrder(Credentials credentials, String orderId)

This method retrieves a single order using the known order ID.  This method is suitable for warehouse management system which may be scanning a pick list barcode of the order id.

Order[ ] getOrders(Credentials credentials)

This function obtains all the orders that have not been exported. This will include all orders that are new from the previous retrieval and acknowledgment. It is important that you make an acknowledge call for each order that you process after retrieving them.  

Order[ ] getOrdersForDateRange(Credentials credentials, dateTime from, dateTime to)

This function obtains all orders that are either in the shipping department or in the completed stage between the specified from and to times. This method can be used to historically fetch order information in case of a processing problem after an order has been acknowledged.  

Order[] getOrdersWithThumbnails(Credentials credentials, int thumbnailWidth, int thumbnailHeight)

This function obtains all the orders that have not been exported. This will include all orders that are new from the previous retrieval and acknowledgment. It is important that you make an acknowledge call for each order that you process after retrieving them. If there is a graphic available for the item then a thumbnail of width and height specified will be created. The URL for the thumbnail is returned on the Item object.

Order[] getOrdersForDateRangeWithCustomThumbnails(Credentials credentials, dateTime from, dateTime to, int thumbnailWidth, int thumbnailHeight)

This function obtains all orders that are either in the shipping department or in the completed stage between the specified from and to times. This method can be used to historically fetch order information in case of a processing problem after an order has been acknowledged. If there is a graphic available for the item then a thumbnail of width and height specified will be created. The URL for the thumbnail is returned on the Item object.

void acknowledge(Credentials credentials, String orderId)

This function acknowledges that the order has been downloaded and processed. This order will no longer appear in the next call to getOrders. If the interface is implemented in a unidirectional fashion then the order will also be marked as shipped within UltraCart. If the interface is bidirectional then the order will stay in the shipping department awaiting confirmation of shipment and tracking information.

String[] acknowledgeMultiple(Credentials credentials, String[] orderIds)

This function acknowledges that the orders have been downloaded and processed. These orders will no longer appear in the next call to getOrders. If the interface is implemented in a unidirectional fashion then the orders will also be marked as shipped within UltraCart. If the interface is bidirectional then the orders will stay in the shipping department awaiting confirmation of shipment and tracking information. Returns the order ids that were successfully acknowledged. If everything goes smoothly the same orderIds passed in will be returned.

void shipped(Credentials credentials, String orderId, String trackingNumber)

This function confirms that an order has been shipped and stores the tracking number on the order. This method must be used if the interface is bidirectional.

void shippedWithCost(Credentials credentials, String orderId, String trackingNumber, BigDecimal shippingCost)

This function confirms that an order has been shipped, stores the tracking number on the order and records the shipping cost. This method must be used if the interface is bidirectional.

void shippedWithMultipleTrackingNumbers(Credentials credentials, String orderId, String[] trackingNumbers)

This function confirms that an order has been shipped and stores multiple tracking numbers on the order.  This method or shipped must be used if the interface is bidirectional.  It is OK to call this method with a single tracking number in the array.

void shippedWithMultipleTrackingNumbersWithCost(Credentials credentials, String orderId, String[] trackingNumbers, BigDecimal shippingCost)

This function confirms that an order has been shipped, stores multiple tracking numbers on the order and records the shipping cost.  This method or shipped must be used if the interface is bidirectional.  It is OK to call this method with a single tracking number in the array.

boolean updateItemInventory(Credentials credentials, ItemInventory itemInventory)

This function updates the inventory for a single item.  The result indicates if the update was successful or not.  Please use the next method to update inventory in batches.

boolean[] updateItemInventories(Credentials credentials, ItemInventory[] itemInventories)

This function updates the inventory for a batch of items.  The result is an array of boolean values indicating if the update was successful

Objects

Credentials

Credentials to access the web service. All the fields for this object should be provided by the merchant after they configure the distribution center transport within UltraCart.

Order

Header level information about the order. This will contain payment information if the merchant has configured the distribution center web service transport to allow payment information to be sent.

Item

Item information

Option

Item option information.

ItemInventory

Inventory information associated with the item that can be updated.

Recommended API Workflow

Importing Orders from UltraCart into WMS

1. Call the getOrders method and fetch a batch (up to 500 will be returned)
2. Add the orders to your internal WMS system
3. Call the acknowledgeMultiple method with the orderIds from the batch retrieved in step 1.
4. If 500 orders were retrieved in step 1 then loop by performing steps 1-3 repeatedly until all orders have been imported.

Confirming Shipment from WMS to UltraCart (Bi-Directional Integrations)

1. After each order ships call the shipped method and provide the order ID and tracking information.

Abuse of API

Frequently Asked Questions

Sample Code

C#

First, create a Service Reference using the WSDL link above.   Name it DctServiceReference.

App.config

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
    <startup> 
        <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.5.2" />
    </startup>
    <system.serviceModel>
        <bindings>
            <basicHttpBinding>
                <binding name="DctServiceV4SoapBinding" />
            </basicHttpBinding>
        </bindings>
        <client>
            <endpoint address="http://secure.ultracart.com/axis/services/DctServiceV4"
                binding="basicHttpBinding" bindingConfiguration="DctServiceV4SoapBinding"
                contract="DctServiceReference.DctService" name="DctServiceV4" />
        </client>
    </system.serviceModel>
</configuration>

Program.cs

using System;
using UltraCartServices.DctServiceReference;

namespace UltraCartServices {
    public class Program {
        public static void Main(string[] args) {
            var client = new DctServiceClient();
            var credentials = new Credentials {
                merchantId = "DEMO",
                distributionCenterCode = "DFLT",
                key = "1234567890"
            };

            var start = DateTime.Now.AddDays(-720);
            var end = DateTime.Now.AddDays(+1);

            var orders = client.getOrdersForDateRange(credentials, start, end);
            Console.WriteLine($"{orders.Length} orders returned");

            orders = client.getOrders(credentials);
            Console.WriteLine($"{orders.Length} orders returned");

            Console.ReadKey();
        }
    }
}

Version History