Getting started using techSHIP API [Information]

When interacting with techSHIP via API (Blackbox) there are tools, documentation and good practices that will help you do it in the easiest way possible.

These are the elements detailed in this article:

• Swagger documentation to access API methods
• Receive API keys from Techdinamics
• Postman to test API calls
• Additional notes

NOTE: To run tests with your own portal and credentials, refer to the article  techSHIP API best practices [Information].

Follow the guide and bookmark the documentation as you find it convenient.

SWAGGER DOCUMENTATION

The Swagger documentation details the methods, parameters and values you need to interact with techSHIP. 

Access and bookmark the following link: https://api.techship.io/api/docs/ui/index

As you become familiar with the techSHIP API, you will have to consult it frequently.

The documentation is divided in the following sections:

• Auth: Details the Authentication methods

• Boxes: Details how to interact with Boxes objects

• Carriers: Details how to interact with Carriers objects

• Clients: Details how to interact with Clients' lists

• Countries: Details how to interact with Countries objects

• Manifests: Details how to get and validate manifest tracking numbers, as well to getting and finalizing manifests

• Shipments: Details how to create, print, update, delete, count, list, cartonize and update shipments

• Models: Details the available objects

For each method, you will find:

A) Method definition and description

B) Parameters mode

• Example value: Displays an example of how the parameters should be completed
• Model: Displays the object contents, parameters, data types, max/min length and values when applicable 

C) Details of the selected mode

D) Parameters details: Clarifies values and codes of a parameter whenever applicable

E) Try it out: Enables the quick test mode, opening the fields to be completed and an Execute button to execute the method test with the parameters you provided:

RECEIVE API KEYS FROM TECHDINAMICS

To be able to interact with the API, you will need your techSHIP Portal API Key and Password (Secret).

Each portal has its own key set, so for each portal, you will need a different set of keys.

Reach your Techdinamics POC(s) requesting the keys and detailing for which portal(s) you need them, and these will be sent to you via a secure link (1Password).

The API information (API Key and API Secret/Password) will be used in the next section in the contest of this article to test your connection.

POSTMAN TO TEST API CALLS

Once you have familiarized yourself with the API, the next step is to test it.

This section details how to use Postman to test a few interactions.

To do so, try the following as indicated:

• Create a shipment to receive the courier labels, shipment cost and tracking numbers
• Void and delete the test shipment

CREATE THE SHIPMENT AND RECEIVE DATA

Creating this basic JSON file will allow you to create shipments and receive back both the courier labels, shipment costs, and tracking numbers. 

1) Copy and import the code for Create Shipment from Swagger into a JSON’s Tool.

{
    "ClientCode": "ClientCode will be provided",
    "Routing": {
     "AccountCode": "STUD",
        "ServiceCode": "Standard"
    },
    "TransactionNumber": "2000015071",
    "CustomerOrder": "0300017131",
    "CustomerPO": "917891700",
    "CustomerNumber": "62902",
    "ShipToAddress": {
        "Name": "ASL Onboarding",
        "Address1": "1-16 Main Street",
        "City": "Mississauga",
        "StateProvince": "ON",
        "Postal": "L5M 1X3",
        "Country": "CA",
        "Phone": "18008009999"
    },
    "Packages": [
        {
            "Weight": "4.000 ",
            "Dimensions": {
                "PackagingWeight": 0,
                "Width": 4,
                "Height": 4,
                "Length": 4
            },
            "Items": [
                {
                    "SKU": "ABC",
                    "Description": "SD for Dummies 2",
                    "Quantity": "1.000"
                }
            ]
        },
        {
            "Weight": "4.000 ",
            "Dimensions": {
                "PackagingWeight": 0,
                "Width": 4,
                "Height": 4,
                "Length": 4
            },
            "Items": [
                {
                    "SKU": "ABC",
                    "Description": "SD for Dummies 2",
                    "Quantity": "1.000"
                }
            ]
        }
    ]
}

2) Create on the header section a Key named x-api-key with the provided information in the previous section

3) Create on the header section a Key named x-secret-key with the provided information in the previous section 

4) In Method POST use: https://{{url}}/api/v3/shipments/create?duplicateHandling=2

Example for TEST, where [your techSHIP portal] is your techSHIP portal name as provided by the Techdinamics Implementation team: 

https://[your techSHIP portal]/api/v3/shipments/create?duplicateHandling=2

If your techSHIP portal would be techshiptest.techship.ca, the URL would look like this:

https://techshiptest.techship.ca/api/v3/shipments/create?duplicateHandling=2

5) Execute the generated post file 

If the execution is successful, the response will be shown with main information and fields data for the new order created, as displayed below

VOID AND DELETE THE SHIPMENT

6) In Method POST of a separate JSON use: DELETE: https://{{url}}/api/v3/shipments/{{shipmentId}}

Example for TEST, where [your techSHIP portal] is your techSHIP portal name as provided by the Techdinamics Implementation team, and [your order reference] is the reference number you set at the time of creating the order: 

https://[your techSHIP portal]/api/v3/shipments/[your order reference]

If your techSHIP portal would be techshiptest.techship.ca and your shipment ID/reference is 53672288, the URL would look like this:

https://techshiptest.techship.ca/api/v3/shipments/53672288

7) Add API Key and Secret Key using information you already completed for the JSON file in steps 2 and 3

8) Press Send to execute

If the shipment was deleted successfully, you will get the following response:

ADDITIONAL NOTES

Take the following details into account:

• techSHIP Units of Measurement are:
  • In for Length, Width and Height
  • LB for Weight
• Ship To Addresses usage:
  • Provinces/State: The value must be sent using 2 letter abbreviations, for example Ontario should be "ON", Alberta "AB", etc.; Use this link as reference: Dictionary, Census of Population, 2021 - Table 1.8 Abbreviations and codes for provinces and territories, 2021 Census (statcan.gc.ca) for Canada and this other one for the US (USPS column) https://en.wikipedia.org/wiki/List_of_U.S._state_and_territory_abbreviations
    
  • Country: The value must be sent using 2 letter abbreviations, for example the United States should be "US", Mexico "MX", etc.; Use this link as reference: https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes as on the Alpha Code 2 column