EXLABEL 3.0 WEB SERVICE

Requirements:

To be able to use this service, the following points are required.

HTTP Package Management:

HTTP client flows must comply with the following standards. Any client flow that doesn’t comply with these standards will be automatically rejected.

HTTP Protocol:
  • HTTP Version: HTTP messages must include the protocol version in the request or status line (e.g., 'HTTP/1.1').
  • HTTP/1.0: If using HTTP version 1.0, only use Content-Length to specify the message body size.
  • HTTP/1.1 and later versions: Prefer Transfer-Encoding: chunked for more efficient data transmissions but ensure that Content-Length is not present simultaneously.
Content-Length:
  • Definition: The Content-Length header indicates the size of the message body in bytes.
  • Usage:
    • Mandatory for response messages containing a body, unless Transfer-Encoding is used with the value chunked.
    • Must not be used if Transfer-Encoding: chunked is present.
  • Accuracy:
    • Clients must ensure that the size specified in Content-Length matches the size of the received message body.
Transfer-Encoding:
  • Definition: The Transfer-Encoding header specifies the encoding(s) used to transfer the message body. Each encoding is applied sequentially, in order, to decode the message body.
  • Values and Usage:
    • chunked: Allows for the transfer of data in variable-sized segments, which is useful when the total length of the message body is not known beforehand.
    • If Transfer-Encoding: chunked is used, the Content-Length header must be omitted.
    • The value chunked must be the last encoding if multiple encodings are used.

For more details, refer to sections 3.3, 3.3.1, 3.3.2, and 3.3.3 of the RFC 7230 standard:

https://datatracker.ietf.org/doc/html/rfc7230

SLA, Limits & Performance:

SLA:
  • Target Availability: 99.16% monthly
  • TDI Monitoring: GET /GetSystemStatus every 1min, timeout 3s
  • States:
    • ✅ Healthy: all critical components OK.
    • ⚠️ Degraded: service limited but functional.
    • ❌ Unhealthy: critical components down or timeout.
  • SLA Calculation: only unhealthy states count as downtime
Average Response Time:
  • GenerateLabel: 500 ms – 1000 ms
    • Measured internally within our system. Excludes client-side network latency, request transmission, and response delivery times.
    • Carrier API performance can significantly impact this metric.
Rate Limits:
  • GenerateLabel:
    If shipment processing thresholds (number of call per hour) are exceeded, an internal alert is automatically triggered within our system.
    • 00:00 – 03:59: 200 calls/minute per sender
    • 04:00 – 23:59: 100 calls/minute per sender
    • (CET/CEST timezones)
Parallel operations:
⚠️ Important: Avoid parallel operations on the same masterId whenever possible.
  • Same method (multiple GenerateLabel calls):
    • Technically supported via a queue mechanism.
    • ⚠️ Requests are processed sequentially under the same masterId, which may cause performance degradation when multiple calls are made in parallel.
    • Recommendation: Prefer sequential calls for the same masterId to ensure optimal performance and predictable processing times.
  • Different methods (GenerateLabel + DeleteLabel):
    • ❌ Strongly discouraged and not supported.
    • No concurrency handling implemented.
    • May result in errors and/or inconsistent states.
Stress/Load testing:
  • Any load testing must be conducted with mandatory support from our technical team.

New features:

Since 2026-02-26:
  • GenerateShipment method added
  • Allows the generation of one or more labels for a shipment
Since 2025-07-10:
  • UploadDocument method added
  • Allows the upload of a document to a carrier for a specific handling unit
Since 2025-07-08:
  • GetLabel method added
  • Allows the retrieving of a label stream
Since 2025-05-27:
  • GetDocuments method added
  • Allows the obtention of documents (shipment note, receipt or packing list)
Since 2025-04-03:
  • DeleteShipment uses the carrier WebService if possible
Since 2025-04-02:
  • DeleteHandlingUnit uses the carrier WebService if possible
Since 2025-02-13:
  • Management of third party payors added
  • Management of "IsReturn" tag added
Since 2024-11-04:
  • DeleteShipment method added
  • Allows the deletion of a shipment using its MasterId

New features:

Since 2025-10-09:
  • Fix GenerateLabel not logging carrier WS call time
Since 2025-09-23:
  • Fix Deletion methods only sending the first barcode of a handling unit to carrier WS
Since 2025-09-16:
  • Fixed TranslationService's used language not being thread-safe
Since 2025-09-04:
  • Added UpdateData (hidden on swagger)
Since 2025-08-20:
  • Major code linting
Since 2025-07-29:
  • Added some bug fixes :
  • Fix CARRIER_MASTERID and SWAP_RETURN_NUMBER for WSLM2.3
  • Handle error when calling the carrier web service (LM 1.15)
  • Fix handling of custom fields when calling the LM 1.15 gateway and unit tests
  • Fix object cloning method
  • Fix XML serialization of (null) data for DG, INV, and item details
  • Add attributes to indicate the minimum number of elements in lists and required fields
Since 2025-07-08:
  • GetLabel method added
  • Allows the retrieving of a label stream
Since 2025-05-27:
  • GetDocuments method added
  • Allows the obtention of documents (shipment note, receipt or packing list)
Since 2025-05-20:
  • NuGet update
Since 2025-03-27:
  • DeleteShipment: Checks for usage of Carrier WS
Since 2025-03-26:
  • DeleteHandlingUnit: Checks for usage of Carrier WS
Since 2025-03-06:
  • Fixed CarriagePaymentType not being required
Since 2025-02-19:
  • nugets "Microsoft.EntityFrameworkCore.XXXX"
  • Update of the nugets "Microsoft.EntityFrameworkCore.XXXX" from 8.0.6 to 8.0.7
  • Deletion of nuget "Microsoft.EntityFrameworkCore.XXXX" from the project "Tdi.EXLabel.Manager"
Since 2025-02-13:
  • Management of third party payors added
  • New classes added on the project
  • Management of "IsReturn" tag added
  • Filling of the new column "IsReturn"