Shipvine provides a simple, free, open, public API that allows software developers to write custom integration solutions. (Before you go down this road, though, we recommend checking to see if we've already built an integration for your platform!)

The API is "RESTful Web service," meaning that the only true requirement for an integrator is that his or her platform of choice needs an HTTP stack, such as the .NET Framework's HttpWebRequest class or the common libcurl library.

Understanding the REST Architecture

Like many Web services based on the Simple Object Access Protocol, or SOAP, the Shipvine Logistics API involves the exchange of XML documents over HTTP. Unlike many SOAP-based Web services, however, the Shipvine Logistics API treats the contents of the XML as the representation of the resource, or a specific entity in the Shipvine Logistics system. The intended action that should be performed against that resource is conveyed by the HTTP method, such as GET, POST, DELETE, or PUT, and the resource is identified by the URL of the HTTP request.

For example, in a SOAP+WSDL architecture, the Shipvine Logistics API for submitting a fulfillment request might have a method called SubmitFulfillmentRequest() that accepted an instance of a FulfillmentRequest object.

In the Shipvine Logistics API, however, a fulfillment request is submitted by POSTing a fulfillment request XML document via HTTP to https://api.warehousefs.com/public/v1/fulfillment-request-submissions. If successfully received, the Shipvine Logstics API will respond with an HTTP 200 OK response or some other appropriate HTTP status code if something went wrong.

The Shipvine Logistics API is stateless.

This architecture allows the Shipvine Logistics API to be accessible by a wide range of platforms and languages, particularly those that have poor tool support for SOAP and WSDL.

Sending Requests

All requests sent to the Shipvine Logistics API must be authenticated with an X-Api-Key header, relying on a secure transport connection to the protect the contents of the header. The API key can be obtained by contacting Shipvine Merchant Support.

The base address for all Shipvine Logistics API resources is https://api.warehousefs.com/public/v1/{resource-name}, where {resource-name} is substituted with the identifier for a particular resource or collection as defined in the reference documentation.

All requests must conform to the provided XML schema definition.

The following examples show a complete request and response from the Tracking resource.

Sample REST API Request

GET /public/v1/tracking/9101148008600996958525 HTTP/1.1
Host: api.warehousefs.com
Accept: */*
X-Api-Key: {048BC3C5-70CC-47C3-9CD2-71F228AC6EE4}

Sample REST API Response

HTTP/1.1 200 OK
Content-Length: 731
Content-Type: text/xml
Server: Microsoft-HTTPAPI/1.0
Date: Thu, 15 Oct 2009 19:39:09 GMT
Connection: close

<?xml version="1.0" encoding="utf-8"?>
<Tracking xmlns="urn:WarehouseFS-1.0">
	<Status>EnRoute</Status>
	<Waypoints>
		<Waypoint>
			<TransactedAtLocal>2009-10-15T07:00:00</TransactedAtLocal>
			<Location>ENGLEWOOD, CO 80110</Location>
			<Note>Arrival at Unit</Note>
		</Waypoint>
		<Waypoint>
			<TransactedAtLocal>2009-10-14T21:19:00</TransactedAtLocal>
			<Location>DENVER, CO 80217</Location>
			<Note>Processed through Sort Facility</Note>
		</Waypoint>
		<Waypoint>
			<TransactedAtLocal>2009-10-14T01:09:00</TransactedAtLocal>
			<Location>BOULDER, CO 80302</Location>
			<Note>Electronic Shipping Info Received</Note>
		</Waypoint>
	</Waypoints>
</Tracking>

Interpreting Responses

The Shipvine Logistics API only returns the HTTP 200 OK response when a successful operation occurred. The entity body of the response may or may not be empty depending on the operation and the resource that was accessed or modified.

If an error occurs, the Shipvine Logistics API will return an HTTP status code (for example, "HTTP 401 Unauthorized" or "HTTP 400 Bad Request"). The entity body of the response may or may not contain an <Errors> XML document that contains detailed, Shipvine Logistics-specific error messages and codes that describe the problem that occurred during the request.