easyDHL · FAQ

Schnittstelle zum abrufen von Sendungsdaten und Dokumenten

API Guide: GET api/orders

Base URL: https://easydhl.247apps.de

Was macht dieser Endpoint?

Dieser Endpoint liefert Versanddaten zu Bestellungen, inklusive Tracking-Nummer und Download-Links (z. B. Label oder Lieferschein), wenn diese verfügbar sind.

Schnellstart

Authentifiziere dich per Bearer-Token.
Sende den Header Accept: application/json.
Übergib einen Startpunkt über from_order_id oder from_order_name.
Optional: steuere Umfang mit take und Verhalten mit skip_first.

Endpoint

Methode: GET
URL: /api/orders

Authentifizierung

Sende den Shop-API-Key als Bearer-Token. Den API-Key findest du unter Einstellungen->DHL innerhalb der App.

Authorization: Bearer <API_KEY_DES_SHOPS>
Accept: application/json

Wenn der Token fehlt oder ungültig ist, erhältst du 403 Unauthenticated.

Query-Parameter

Parameter	Typ	Pflicht	Beschreibung
from_order_id	string oder int	Bedingt	Start ab dieser Order-ID. Pflicht, wenn `from_order_name` nicht gesetzt ist.
from_order_name	string	Bedingt	Start ab diesem Bestellnamen (z. B. `#1001`). Pflicht, wenn `from_order_id` nicht gesetzt ist.
skip_first	boolean	Nein	`true`: Start-Bestellung überspringen. `false`/nicht gesetzt: Start-Bestellung einschließen.
take	int	Nein	Anzahl der zurückgegebenen Ergebnisse. Standard: `1`.
automated	boolean, int oder string	Nein	Filtert auf automatisch erzeugte Vorgänge.

Wichtige Regeln

Du musst mindestens einen der beiden Startparameter senden:
- from_order_id
- from_order_name
skip_first akzeptiert boolean-kompatible Werte (true/false, 1/0).
Sende immer den Header Accept: application/json, damit Fehler- und Erfolgsantworten zuverlässig als JSON zurückgegeben werden.

Request-Beispiele

Start über Order-ID:

curl -G 'https://<deine-domain>/api/orders' \
  -H 'Authorization: Bearer <API_KEY_DES_SHOPS>' \
  -H 'Accept: application/json' \
  --data-urlencode 'from_order_id=1234567890' \
  --data-urlencode 'take=5'

Start über Order-Name und erste Order überspringen:

curl -G 'https://<deine-domain>/api/orders' \
  -H 'Authorization: Bearer <API_KEY_DES_SHOPS>' \
  -H 'Accept: application/json' \
  --data-urlencode 'from_order_name=#1001' \
  --data-urlencode 'skip_first=true' \
  --data-urlencode 'take=3'

Erfolgsantwort

Status: 200 OK

Hinweis zur Struktur: Die API liefert aktuell ein äußeres Array mit einem inneren Ergebnis-Array.

[
    [
        {
            "order_id": "1234567890",
            "order_name": "#1001",
            "tracking_number": "00340434161094012345",
            "labelUrl": "https://...",
            "retoureUrl": null,
            "slipUrl": "https://...",
            "invoiceUrl": null,
            "exportUrl": null,
            "exportStickerUrl": null
        }
    ]
]

Response-Felder

order_id: ID der Bestellung
order_name: Name/Nummer der Bestellung
tracking_number: Versand-Trackingnummer
labelUrl: Signierter Download-Link zum Label oder null
retoureUrl: Signierter Download-Link zum Retourenlabel oder null
slipUrl: Signierter Download-Link zum Lieferschein oder null
invoiceUrl: Signierter Download-Link zur Rechnung oder null
exportUrl: Signierter Download-Link zum Exportdokument oder null
exportStickerUrl: URL für Export-Sticker oder null

Fehlerantworten

403 Unauthenticated

{
    "message": "Unauthenticated"
}

422 Validation Error

Typische Ursache: weder from_order_id noch from_order_name gesendet.

{
    "message": "The given data was invalid.",
    "errors": {
        "from_order_id": [
            "The from order id field is required when from order name is not present."
        ],
        "from_order_name": [
            "The from order name field is required when from order id is not present."
        ]
    }
}

Integrationshinweise

Behandle alle URL-Felder als optional (null möglich).
Plane für die aktuelle verschachtelte Array-Struktur der Antwort.
Verwende take für Paging-artige Abrufe in kleineren Batches.
Sende Accept: application/json, damit insbesondere Validierungs- und Authentifizierungsfehler nicht als HTML-Antwort zurückkommen.