Zum Inhalt springen

App-Dokumentation · DE

Sendungsverfolgung

Mit Sendungsverfolgung verfolgen Sie Pakete auf Basis des ERP-Carriers/Tracking-Backends: Sendung registrieren, Carrier abrufen und beobachten, wie die einheitliche Ereignis-Zeitleiste von registriert bis zugestellt voranschreitet. Der aufgerollte Status wird als farbiges Badge angezeigt.

Bereiche

  • Verfolgen: ein Registrierungsformular (Carrier + Sendungsnummer + optionale Sendungs-ID), eine Suchleiste (Verfolgen / Abrufen) und die Zeitleiste der aktuell geladenen Sendung.
  • Hilfe: In-App-Hinweise.

Felder und Konzepte

  • Sendung: carrier, tracking_no, optionale shipment_id, ein aufgerollter status, created_at und last_polled_at.
  • Ereignis: ein Zeitleisten-Scan mit ts (UTC Y-m-d H:i:s), status, optionalem location und description.
  • Status: registered | picked_up | in_transit | out_for_delivery | delivered | exception | returned. Der aufgerollte Status folgt dem neuesten Scan nach Zeitstempel.

Backend-Vertrag

Alle Routen liegen unter /api/erp/tracking, mandantenbezogen, mit dem {success, data}-Umschlag.

  • POST /register — Sendung registrieren. Body (snake_case): {carrier, tracking_no, shipment_id?}. Liefert 201 {id}. Idempotent auf (tenant, tracking_no).
  • POST /poll — Carrier-Adapter abrufen. Body: {tracking_no}. Liefert {appended, status}. Erneutes Abrufen ohne neue Scans fügt nichts hinzu.
  • GET /timeline/{trackingNo} — geordnete Zeitleiste. Liefert {tracking, events} oder 404, wenn die Nummer unbekannt ist.

Die Authentifizierung erfolgt per httpOnly-Cookie + CSRF über @it-tremmel.de/platform-http authedFetch (credentials: 'include'); es werden keine Tokens aus localStorage gelesen.

Typischer Ablauf

  1. Eine Sendung mit Carrier und Sendungsnummer registrieren.
  2. Den Carrier abrufen, um neue Scans in die Zeitleiste zu übernehmen.
  3. Die geordnete Ereignis-Zeitleiste und das aufgerollte Status-Badge lesen.
  4. Später eine beliebige Sendungsnummer suchen, um ihre Zeitleiste erneut zu öffnen.

Registrieren und Carrier-Abfragen sind während der Verarbeitung einschließlich Timeline-Aktualisierung gesperrt. Weitere Auslösungen senden keine zweite Anfrage. Nach Erfolg oder Fehler ist eine neue Aktion möglich.