Shipping Apps API
Orders Endpoint
Diese API erlaubt es, Versand-/Dokumentdaten zu bereits erzeugten Sendungen („Deliveries“) eines Shops abzurufen (Trackingnummern + Download-URLs für Label, Retoure, Lieferschein, Rechnung, Exportdokumente).
Base URL
Base URL: https://easydhl.247apps.de/api , https://easydpd.247apps.de/api , https://easyhermes.247apps.de/api , https://easygls.247apps.de/api
Alle Requests müssen über HTTPS erfolgen.
Authentifizierung
Bearer Token
Die API verwendet Bearer Token Auth. Der Token entspricht dem SHOP_API_KEY des Shops.
Header:
Authorization: Bearer <SHOP_API_KEY>
SHOP_API_KEY zu finden in der App unter Einstellungen -> Allgemein
Fehlerfälle:
403 Unauthenticated – wenn kein Shop mit diesem api_key gefunden wird.
Response (Beispiel):
{ "message": "Unauthenticated" }App-Plan
Wenn der Shop das Feature/Plan (Premium-Plus) nicht aktiviert hat, gibt die API 403 zurück.
Fehler:
403 planUpgradeRequired
{ "message": "planUpgradeRequired" }Endpoint: List Orders
GET
/orders
Liefert eine Liste von Orders (basierend auf deliveries) ab einem Startpunkt (from_order_id oder from_order_name) mit optionalem „skip first“ und optionalem Filter auf „automated“.
Query Parameter
Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
take | integer | optional | Anzahl der Ergebnisse. Default: 1 |
skip_first | boolean | optional | Wenn true, wird strikt größer als Startwert verwendet (> statt >=) |
from_order_id | string/int | bedingt | Pflicht, wenn from_order_name fehlt |
from_order_name | string | bedingt | Pflicht, wenn from_order_id fehlt |
automated | boolean/int | optional | Wenn 1 dann werden nur Datensätze aus der Automation berücksichtigt |
Validierungslogik (kurz):
Du musst genau einen Startparameter setzen: from_order_id oder from_order_name.
skip_first muss boolean sein, wenn gesetzt.
Beispiel Requests
1) Eine Verarbeitung/Bestellung abrufen
curl -H "Authorization: Bearer <SHOP_API_KEY>" \ "https://<deine-domain>/api/orders?from_order_name=10001"2) Nächste Verarbeitung/Bestellung ab Order-Name (Startorder überspringen) so kann z.B. geblättert werden
curl -H "Authorization: Bearer <SHOP_API_KEY>" \ "https://<deine-domain>/api/orders?from_order_name=10001&skip_first=1"3) Nur automatisierte Vorgänge
curl -H "Authorization: Bearer <SHOP_API_KEY>" \ "https://<deine-domain>/api/orders?from_order_name=10001&automated=1"4) Wie in 1 bis 3 gezeigt nur über order_id statt order_name
curl -H "Authorization: Bearer <SHOP_API_KEY>" \ "https://<deine-domain>/api/orders?from_order_id=1234567890"Response
Format
Der Controller gibt aktuell ein Array zurück, das eine Liste enthält:
Response Fields (pro Item)
Feld | Typ | Beschreibung |
|---|---|---|
order_id | string/int | Shopify Order ID |
order_name | string | Shopify Order Name (z. B. #1001 oder 1001, je nach Speicherung) |
tracking_number | string/null | Trackingnummer der Delivery |
labelUrl | string/null | Signierte Download-URL für Versandlabel |
retoureUrl | string/null | Signierte Download-URL für Retourenlabel |
slipUrl | string/null | Signierte Download-URL für Lieferschein |
invoiceUrl | string/null | Signierte Download-URL für Rechnung |
exportUrl | string/null | Signierte Download-URL für Exportdokument |
exportStickerUrl | string/null | Statische URL/Config für Export-Sticker |
Status Codes & Errors
Status | Message | Wann tritt es auf |
|---|---|---|
200 | – | Erfolgreich |
403 | Unauthenticated | Bearer Token fehlt/ist ungültig (Shop nicht gefunden) |
403 | planUpgradeRequired | Route erfordert Plan/Feature, Shop erfüllt es nicht |
422 | Laravel Validation Error | Fehlende/ungültige Query Parameter (z. B. weder from_order_id noch from_order_name) |
Pagination Pattern (Empfehlung für Clients)
Da die API „cursor-basiert“ über from_order_* arbeitet, ist ein typischer Ablauf:
Initialer Call mit from_order_name=<kleinster Startwert> und take=n
Nimm aus der letzten Antwort den letzten order_name (oder order_id, je nachdem wie du paginierst)
Nächster Call mit skip_first=1 und from_order_name=<letzter order_name>
Sicherheits- und Integrationshinweise
Der api_key ist ein Geheimnis. Niemals im Frontend ausliefern; nur serverseitig verwenden.
Download-URLs sind signiert und üblicherweise zeitlich begrenzt (abhängig von deiner signedDownloadUrl()-Implementierung).