Ship API Request

This section covers the Request portion of the process, including the partner endpoint, the verification, and the shipment request.

Partner Endpoint

The Partner Endpoint must be exposed to the public and use SSL. Posts are sent via HTTP POST and contain a JSON body. The following are required for a partner endpoint:

Must be exposed to the public and use SSL
Must be able to receive a HTTP POST request with a JSON body
Shipping requests will be POSTed to the /shipment path on the endpoint
“content-type:” is always 'application/json'
“accept:” is always 'application/json'

Request verification

The signature of each request should be verified by the Partner as follows, using whichever libraries are appropriate for the platform they are on:

function verifySignature(nonce, apiKey) {
 const hmac = createHmac('sha256', apiKey)
 hmac.update(nonce) 
 return hmac.digest('base64') 
}
const nonce = req.headers['x-siteflow-nonce']
const [ partnerId, signature ] = req.headers['x-siteflow-signature'].split(':')
const verification = verifySignature(nonce, 'PARTNER_API_KEY')
if(verification !== signature) {
 return send(res, 401, { error: 'signature does not match' }) 
}

Value	Description
X-SITEFLOW-NONCE	A random token generated for each request
X-SITEFLOW-SIGNATURE	The partnerId and the request signature generated by Site Flow for this request, separated by a ':' character
PARTNER API KEY	A secure random key in hex format. Ideally, this should be 20 bytes or more. e.g. to generate a new key using node.js: crypto.randomBytes(20).toString("hex")
RETURN CODE (401 - SIGNATURE DOES NOT MATCH)	The response code for the request. In this example, the return code is 401, which indicates an error with the signatures. See the Status Codes topics for a description of other common status codes.

Shipping request payload

The body of the HTTP POST is a shipment request sent from Site Flow. The following is an example of a completed shipment request that can be used as a template:

{
"output": {
   "type": "printer",
   "deviceName": "zebra01",
   "format": "pdf",
   "orientation": "portrait",
   "dimensions": {
      "unit": "inch",
      "width": 4,
      "height": 6
      },
   "dpi": 203
   },
   "shipmentId": "5976029c770e36a13e25a85e",
   "timezone": "Europe/London",
   "dateFormat": "dd/MM/yyyy",
   "weightUnit": "g",
   "dimensionUnit": "mm",
   "currency": "GBP",
   "shipTo": {
      "name": "John Smith",
      "companyName": "HP GSB Solutions",
      "address1": "1 Primrose Street",
      "address2": "200 Commerce Street",
      "address3": "",
      "town": "London",
      "state": "",
      "postcode": "IG11 0HQ",
      "isoCountry": "GB",
      "phone": "0202223333",
      "email": "siteflow@hp.com "
      },
   "orderNumber": "20170721051327",
   "carrier": {},
   "return": {
      "name": "Jane Doe",
      "companyName": "HP GSB Solutions",
      "address1": "1 Primrose Street",
      "address2": "",
      "address3": "",
      "town": "London",
      "state": "",
      "postcode": "IG11 0HQ",
      "isoCountry": "GB",
      "phone": "0202223333",
      "email": "getintouch@hp.com"
      },
   "shipper": {
      "name": "Mr Smith",
      "address1": "1 Primrose Street",
      "town": "London",
      "postcode": "IG11 0HQ",
      "isoCountry": "GB",
      "phone": "0202223333",
      "email": "getintouch@hp.com"
      },
   "packages": [
      {
         "weight": 6,
         "totalWeight": 11,
         "height": 334,
         "width": 229,
         "depth": 1,
         "volume": 76486,
         "referenceNumber": "20170721051327-1-1",
         "value": 200,
         "items": [
            {
               "type": "production",
               "barcode": "B30000B96B",
               "sourceItemId": "20170721051327-1",
               "description": "Postcard",
               "value": 200,
               "count": 1
            }
         ]
      }
   ]
}

* Indicates the value is mandatory

