Getting started using techSHIP API [Information]

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

These are the sections detailed in this article:

• How to get the required API credentials to be able to use the API.
  
• How to use Swagger documentation to learn and test the available API methods.
• How to use Postman for testing the API calls
• Additional notes

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

HOW TO GET THE REQUIRED API CREDENTIALS

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).

HOW TO USE SWAGGER DOCUMENTATION

You can review the Swagger documentation at https://api.techship.io/api/docs/ui/index.

NOTE: We suggest you bookmark this link for frequent consultation.

techSHIP's API methods are categorized in Swagger as follows:

• 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.

• Metadata: Details how to retrieve carrier metadata.

• MiddleMile: Details how to set container for shipment by tracking number.

• Shipments: Details how to interact with shipment objects.

You can refer to How to Use Swagger Documentation [Information] to learn more about using Swagger for reference and testing Techdinamics' APIs.

HOW TO USE POSTMAN FOR TESTING

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