This article contains payloads, tips and details of the best practices when using the techSHIP API.

STRUCTURE

Each API call will have the following structure:

  • Headers = Security elements
  • Body = Order content (when applicable)
  • Query string = What the system should do with the order based on provided parameters

CREATING A SHIPMENT

In order to test the main operative functionalities of the API, you’ll need to have a shipment created.

You can use the following payload to create a shipment:


NOTE: Remember to use the header authentication keys as provided by Techdinamics' staff, and in the query string, the duplicateHandling parameter as 1 (which allows duplicates if not closed) to avoid duplicate issues, and the importOnly parameter as false (which will create and process the order). 
If you have issues using the duplicate control, you can change the TEST0001 reference value to another.
Feel free to change any other parameter in the query string if needed as described here: https://api.techship.io/api/docs/ui/index#/Shipments/CreateShipment

 

E.g., your query string would look like this with these parameters on, if your portal was test-api-us.techship.io:


https://test-api-us.techship.io/api/v3/shipments/create?duplicateHandling=1&errorLabelMode=&labelPreference=&isQuote=&importOnly=false&printerKey=


This order is a domestic order with a ship-from and ship-to Canadian address, containing 1 SKU, without accessorials. The weight is 4 lbs, and the packaging is a single 12x12x12 carton.