Keys	Description
output	The label specs
Type	The type of output device
Device name	The name given to identify the device
Format	The file type of the output. The format can be pdf, png, or zpl.
Orientation	The relative position of the output. The orientation can be either portrait or landscape.
dimensions - the unit of measure for the dimensions of the label
Unit	The unit of measure for the following width and height measurements. The unit can be either mm or inch.
Width	The extent of the label from side to side
Height	The extent of the label from top to bottom
DPI	The number of dots per inch on the label
ShipmentID	The Site Flow shipment ID, which can be stored as a reference. This ID is unique for each shipment.
Timezone	The common standard time specified in the settings from Site Flow’s account details for PSP
Date format	The arrangement of the date
Weight unit	The unit of measure for the weight of the shipment. The unit can be either g or oz.
Dimension unit	The unit of measure for the dimensions of the shipment. The unit can be either mm or inch.
Currency	The system of money used in the order. Enter the standard abbreviation for the currency.
shipTo - the address of the recipient
Name*	The name associated with the recipient.
Company name	The title by which a formally organized or incorporated firm is known;
Address1*	The primary postal address information
Address2	The secondary postal address information
Address3	The tertiary postal address information
Town*	The town associated with the address
State	The state associated with the address, if included
Postcode*	The series of letters or digits or both included in a postal address, also known locally in various English-speaking countries throughout the world as a postcode, post code, PIN or ZIP Code.
ISOCountry*	The short alphabetic or numeric geographical codes developed to represent countries and dependent areas for use in data processing and communications
Phone	The phone number associated with the recipient.
Email	The email address associated with the recipient.
Ordernumber	The Customer Order Reference from Site Flow. This would normally be the order number submitted by the PSP’s brand. The same order number may be used for multiple shipments.
Carrier	This structure can contain integration fields per shipping method as defined by PSP if wanting to split services this way.
return - the return address specified by the brand on the order or the PSP address
Name*	The name associated with the recipient.
Company name	The title by which a formally organized or incorporated firm is known
Address1*	The primary postal address information
Address2	The secondary postal address information
Address3	The tertiary postal address information
Town*	The town associated with the address
State	The state associated with the address, if included
Postcode*	The series of letters or digits or both included in a postal address, also known locally in various English-speaking countries throughout the world as a postcode, post code, PIN or ZIP Code.
ISOcountry*	The short alphabetic or numeric geographical codes developed to represent countries and dependent areas for use in data processing and communications
Phone	The phone number associated with the recipient. The format should be only numbers "?" with no punctuation separating the numbers.
Email	The email address associated with the recipient.
shipper - the originating address
Name*	The name associated with the recipient.
Address1*	The primary postal address information
Town*	The town associated with the address
Postcode*	The series of letters or digits or both included in a postal address, also known locally in various English-speaking countries throughout the world as a postcode, post code, PIN or ZIP Code.
ISOcountry*	The short alphabetic or numeric geographical codes developed to represent countries and dependent areas for use in data processing and communications
Phone	The phone number associated with the recipient. The format should be only numbers "?" with no punctuation separating the numbers.
Email	The email address associated with the recipient.
PSP address	Where shipment is being dispatched from
packages - an array of packages on the shipment with the dimensions and weights in units specified above
weight	The packaging weight
totalweight	The packaging weight + the weight of the contents
height	Dimensions for the package
width	The measurement of the package from side to side
depth	The measurement of the package from top to bottom
volume	Total package volume
referencenumber	Each package has a unique reference so labels can be added to correct packages. This will be {{orderID}}-{{shipmentIndex}}-{{packageIndex}}.
value	The total value of all items in the package (the count multiplied by unit value).
type	Can be either production or stock. Production is used when the PSP manufactured the item. Stock is used for "ready to drop in the box" item, such as envelopes, vouchers, and flyers..
barcode	A set of alphanumeric characters used to identify a product
sourceitemid	The item ID given by the order submitter
description	The item/product description
count	The number of items of that type.