Techship API Requirements

NOTE:  In your system Orders may be replaced with Shipment.  

NOTE: This document was created for an organization that currently has or is interested to build its own API that could be consumed by techSHIP or organization that is interested in having techSHIP develop a connection to their database and will to create views or stored procedures.  If your interest is in developing an API to connect to techSHIP, and programmatically generate labels you should look at http://techshipapiv2.docs.apiary.io documentation.

techSHIP is a cloud-based application that is fully integrated with your WMS or ERP and provides a single user interface and a single API interface to simplify both use and integration.

A key requirement for techSHIP integration is real-time access to shipment data in the WMS system.  Allowing techSHIP to pull and process the order at user request.  techSHIP supports both API (REST or SOAP) as well as database connectivity.

Our development team will implement an API interface to consume your system's API or read/write to your database.

This document outlines the data elements that are required for our technical deal to develop such integration.

Orders Retrieval

The first API call required by techSHIP is a call to retrieve warehouse orders stored in the WMS system. techSHIP requires the ability to extract orders as a collection based on 

• Transaction Number
  This would be your WMS internally assigned a number to the warehouse order
• Customer Order Number
  Normally this would be your customer order number.  The warehouse orders ID that was provided by your customer
• Batch Number
  A batch number assigned by the WMS when processing a group of orders together.  This is a very common approach used for e-commerce order processing.
• Carton ID (optional)
  NOTE: This functionality only works with our techSHIP Desktop application.

During an API call, Techship will provide the type of reference is using to retrieve the information from the WMS system.

The message back should have the following structure.  If all the information cannot be returned in one call, multiple calls will be supported.

• Warehouse Order Collection
  Batch requests will require to return multiple orders.  This collection will contain all the orders or references to the orders.
  • Warehouse Order
    • Header Information
      • Client Number
      • Order Number (Mandatory, Unique)
      • Customer Order (Reference) number (Mandatory, Unique)
      • Customer PO (Optional, i.e. optional additional order number to display on labels and UI)
      • Order Date (Mandatory)
      • Ship-to Name (Mandatory)
      • Ship-to Address 1 (Mandatory)
      • Ship-to Address 2 (Optional)
      • Ship-to Address 3 (Optional)
      • City (Mandatory)
      • State/Province code (i.e. AB, SK, ON, etc.) (Mandatory)
      • Country code (i.e. CA, US, etc.) (Mandatory)
      • Postal code (Mandatory)
      • Ship-to Phone (Conditional, required for some carriers/services)
      • Ship-to Email (Optional)
      • Sequence Number (Optional).  Using in batches to print labels in a specific order.  Helps correlate labels with packing slips.
      • Carrier code (Optional)
      • Carrier service (Optional)
      • Carrier Billing Account (Optional)
      • Terms (Optional)
      • Signature Required (Boolean, Optional)
      • Adult Signature Required  (Boolean, Optional)
      • Collect On Delivery (Boolean, Optional)
      • COD Amount (Decimal, Conditional, required if COD=true)
      • COD Method (Optional)
      • Declared Value (Decimal, Optional)
      • Oversize (Boolean, Optional)
      • Unpackaged (Boolean, Optional)
      • Mailing Tube(Boolean, Optional)
      • Additional Parameters Collection (Optional) - used if customers request custom labels creation/printing, can be used for fields like DC number, Store Number, etc.
        • Code (Mandatory)
        • Value (Mandatory)
    • Package collection (Optional)
      When the order is packaged in the WMS prior to being passed to Techship this collection will contain information on the packages that were packaged their dimensions, weight, etc.  Normally each package will be updated by Techship with its own tracking number after the shipment is sent.
      • Package Information 
        • Package ID (Conditional, either Package ID or Package Sequence Number required)
        • Package Sequence Number (within Order, Conditional, either Package ID or Package Sequence Number required)
        • Package Weight (Mandatory)
        • Package Dimensions (H x L x W) (Optional)
        • Package UCC128 code (Optional, pass if generated on WMS side)
        • Package Type (Optional)
        • Additional Parameters Collection (Optional) - used if customers request custom labels creation/printing, can be used for additional SKU info, Color, Size, etc.
          • Code (Mandatory)
          • Value (Mandatory)
        • Item Collection (Optional)
          Item information is used when creating packing slips and international shipments
          • Item Information (Optional)
            • SKU (Mandatory)
            • Lot (Optional)
            • Description (Optional)
            • Quantity (Mandatory)
            • Serial Number (Optional)
            • HSS
            • Commercial Invoice Price (Mandatory for international)
            • Country of origin (Mandatory for international)

Order Update

Called by Techship when the customer finalizes order/batch in techSHIP to update tracking, freight charge, UCC, etc.

• Update Order Call (mandatory)
  • Order Number (Conditional, either Order Number or Customer Order required)
  • Customer Order(Conditional, either Order Number or Customer Order required)
  • Tracking Number (mandatory)
  • Carrier Code (Optional)
  • Carrier Service (Optional)
  • Carrier Billing Account (Optional)
  • Freight Charge (Optional)
  • Fuel Surcharge (Optional)
  • Close Order (Boolean, Optional - or additional service method to close order needs to be exposed)
  • Close/Confirmation Date (DateTime, Optional)
• Update Package Call (Optional) - this call and update order call can be combined in a single call if required
  • Package ID (Conditional, either Package ID or Package Sequence number with (Order Number or Customer Order) required to uniquely identify package)
  • Package Sequence Number (Conditional, see above)
  • Order Number (Conditional, see above)
  • Customer Order (Conditional, see above)
  • Tracking Number (Optional)
  • UCC128 Code (Optional, used for custom labels, returned if UCC128 generated on Techship side)

Database Connectivity

If you are interested in techSHIP connecting through your database, this section will help you with the connectivity requirements for this type of connection.

It is important to understand that techSHIP is a cloud-based application and as such it will reside outside your local network. There are two methods that exist to connect to your internal network in a secure way. Discuss with your IT team as to which method will better meet your internal requirements. 

Method 1: Open Port

This is the most common method.  Here your network team opens a port in your firewall and restricts access to this port to techSHIP API address.  We will provide the API addresses that need to be whitelisted. 

The firewall will then redirect traffic to the dabase server.  Access to the database server is further restricted by login credentials and limited permissions, usually limited to the views or store procedures required for this connection. 

The connection from techSHIP to the firewall is encrypted.

Method 1: VPN

In the case where the first method does not meet the IT requirements, techSHIP could support connectivity via a VPN.  This will need to be a firewall-to-firewall VPN connection.  The customer will bear all the additional costs of managing the VPN connection.