{
  "Packages": [
    {
      "Items": [
        {
          "SKU": "SKU001",
          "LotNumber": "1",
          "SerialNumber": "1",
          "Description": "Interesting Book",
          "Description2": "",
          "Description3": "",
          "Quantity": 1,
          "UnitPrice": 10,
          "UnitWeight": 1,
          "NetUnitWeight": 1,
          "ExpirationDate": "2023-11-28 14:37:00",
          "UOM": "",
          "Supplier": "",
          "CountryOfOrigin": "CA",
          "HarmonizedCode": "",
          "CustomFields": [
            {
              "Code": "",
              "Value": ""
            }
          ],
          "DangerousGoods": {
            "DangerousGoodsDhl": [
              {
                "ServiceType": "",
                "ContentId": "",
                "NetWeight": 0,
                "Uom": "",
                "SkipOnDeclaration": true,
                "LabelDesc": "",
                "UnCode": "",
                "CargoAircraftOnly": false,
                "ProperShippingName": "",
                "HazardClass": "",
                "PackingInstructions": "",
                "PackingGroup": "",
                "DeclarationQty": 0,
                "DeclarationUom": ""
              }
            ],
            "DangerousGoodsBasic": [
              {
                "LabelDesc": "",
                "UnCode": "",
                "CargoAircraftOnly": false,
                "ProperShippingName": "",
                "HazardClass": "",
                "PackingInstructions": "",
                "PackingGroup": "",
                "DeclarationQty": 0,
                "DeclarationUom": ""
              }
            ],
            "ContainerType": "",
            "RadioactiveContainerClass": "",
            "DangerousGoodsFedex": [
              {
                "IDNumber": "",
                "PackingGroup": "",
                "CargoAircraftOnly": false,
                "PackingInstructions": "",
                "ProperShippingName": "",
                "TechnicalName": "",
                "HazardClass": "",
                "Quantity": 0,
                "QuantityType": "",
                "Units": "",
                "Authorization": "",
                "LabelText": "",
                "ReportableQuantity": false,
                "SubsidiaryClasses": [
                  ""
                ],
                "LabelTextOptions": "",
                "CustomerSuppliedLabelText": ""
              }
            ]
          }
        }
      ],
      "Weight": 4,
      "WeightUOM": "",
      "Description": "",
      "MetroSCGCartonId": "",
      "Dimensions": {
        "PackagingWeight": 0,
        "Width": 12,
        "Height": 12,
        "Length": 12,
        "DimensionsUOM": ""
      },
      "BatteriesInfo": {
        "Batteries": false,
        "BatteryPackingType": "",
        "BatteryMaterialType": "",
        "BatteryRegulatorySubType": ""
      },
      "PackageDetails": {
        "SSCC": "",
        "CartonId": "",
        "CustomerSKU": "",
        "WarehouseSKU": ""
      },
      "PackageOptions": {
        "DeclaredValue": 0,
        "FreightClass": "",
        "DryIceWeight": 0
      },
      "SequenceNumber": 0,
      "CustomFields": [
        {
          "Code": "",
          "Value": ""
        }
      ],
      "UserDocuments": [
        {
          "Purpose": "",
          "Type": "",
          "Data": ""
        }
      ]
    }
  ],
  "TransactionNumber": "1",
  "ClientCode": "XYZ",
  "CarrierCode": "FedEx",
  "CustomerOrder": "TEST0001",
  "CustomerPO": "TEST0001",
  "CustomerNumber": "TEST0001",
  "BatchNumber": "TEST0001",
  "OrderImportSource": "API",
  "ManifestId": "",
  "PackageDescription": "Box",
  "Terms": "API",
  "Instruction": "HANDLE WITH CARE",
  "ShipFromAddress": {
    "Name": "John Customer",
    "Company": "Successful John",
    "Address1": "#15 AIRPORT ROAD",
    "Address2": "",
    "Address3": "",
    "City": "CHILLIWACK",
    "StateProvince": "BC",
    "Postal": "V2P1A4",
    "Country": "CA",
    "Phone": "123-456-7890",
    "Email": "successful.john@techship.com"
  },
  "LabelFromAddress": {
    "Name": "Techdinamics",
    "Company": "Techdinamics",
    "Address1": "41 PARR BLVD",
    "Address2": "",
    "Address3": "",
    "City": "BOLTON",
    "StateProvince": "ON",
    "Postal": "L7E4E3",
    "Country": "CA",
    "Phone": "555-123-4567",
    "Email": "mail@techship.com"
  },
  "ShipToAddress": {
    "IsResidential": true,
    "Name": "John Customer",
    "Company": "Successful John",
    "Address1": "#15 AIRPORT ROAD",
    "Address2": "",
    "Address3": "",
    "City": "CHILLIWACK",
    "StateProvince": "BC",
    "Postal": "V2P1A4",
    "Country": "CA",
    "Phone": "123-456-7890",
    "Email": "successful.john@techship.com"
  },
  "BillToAddress": {
    "Name": "",
    "Company": "",
    "Address1": "",
    "Address2": "",
    "Address3": "",
    "City": "",
    "StateProvince": "",
    "Postal": "",
    "Country": "",
    "Phone": "",
    "Email": ""
  },
  "ExporterAddress": {
    "Name": "",
    "Company": "",
    "Address1": "",
    "Address2": "",
    "Address3": "",
    "City": "",
    "StateProvince": "",
    "Postal": "",
    "Country": "",
    "Phone": "",
    "Email": ""
  },
  "ImporterAddress": {
    "Name": "",
    "Company": "",
    "Address1": "",
    "Address2": "",
    "Address3": "",
    "City": "",
    "StateProvince": "",
    "Postal": "",
    "Country": "",
    "Phone": "",
    "Email": ""
  },
  "Routing": {
    "AccountCode": "",
    "AccountId": 0,
    "ServiceCode": "Ground",
    "RateShoppingGroup": "",
    "RoutingGroup": "",
    "FreightPaymentTerms": "Prepaid",
    "ThirdPartyBillingAccount": "",
    "ThirdPartyBillingPostal": "",
    "ThirdPartyBillingCountryCode": "",
    "PickupDateTime": "2023-11-28 14:37:00",
    "InjectionDateTime": "2023-11-28 14:37:00",
    "DepartureDateTime": "2023-11-28 14:37:00",
    "DeliveryDateTime": "2023-11-28 14:37:00"
  },
  "Customs": {
    "TermsOfTrade": "",
    "PlaceOfIncoterm": "",
    "ItnNumber": "",
    "CommercialInvoiceDeclarationStatement": "",
    "CommercialInvoiceSpecialInstructions": "",
    "DutyBilling": {
      "DutyBillingAccount": "",
      "DutyBillingPostal": "",
      "DutyBillingCountryCode": "",
      "DutyPaymentTerms": ""
    },
    "SenderTax": {
      "VatNumber": "",
      "IossNumber": "",
      "EoriNumber": "",
      "PidNumber": ""
    },
    "SenderTaxInfo": {
      "VatNumber": "",
      "IossNumber": "",
      "EoriNumber": "",
      "PidNumber": ""
    },
    "ReceiverTaxInfo": {
      "VatNumber": "",
      "IossNumber": "",
      "EoriNumber": "",
      "PidNumber": ""
    },
    "ExporterTaxInfo": {
      "VatNumber": "",
      "IossNumber": "",
      "EoriNumber": "",
      "PidNumber": ""
    },
    "ImporterTaxInfo": {
      "VatNumber": "",
      "IossNumber": "",
      "EoriNumber": "",
      "PidNumber": ""
    }
  },
  "ShippingOptions": {
    "SignatureRequired": false,
    "SignatureAdult": false,
    "SignatureIndirect": false,
    "SaturdayPickup": false,
    "SaturdayDelivery": false,
    "ProofOfAge18": false,
    "ProofOfAge19": false,
    "HoldAtLocation": false,
    "AppointmentDelivery": false,
    "DryIce": false,
    "SpecialHandling": false,
    "PostOfficeId": "",
    "HoldForPickupIndicator": false,
    "DangerousGoods": false,
    "Explosive": false,
    "Alcohol": false,
    "IsNoRTS": false,
    "Perishable": false,
    "KeepFrozen": false,
    "TwoPersons": false,
    "ControlledSubstance": false,
    "DeliveryOptions": "",
    "OriginSignatureNotRequired": false,
    "LiftGateForPickUpIndicator": false,
    "LiftGateForDeliveryIndicator": false
  },
  "LTLOptions": {
    "FreightClass": "",
    "FreightNMFCClass": ""
  },
  "Insurance": {
    "DeclaredValue": 0,
    "DeclaredValueType": "",
    "DeclaredValueCurrencyCode": "",
    "Insurance": false
  },
  "DangerousGoodsHeader": {
    "RegulationSet": "",
    "EmergencyContact": "",
    "EmergencyPhone": "",
    "Signatory": {
      "ContactName": "",
      "Title": "",
      "Place": "",
      "Signature": "",
      "SignatureImageBase64": ""
    },
    "Offeror": "",
    "AdditionalHandling": "",
    "Accessibility": ""
  },
  "CustomFields": [
    {
      "Code": "",
      "Value": ""
    }
  ]
}

