Logistics API: Overview

            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.

            Updated: 13 Apr 2017 02:17 AM
            Helpful?  
            Help us to make this article better
            0 0