You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/Actions/GLS/configs.md
+15-10Lines changed: 15 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,9 +3,8 @@ title: Configuration
3
3
description: All configuration options for the GLS Action, including how to obtain credentials from the GLS Developer Portal.
4
4
---
5
5
6
-
# GLS Action Configuration
7
-
8
-
The GLS action requires a few credentials to authenticate with the GLS ShipIT API. These are set as **configuration values** in the Hercules admin panel (not as environment variables).
6
+
The GLS action requires a few credentials to authenticate with the GLS ShipIT API.
7
+
These are set as **configuration values** in the Hercules admin panel (not as environment variables).
9
8
10
9
---
11
10
@@ -20,15 +19,16 @@ The GLS action requires a few credentials to authenticate with the GLS ShipIT AP
20
19
|`auth_url`| string | No |`https://api.gls-group.net/oauth2/v2/token`| GLS OAuth2 token endpoint — must end in `/token`|
21
20
|`shipper`| GLS_SHIPPER | No | — | Default shipper address used when no shipper is provided in the shipment data |
22
21
23
-
> **`contact_id`:** This identifier is required for certain shipment operations (e.g. end-of-day reports and some services). It is issued by GLS support — contact them directly to request it.
22
+
> **`contact_id`:** This identifier is required for certain shipment operations (e.g. end-of-day reports and some services).
23
+
> It is issued by GLS support — contact them directly to request it.
24
24
25
25
---
26
26
27
27
## How to obtain your credentials
28
28
29
29
### Step 1 — Create a GLS Developer account
30
30
31
-
1. Go to [https://dev-portal.gls-group.net/get-started](https://dev-portal.gls-group.net/get-started)
31
+
1. Go to <https://dev-portal.gls-group.net/get-started>
32
32
2. Click **Sign In** and register a new account, or log in with an existing GLS account
33
33
3. Complete the registration and verify your email address
34
34
@@ -50,13 +50,15 @@ The GLS action requires a few credentials to authenticate with the GLS ShipIT AP
50
50
51
51
### Step 4 — Get your Contact ID (optional)
52
52
53
-
The `contact_id` is not available in the developer portal. You must contact **GLS support** directly and ask them to provide you with a Contact ID linked to your GLS contract.
53
+
The `contact_id` is not available in the developer portal.
54
+
You must contact **GLS support** directly and ask them to provide you with a Contact ID linked to your GLS contract.
54
55
55
56
---
56
57
57
58
## API endpoints
58
59
59
-
GLS provides different API endpoints depending on your region and environment. The defaults point to the global production API:
60
+
GLS provides different API endpoints depending on your region and environment.
61
+
The defaults point to the global production API:
60
62
61
63
| Setting | Default URL |
62
64
|---------|-------------|
@@ -71,7 +73,7 @@ If you are using a regional or sandbox endpoint, update these values accordingly
71
73
72
74
The GLS Action authenticates using **OAuth2 client credentials**:
73
75
74
-
```
76
+
```text
75
77
GLS Action
76
78
│
77
79
├── POST {auth_url}
@@ -85,13 +87,16 @@ GLS Action
85
87
Authorization: Bearer <access_token>
86
88
```
87
89
88
-
Tokens are **cached** and automatically refreshed 60 seconds before they expire. You do not need to manage token lifecycle manually.
90
+
Tokens are **cached** and automatically refreshed 60 seconds before they expire.
91
+
You do not need to manage token lifecycle manually.
89
92
90
93
---
91
94
92
95
## Default shipper
93
96
94
-
The optional `shipper` config allows you to set a **default sender address** that is applied to all shipments when no shipper is explicitly provided in the shipment data. This is useful when all your shipments originate from the same address.
97
+
The optional `shipper` config allows you to set a **default sender address** that is applied to all shipments when
98
+
no shipper is explicitly provided in the shipment data.
99
+
This is useful when all your shipments originate from the same address.
Copy file name to clipboardExpand all lines: docs/Actions/GLS/events.md
+7-4Lines changed: 7 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,16 +3,19 @@ title: Trigger
3
3
description: Events emitted by the GLS Action — what they are, how they trigger flows in Aquila, and what future events are planned.
4
4
---
5
5
6
-
# GLS Action Events
6
+
##GLS Action Events
7
7
8
-
In the Hercules platform, **events** are notifications emitted **by an action** that trigger flows in Aquila. They are the opposite of functions: instead of a flow calling the action, the action pushes data to Aquila, which starts any flows that are listening for that event type.
8
+
In the Hercules platform, **events** are notifications emitted **by an action** that trigger flows in Aquila.
9
+
They are the opposite of functions: instead of a flow calling the action, the action pushes data to Aquila, which starts
10
+
any flows that are listening for that event type.
9
11
10
12
---
11
13
12
14
## Current status
13
15
14
16
> **The GLS Action does not currently emit any events.**
15
17
>
16
-
> The GLS action presently only exposes **functions** (called by flows) and registers **data types** and **configuration**. Event support — where the action proactively notifies Aquila of changes — is **planned for a future release**.
18
+
> The GLS action presently only exposes **functions** (called by flows) and registers **data types** and **configuration**.
19
+
> Event support — where the action proactively notifies Aquila of changes — is **planned for a future release**.
Copy file name to clipboardExpand all lines: docs/Actions/GLS/overview.md
+14-12Lines changed: 14 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,9 +4,9 @@ description: Overview of the GLS ShipIT action — what it does, what you need t
4
4
icon: IconHome
5
5
---
6
6
7
-
# GLS Action
8
-
9
-
The **GLS Action** integrates the [GLS ShipIT API](https://dev-portal.gls-group.net/docs/shipit-farm/1/overview) as an action. It lets you create, validate, cancel, and manage GLS parcel shipments directly from your flows — no manual API calls required.
7
+
The **GLS Action** integrates the [GLS ShipIT API](https://dev-portal.gls-group.net/docs/shipit-farm/1/overview) as an action.
8
+
It lets you create, validate, cancel, and manage GLS parcel shipments directly from your
9
+
flows — no manual API calls required.
10
10
11
11
---
12
12
@@ -37,19 +37,20 @@ Before using the GLS Action you will need:
|`client_id`| Create an application at <https://dev-portal.gls-group.net> and find it under **My Apps**|
43
+
|`client_secret`| Found alongside the `client_id` in **My Apps** on the GLS developer portal |
44
+
|`contact_id`*(optional)*| Issued by GLS support — contact them directly to request it |
45
45
46
-
> **Note:** The `contact_id` is required for some shipment operations. If you are unsure whether you need it, contact GLS support.
46
+
> **Note:** The `contact_id` is required for some shipment operations.
47
+
> If you are unsure whether you need it, contact GLS support.
47
48
48
49
---
49
50
50
51
## Architecture overview
51
52
52
-
```
53
+
```text
53
54
Your Flow
54
55
│
55
56
▼
@@ -62,13 +63,14 @@ Your Flow
62
63
└── GLS ShipIT API (/shipit-farm/v1/backend/rs/...)
63
64
```
64
65
65
-
The action handles OAuth2 token management automatically, including caching and refresh before expiry. You only need to provide the `client_id` and `client_secret` in the action configuration.
66
+
The action handles OAuth2 token management automatically, including caching and refresh before expiry.
67
+
You only need to provide the `client_id` and `client_secret` in the action configuration.
Copy file name to clipboardExpand all lines: docs/Actions/GLS/quick-start.md
+6-6Lines changed: 6 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,15 +3,15 @@ title: Quick Start
3
3
description: Create your first GLS shipment in a few steps.
4
4
---
5
5
6
-
# Quick Start
7
-
8
-
This guide walks you through creating your first GLS shipment using the GLS Action. By the end, you will have a working flow that creates a parcel and retrieves a shipping label.
6
+
This guide walks you through creating your first GLS shipment using the GLS Action.
7
+
By the end, you will have a working flow that creates a parcel and retrieves a shipping label.
9
8
10
9
---
11
10
12
11
## Step 1: Install and configure the action
13
12
14
-
Follow the [Installation Guide](../../installation.md) to deploy the GLS Action, then set the following configuration values in your Hercules admin panel (or `.env` file):
13
+
Follow the [Installation Guide](../../installation.md) to deploy the GLS Action, then set the following configuration values in
Copy file name to clipboardExpand all lines: docs/Actions/GLS/troubleshooting.md
+39-59Lines changed: 39 additions & 59 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,23 +3,19 @@ title: Troubleshooting
3
3
description: Frequently asked questions, troubleshooting tips, and community resources for the GLS Action.
4
4
---
5
5
6
-
# Troubleshooting & Community Support
7
-
8
-
---
9
-
10
6
## FAQ
11
7
12
8
### General
13
9
14
-
**Q: What is the GLS Action?**
10
+
####What is the GLS Action?
15
11
16
-
A: The GLS Action is an integration for the Hercules automation platform that connects to the [GLS ShipIT API](https://api.gls-group.net). It lets you create and manage GLS shipments from within your flows without writing any API code.
12
+
The GLS Action is an integration for the Hercules automation platform that connects to the [GLS ShipIT API](https://api.gls-group.net).
13
+
It lets you create and manage GLS shipments from within your flows without writing any API code.
17
14
18
-
---
15
+
#### What GLS services does this action support?
19
16
20
-
**Q: What GLS services does this action support?**
17
+
The action supports all major GLS shipment types and services, including:
21
18
22
-
A: The action supports all major GLS shipment types and services, including:
23
19
- Standard parcel delivery
24
20
- Shop delivery and shop returns
25
21
- Exchange shipments
@@ -32,82 +28,71 @@ A: The action supports all major GLS shipment types and services, including:
32
28
33
29
See [Functions](functions.mdx) for the complete list.
34
30
35
-
---
36
-
37
-
**Q: Do I need a paid GLS account?**
38
-
39
-
A: Yes. You need a GLS business account and API access. Register on the [GLS Developer Portal](https://dev-portal.gls-group.net) and create an application to obtain `client_id` and `client_secret`.
40
-
41
-
---
42
-
43
-
**Q: What is the `contact_id` and do I need it?**
31
+
#### Do I need a paid GLS account?
44
32
45
-
A: The `contact_id` is a GLS-assigned identifier linked to your contract. It is required for some advanced operations (e.g. retrieving end-of-day reports with your account data). Contact GLS support to request it. It is **optional** for basic shipment creation.
33
+
Yes. You need a GLS business account and API access.
34
+
Register on the [GLS Developer Portal](https://dev-portal.gls-group.net) and create an application to obtain `client_id` and `client_secret`.
46
35
47
-
---
36
+
#### What is the `contact_id` and do I need it?
48
37
49
-
**Q: Can I test the action without a real GLS account?**
38
+
The `contact_id` is a GLS-assigned identifier linked to your contract.
39
+
It is required for some advanced operations (e.g. retrieving end-of-day reports with your account data).
40
+
Contact GLS support to request it. It is **optional** for basic shipment creation.
50
41
51
-
A: GLS provides sandbox/test environments for some regions. Check the [GLS Developer Portal](https://dev-portal.gls-group.net) for sandbox API endpoint URLs and test credentials. Update `ship_it_api_url` and `auth_url` in your configuration to point to the sandbox endpoints.
42
+
#### Can I test the action without a real GLS account?
52
43
53
-
---
44
+
GLS provides sandbox/test environments for some regions.
45
+
Check the [GLS Developer Portal](https://dev-portal.gls-group.net) for sandbox API endpoint URLs and test credentials.
46
+
Update `ship_it_api_url` and `auth_url` in your configuration to point to the sandbox endpoints.
54
47
55
48
### Installation & configuration
56
49
57
-
**Q: The action starts but immediately disconnects. What's wrong?**
50
+
#### The action starts but immediately disconnects. What's wrong?
51
+
52
+
Check the following:
58
53
59
-
A: Check the following:
60
54
1.`HERCULES_AUTH_TOKEN` — is it valid and not expired?
61
55
2.`HERCULES_AQUILA_URL` — is the Aquila server reachable from the Docker container?
62
56
3. Docker logs: `docker compose logs -f` — look for specific error messages
63
57
64
-
---
65
-
66
58
### Authentication & API errors
67
59
68
-
**Q: I get an `INVALID_PRODUCT` error when creating a Saturday delivery shipment.**
69
-
70
-
A: Saturday delivery (and next-working-day delivery) requires the shipment's `Product` to be set to `"EXPRESS"`. Change `Product: "PARCEL"` to `Product: "EXPRESS"` in your shipment data.
71
-
72
-
---
73
-
74
-
**Q: I get `ERROR_CREATING_GLS_SHIPMENT` — how do I find out what went wrong?**
60
+
#### I get an `INVALID_PRODUCT` error when creating a Saturday delivery shipment
75
61
76
-
A: Use `validateShipment` first to check your shipment data before creating it. The validation response includes specific `Issues` with `Rule` and `Location` fields pointing to the problematic field. See [Use Cases — Validate before creating](../GLS/use-cases.md#use-case-2-validate-before-creating).
62
+
Saturday delivery (and next-working-day delivery) requires the shipment's `Product` to be set to `"EXPRESS"`.
63
+
Change `Product: "PARCEL"` to `Product: "EXPRESS"` in your shipment data.
77
64
78
-
---
65
+
#### I get `ERROR_CREATING_GLS_SHIPMENT` — how do I find out what went wrong?
79
66
80
-
**Q: Can I cancel a shipment after it has been picked up by GLS?**
67
+
Use `validateShipment` first to check your shipment data before creating it.
68
+
The validation response includes specific `Issues` with `Rule` and `Location` fields pointing to the problematic field.
69
+
See [Use Cases — Validate before creating](../GLS/use-cases.md#use-case-2-validate-before-creating).
81
70
82
-
A: No. Once GLS has scanned the parcel at a depot or delivery vehicle, cancellation is no longer possible. The `cancelShipment` function will return `result: "SCANNED"` in that case.
83
-
84
-
---
71
+
#### Can I cancel a shipment after it has been picked up by GLS?
85
72
73
+
No. Once GLS has scanned the parcel at a depot or delivery vehicle, cancellation is no longer possible.
74
+
The `cancelShipment` function will return `result: "SCANNED"` in that case.
86
75
87
76
### Labels & printing
88
77
89
-
**Q: What label formats are supported?**
78
+
####What label formats are supported?
90
79
91
-
A: The action supports: `PDF`, `ZEBRA`, `INTERMEC`, `DATAMAX`, `TOSHIBA`, `PNG`. For reprint, additionally `PNG_200`.
80
+
The action supports: `PDF`, `ZEBRA`, `INTERMEC`, `DATAMAX`, `TOSHIBA`, `PNG`. For reprint, additionally `PNG_200`.
92
81
93
82
Choose the format that matches your label printer.
94
83
95
-
---
84
+
#### The label data returned is base64-encoded. How do I print it?
96
85
97
-
**Q: The label data returned is base64-encoded. How do I print it?**
86
+
Decode `CreatedShipment.PrintData[0].Data` from base64, then:
98
87
99
-
A: Decode `CreatedShipment.PrintData[0].Data` from base64, then:
100
88
-**PDF:** Save as a `.pdf` file and send to a PDF-capable printer
101
89
-**ZPL (ZEBRA):** Send the raw ZPL string directly to a Zebra label printer
102
90
-**PNG:** Save as a `.png` file and print as an image
103
91
104
-
---
105
-
106
-
**Q: Can I reprint a label after the parcel has been dispatched?**
92
+
#### Can I reprint a label after the parcel has been dispatched?
107
93
108
-
A: Yes, use the `reprintParcel` function with the `TrackID` and the original `CreationDate`. Note that available template sets for reprinting are limited to `NONE`, `ZPL_200`, and `ZPL_300`.
109
-
110
-
---
94
+
Yes, use the `reprintParcel` function with the `TrackID` and the original `CreationDate`.
95
+
Note that available template sets for reprinting are limited to `NONE`, `ZPL_200`, and `ZPL_300`.
111
96
112
97
## Common error codes
113
98
@@ -116,8 +101,6 @@ A: Yes, use the `reprintParcel` function with the `TrackID` and the original `Cr
116
101
|`ERROR_CREATING_GLS_SHIPMENT`| API returned an error during shipment creation or management | Check `validateShipment` output for details |
117
102
|`INVALID_PRODUCT`| Used `"PARCEL"` product with a service that requires `"EXPRESS"`| Set `Product: "EXPRESS"` in the shipment |
118
103
119
-
---
120
-
121
104
## Still stuck?
122
105
123
106
If you cannot resolve your issue with the FAQ above:
@@ -126,21 +109,18 @@ If you cannot resolve your issue with the FAQ above:
126
109
2.**Check the GLS API status:** Visit the [GLS Developer Portal](https://dev-portal.gls-group.net) for service announcements
127
110
3.**Open an issue** on GitHub (see below)
128
111
129
-
---
130
-
131
112
## GitHub
132
113
133
114
The source code for the GLS Action and all other Centaurus actions is available on GitHub:
0 commit comments