API: Lieferaufträge abrufen (Outbound, ohne Retouren)

Mit diesem Endpunkt kannst du deine zuletzt erzeugten easyDHL-Lieferaufträge (keine Retouren) samt Tracking- und Dokument-Links abrufen. Die Authentifizierung erfolgt per Bearer-Token im HTTP-Header.

Authentifizierung

• Header: Authorization: Bearer <DEIN_TOKEN>
• Das Token findest du in der App unter Einstellungen → DHL.
• Empfohlen: Accept: application/json

HTTP

• Methode: GET
• URL: https://easydhl.247apps.de/api/orders

Query-Parameter

Wichtig: Mindestens einer der beiden Start-Parameter (from_order_id oder from_order_name) ist erforderlich. Ist einer gesetzt, ist der andere optional.

Filter- & Sortierlogik (vereinfacht)

• Es werden ausschließlich Outbound-Lieferungen zurückgegeben (is_retoure = 0).
• Gefiltert wird ab from_order_id oder from_order_name:
  • skip_first = false (Standard): ≥ Startpunkt
  • skip_first = true: > Startpunkt
• Optionaler Filter: automated (nur wenn der Parameter übergeben wird).
• Gruppierung nach order_name, Sortierung aufsteigend nach order_name, dann Limit via take.

Antwortformat

Der Endpunkt liefert ein verschachteltes Array: eine äußere Array-Hülle mit genau einem Element, das die eigentliche Ergebnisliste enthält.

[
  [
    {
      "order_id": 1234567890,
      "order_name": "#1001",
      "tracking_number": "00340434…",
      "labelUrl": "https://…/label.pdf",
      "retoureUrl": null,
      "slipUrl": "https://…/slip.pdf",
      "invoiceUrl": "https://…/invoice.pdf",
      "exportUrl": "https://…/export.pdf",
      "exportStickerUrl": "https://…/export-sticker.png"
    },
    {
      "order_id": 1234567891,
      "order_name": "#1002",
      "tracking_number": "00340434…",
      "labelUrl": "https://…/label.pdf",
      "retoureUrl": null,
      "slipUrl": null,
      "invoiceUrl": null,
      "exportUrl": null,
      "exportStickerUrl": "https://…/export-sticker.png"
    }
  ]
]

• labelUrl, retoureUrl, slipUrl, invoiceUrl, exportUrl sind signierte Download-Links (können null sein, wenn das jeweilige Dokument nicht existiert).
• exportStickerUrl stammt aus der App-Konfiguration (config('shipping.exportSticker')) und kann z. B. ein statischer Sticker/Template-Link sein.

Beispiel: cURL

curl -X GET "https://easydhl.247apps.de/api/orders?from_order_name=%231001&take=50&skip_first=true" \
  -H "Authorization: Bearer <DEIN_TOKEN>" \
  -H "Accept: application/json"

Beispiel: JavaScript (fetch)

const url = "https://easydhl.247apps.de/api/orders?from_order_id=1234567890&take=10&automated=1";
const res = await fetch(url, {
  headers: {
    "Authorization": "Bearer <DEIN_TOKEN>",
    "Accept": "application/json"
  }
});
const data = await res.json();
// data[0] ist die eigentliche Ergebnisliste
console.log(data[0]);

Beispiel: PHP (Guzzle)

$client = new \GuzzleHttp\Client([
  'base_uri' => 'https://easydhl.247apps.de',
  'headers' => [
    'Authorization' => 'Bearer ' . $token,
    'Accept'        => 'application/json',
  ],
]);

$response = $client->get('/api/orders', [
  'query' => [
    'from_order_name' => '#1001',
    'take'            => 25,
    'skip_first'      => true,
  ],
]);

$payload = json_decode($response->getBody()->getContents(), true);
$orders  = $payload[0] ?? [];

Paginieren (empfohlener Ablauf)

1. Starte mit deinem gewünschten from_order_name (oder from_order_id) und setze take (z. B. 50).
2. Für die nächste Seite: Verwende den letzten order_name (oder order_id) aus der aktuellen Antwort erneut als Startpunkt und setze skip_first=true, um Duplikate zu vermeiden.

Fehlerbilder & Hinweise

• 400 Bad Request: Keiner der Pflicht-Startparameter übermittelt (from_order_id oder from_order_name).
• 401 Unauthorized: Fehlendes oder ungültiges Bearer-Token.
• Leere Felder: Dokument-URLs können null sein, wenn nicht erzeugt/vorhanden.
• Nur Outbound: Retouren (is_retoure = 1) sind ausgeschlossen.

Schnelltest

curl -X GET "https://easydhl.247apps.de/api/orders?from_order_name=%231000" \
  -H "Authorization: Bearer <DEIN_TOKEN>" \
  -H "Accept: application/json"

Fragen oder Probleme? Bitte nenne uns die vollständige Anfrage-URL (ohne Token), Zeitpunkt, sowie die erste Zeile der JSON-Antwort/Fehlermeldung.