Create a Shipping Label
GIGALOGISTICS is a REST API that allows you to manage almost every facet possible for shipping. This tutorial will show you how to create a label.
Before you begin:
- You'll need a pair of
AK/SK
which will work for this tutorial. - You'll need a tool to make an API call, like curl or Postman.
Creating a shipping label requires the following steps:
- Prepare Your Request
- Send the Request
- Download the Label
In the example below, you'll request a label using the GLS account that's included with your GIGALOGISTICS account. The general steps are the same. regardless of which carrier you use.
Step 1: Prepare Your Request
API Endpoint
To create a label, you'll need to send an HTTP POST request to https://apis.gigacloudlogistics.com/cloud-ship-service/v1/shipment. From now on we'll refer to this as the /cloud-ship-service/v1/shipment API endpoint to keep things short.
Headers
There are two HTTP headers that you need to set in your request:
HTTP Header | Desription |
---|---|
Content-Type | The Content-Type header specifies the media type of your API request. GIGALOGISTICS requires all requests to be in JSON format,so this header should always be set to application/json |
Authorization | Use your AK/SK to obtain authorization token for the request,refer to API Authorization documentation. |
transactionId | A unique identifier to your transaction.This element is also returned in the reply and helps you match the request to the reply. |
Note:
transactionId
is restricted from repeating for 24 hours.
Request Body
The body of your HTTP request is where you'll specify all the information about the shipping label that you want to create,such as the "from" and "to" addresses, the package weight and dimensions, etc.
For this tutorial, we'll create a label with the following criteria:
Field | Value |
---|---|
Shipper | Carlo plus Große Ulrichstraße 17 Halle,Saxony-Anhalt 66816,DE |
Recipient | Peter Friesenweg 33 Leverkusen, Saxony-Anhalt 94072,DE |
Item Weight | 15 KG |
Item Dimension | 12 x 24 x 6 IN |
As we mentioned above, GIGALOGISTICS requires all requests to be in JSON format. Here's what our label request body will look like. Notice that it contains all of the information listed above:
{
"carrierId": "GCL-*********",
"serviceType": "GLS_STANDARD",
"shipper": {
"address": {
"countryCode": "DE",
"stateOrProvinceCode": "Saxony-Anhalt",
"city": "Halle",
"zipCode": "66816",
"streetLine1": "Große Ulrichstraße 17"
},
"contact": {
"personName": "Carlo plus"
}
},
"recipient": {
"address": {
"zipCode": "94072",
"streetLine1": "Friesenweg 33",
"city": "Leverkusen",
"stateOrProvinceCode": "Saxony-Anhalt",
"countryCode": "DE"
},
"contact": {
"personName": "Peter"
}
},
"itemLines": [
{
"itemTransactionId": "ITEM91f55857-fe8e-4308-bf16-be5d6a9d4e43",
"itemCode": "this is itemCode",
"weight": {
"units": "KG",
"value": 15
},
"dimensions": {
"units": "IN",
"length": 12,
"width": 24,
"height": 6
}
}
]
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
Step 2: Sending the Request
Now we'll take everything we talked about in Step 1 and put it all together using curl. Notice the example below uses everything we talked about in Step 1:
- Makes a POST call to
https://apis.gigacloudlogistics.com/cloud-ship-service/v1/shipment
- Sets the content type header to
application/json
- Sets
Authorization
header to the access token - Sets
transactionId
header to a unique identifier
Paste the following curl example into your Terminal :
curl -iX POST https://apis.gigacloudlogistics.com/cloud-ship-service/v1/shipment \
-H 'Content-Type: application/json' \
-H 'Authorization: __YOUR_ACCESS_TOKEN__' \
-H 'transactionId: __UUID__' \
-d '{
"carrierId": "GCL-*********",
"serviceType": "GLS_STANDARD",
"shipper": {
"address": {
"countryCode": "DE",
"stateOrProvinceCode": "Saxony-Anhalt",
"city": "Halle",
"zipCode": "66816",
"streetLine1": "Große Ulrichstraße 17"
},
"contact": {
"personName": "Carlo plus"
}
},
"recipient": {
"address": {
"zipCode": "94072",
"streetLine1": "Friesenweg 33",
"city": "Leverkusen",
"stateOrProvinceCode": "Saxony-Anhalt",
"countryCode": "DE"
},
"contact": {
"personName": "Peter"
}
},
"itemLines": [
{
"itemTransactionId": "ITEM91f55857-fe8e-4308-bf16-be5d6a9d4e43",
"itemCode": "this is itemCode",
"weight": {
"units": "KG",
"value": 15
},
"dimensions": {
"units": "IN",
"length": 12,
"width": 24,
"height": 6
}
}
]
}'
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
If your request was successful, you'll receive an HTTP 200 response that looks similar to this:
{
"success": true,
"data": {
"transactionId": "transactionId",
"carrierId": "GCL-*********",
"carrierCode": "GLS",
"serviceType": "GLS_STANDARD",
"paymentOption": {
"paymentType": null,
"paymentTerms": null,
"payor": null
},
"signatureOption": {
"signatureOptionType": null
},
"labelSpecification": {
"imageType": null,
"labelStockType": null
},
"taxIndentifiers": null,
"transactionShipments": [
{
"itemTransactionId": "ITEM91f55857-fe8e-4308-bf16-be5d6a9d4e43",
"gigaTrackingNumber": "GCL1933469400013",
"trackingNumber": "251946492667",
"masterTrackingNumber": null,
"declaredInfo": null,
"specialService": null,
"customerReference": null,
"packageDocuments": [
{
"fileBase64": null,
"imageType": "pdf",
"fileUrl": "https://oss.com/temp/GLS/20221216/7240686711761-251946492667.pdf",
"contentType": "LABEL"
}
]
}
]
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
Notice that this response includes the following:
- TransactionId
- ItemTransactionId
- PackageDocuments
Step 3: Download the Label
At the end of Step 2, you received an HTTP response that included the label details. The label is returned as a URL or base64. You can paste the fileUrl
into your browser to download the label, or get the label file by parsing the fileBase64
.
{"packageDocuments": [
{
"fileBase64": null,
"imageType": "pdf",
"fileUrl": "https://oss.com/temp/GLS/20221216/7240686711761-25194992667.pdf",
"contentType": "LABEL"
}
]}
2
3
4
5
6
7
8
Advanced Options
Review the options below for ways to improve your label flow.
Add Message to the Labels
Show your customers an additional level of care and detail by adding a personal or customized message. Custom Label Messages article.