GLS Netherlands API

A simple .NET SDK for the GLS Netherlands webservice.

Features

• Validate login and resolve the customer number
• Create and confirm shipping labels
• Look up GLS ParcelShops / ParcelLockers
• Test and production endpoints out of the box
• Typed exceptions for 401 Unauthorized and 429 Too Many Requests

Requirements

• .NET 10
• A GLS Netherlands API account (username + password). Request one via the GLS API portal.

Installation

dotnet add package GlsNetherlandsApi

Or via the NuGet package manager: https://www.nuget.org/packages/GlsNetherlandsApi

Quick start

using GlsNetherlands;
using GlsNetherlands.Models;
using GlsNetherlands.Models.Requests;

// Pass test: true to hit the GLS test environment
var api = new GlsNetherlandsApi("username", "password", test: true);

// LabelService requires the customer number; resolve it once and cache it on the instance
await api.ReloadCustomerNoAsync();

var request = new CreateLabelRequest
{
    Shiptype = ShipType.P,
    LabelType = LabelResultType.Pdf,
    ReturnRoutingData = true,
    TrackingLinkType = TrackingLinkType.Shipment,
    Addresses = new DeliveryAddresses
    {
        DeliveryAddress = new DeliveryAddress
        {
            Name1 = "Jan de Tester",
            Street = "Pieterpad",
            HouseNo = "1",
            ZipCode = "6932NC",
            City = "Arnhem",
            CountryCode = "NL",
            AddresseeType = AddresseeType.Private
        }
    },
    Units = [new Unit { UnitId = "1234566789" }]
};

var result = await api.LabelService.CreateLabelAsync(request);
Console.WriteLine(result.ShipmentTrackingLink);

Services

Service	Method	Purpose
api.LoginService	ValidateLoginAsync	Validate credentials and list customers
api.LabelService	CreateLabelAsync	Create a shipping label
api.LabelService	ConfirmLabelAsync	Confirm previously generated labels
api.ParcelShopService	GetListAsync	Fetch nearby ParcelShops / ParcelLockers

api.LabelService throws CustomerNumberUnknownException until CustomerNo is set — either assign it manually or call await api.ReloadCustomerNoAsync().

Error handling

Non-success responses are translated to exceptions:

• UnauthorizedException — HTTP 401
• TooManyRequestsException — HTTP 429~~~~
• NotFoundException — empty / unparseable response body
• HttpRequestException — any other non-2xx status

The parsed error payload from the API is also exposed on each service via LastErrors (and LastRequestStatus for the HTTP status code).

Examples

The GlsNetherlands.Example console project contains runnable samples for every service call. Set your credentials at the top of Program.cs and run:

dotnet run --project GlsNetherlands/GlsNetherlands.Example

Building from source

cd GlsNetherlands
dotnet build GlsNetherlands.sln
dotnet test GlsNetherlands.Tests/GlsNetherlands.Tests.csproj

Contributing

Issues and pull requests are welcome on GitHub. See AGENTS.md for architecture notes and project conventions.

License

MIT © Jordi Jolink