Skip to content

troubleshooting.md

Latest commit

 

History

History
168 lines (109 loc) · 6.55 KB

troubleshooting.md

File metadata and controls

168 lines (109 loc) · 6.55 KB
title Troubleshooting
description Frequently asked questions, troubleshooting tips, and community resources for the GLS Action.

FAQ

General

What is the GLS Action?

The GLS Action is an integration for the Hercules automation platform that connects to the GLS ShipIT API. It lets you create and manage GLS shipments from within your flows without writing any API code.

What GLS services does this action support?

The action supports all major GLS shipment types and services, including:

  • Standard parcel delivery
  • Shop delivery and shop returns
  • Exchange shipments
  • Delivery at work
  • Deposit delivery
  • Identity-verified delivery (Ident / IdentPIN)
  • Flex delivery, signature, guaranteed 24h
  • Tyre service, addressee-only delivery
  • Saturday and next-working-day delivery (EXPRESS only)

See Functions for the complete list.

Do I need a paid GLS account?

Yes. You need a GLS business account and API access. Register on the GLS Developer Portal and create an application to obtain client_id and client_secret.

What is the contact_id and do I need it?

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.

Can I test the action without a real GLS account?

GLS provides sandbox/test environments for some regions. Check the GLS Developer Portal 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.

Installation & configuration

The action starts but immediately disconnects. What's wrong?

Check the following:

  1. HERCULES_AUTH_TOKEN — is it valid and not expired?
  2. HERCULES_AQUILA_URL — is the Aquila server reachable from the Docker container?
  3. Docker logs: docker compose logs -f — look for specific error messages

Authentication & API errors

I get an INVALID_PRODUCT error when creating a Saturday delivery shipment

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.

I get ERROR_CREATING_GLS_SHIPMENT — how do I find out what went wrong?

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.

Can I cancel a shipment after it has been picked up by GLS?

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.

Labels & printing

What label formats are supported?

The action supports: PDF, ZEBRA, INTERMEC, DATAMAX, TOSHIBA, PNG. For reprint, additionally PNG_200.

Choose the format that matches your label printer.

The label data returned is base64-encoded. How do I print it?

Decode CreatedShipment.PrintData[0].Data from base64, then:

  • PDF: Save as a .pdf file and send to a PDF-capable printer
  • ZPL (ZEBRA): Send the raw ZPL string directly to a Zebra label printer
  • PNG: Save as a .png file and print as an image

Can I reprint a label after the parcel has been dispatched?

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.

Common error codes

Error Code Cause Resolution
ERROR_CREATING_GLS_SHIPMENT API returned an error during shipment creation or management Check validateShipment output for details
INVALID_PRODUCT Used "PARCEL" product with a service that requires "EXPRESS" Set Product: "EXPRESS" in the shipment

Still stuck?

If you cannot resolve your issue with the FAQ above:

  1. Check the action logs: docker compose logs -f in the action directory
  2. Check the GLS API status: Visit the GLS Developer Portal for service announcements
  3. Open an issue on GitHub (see below)

GitHub

The source code for the GLS Action and all other Centaurus actions is available on GitHub:

🔗 https://github.com/code0-tech/centaurus

Use the GitHub repository to:

Contributing

Contributions to Centaurus are welcome! Here is how to get started:

1. Fork and clone

git clone https://github.com/<your-username>/centaurus.git
cd centaurus
npm install

2. Create a new action (optional)

Use the scaffolding script to create a new action:

npm run create-action -- my-new-action

This creates a new directory at actions/my-new-action/ with the standard structure.

3. Make your changes

  • Follow the existing code style (TypeScript, Zod for validation, Hercules SDK patterns)
  • Add tests for your changes in src/index.test.ts
  • Run the test suite: npm run test
  • Run the linter: npm run lint

4. Submit a pull request

Open a pull request against the main branch of code0-tech/centaurus. Include:

  • A clear description of what you changed and why
  • Test results showing your changes pass

Development commands

Command Description
npm run build Build all actions
npm run test Run the test suite
npm run test:watch Run tests in watch mode
npm run lint Run ESLint
npm run create-action -- <name> Scaffold a new action