Shipping Apps API

Geändert am Mi, 18 Feb um 5:48 NACHMITTAGS

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).