This payload might require you to change the following elements:

  • Routing section
    • Pickup, Injection, Departure and Delivery times, according to the current date of your test 
  • LTL Orders will require
    1. Freight Class
    2. FreightNMFC Class
  • Accessorials can be enabled with true where falses are set
  • International orders will require Duties and Customs information
  • Dangerous Goods orders require different fields depending on the carrier to be used    


Use the file as is, or modify it depending on the case you want to cover, and try making the API call.


NOTE: Keep the ManifestID value from the response at hand, you'll need it for later usage.


CHECK THE SHIPMENT

Once the shipment has been created and processed, you can verify its information.


You can use the List Shipments method:

https://api.techship.io/api/docs/ui/index#/Shipments/ListShipment


If you were to find the order you created earlier, you can use the query string this way, where you'll be looking for the Customer Order TEST0001.


https://test-api-us.techship.io/api/v3/shipments?startDate=&endDate=&dateType=&clientCode=&transactionNumber=&customerOrder=TEST0001&customerPO=&carrierCode=&pageIndex=&itemsPerPage=


You can use other parameters if you wish, but this is enough for you to familiarize yourself with the method and how query strings work.


MANIFEST THE SHIPMENT

Once the shipment has been created and processed, to close the shipping cycle, you need to manifest it. Manifesting implies confirming the shipment to the carrier, as well as closing and locking the orders in techSHIP so these are not modified after they are ready for shipping. 


You can use the Finalize Manifest method:

https://api.techship.io/api/docs/ui/index#/Manifests/FinalizeManifest


When an order gets processed, it's grouped under a Manifest ID. This field is used to identify to which Manifest group your orders belong to.


To manifest the order you created earlier, you can use the query string this way, where you'll substitute the manifestId parameter with the ManifestID value you obtained when you processed the order.


https://test-api-us.techship.io/api/v3/manifests/finalize/[manifestId - substitute with the ID obtained when processing]?parsNumber=&sync=


Check the response to verify the manifest was successful.



NOTE: Other orders could also be part of the manifest you close.