> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# $wsShipTrack - Sendungsverfolgung

> Modul $wsShipTrack für Sendungsverfolgung und PLZ-Validierung: Tracking-Daten anzeigen und Lieferbarkeit von Adressen vor dem Checkout prüfen.

Mit dem `$wsShipTrack` Modul können Sie auf Sendungsverfolgung und Lieferprüfungen zugreifen. Sie können dies z.B. für Tracking-Anzeigen oder PLZ-Validierungen bei der Lieferung verwenden.

***

## Modulübersicht

**Beispiel / Ausschnitt über** `$wsShipTrack`

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{= $wsShipTrack | json }}
```

**JSON-Ausgabe**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "getTracking": "ƒ()",
  "zipCodeConfirmed": "ƒ()"
}
```

Anmerkung: `ƒ()` kennzeichnet eine Funktion.

**Methoden in der Übersicht**

| **Methode**          | **Rückgabe-Typ** | **Beschreibung**                                                                        |
| -------------------- | ---------------- | --------------------------------------------------------------------------------------- |
| `getTracking()`      | map              | Gibt Tracking-Informationen eines Versanddienstleisters für bestimmte Sendungen zurück. |
| `zipCodeConfirmed()` | bool             | Gibt zurück, ob die Postleitzahl für eine bestimmte Bestellung bereits bestätigt wurde. |

***

## Templates

Sendungsverfolgung und PLZ-Prüfungen werden typischerweise an folgenden Stellen eingesetzt:

* Bestellbestätigung: Tracking-Link nach Versand der Bestellung.
* Kundenkonto: Übersicht der Sendungsverfolgung für vergangene Bestellungen.
* Checkout: PLZ-Validierung für Lieferoptionen.

***

## Variablen

Für `$wsShipTrack` stehen keine Variablen zur Verfügung.

***

## Methoden

### \$wsShipTrack.getTracking()

Lädt Tracking-Informationen eines Versanddienstleisters für eine bestimmte Sendungsnummer. Die zurückgegebenen Daten hängen direkt vom jeweiligen Provider ab, schauen Sie sich daher bei der Integration die entsprechende Schnittstelle des Anbieters an (z.B. DHL-API).

**Signatur**\
`$wsShipTrack.getTracking(id, trackingId)`

**Rückgabe**\
`map` - eine Map mit dem Ergebnis der Tracking-Anfrage.

Beispiel für die Struktur, die im Erfolgsfall zurückgegeben wird:

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "success": true,
  "lastErrorText": "",
  "lastErrorCode": 0,
  "data": <Objekt>
}
```

Der Wert unter `data` wird direkt vom Provider (z.B. DHL) geliefert und ist daher abhängig von der jeweiligen Schnittstelle.

Wenn keine Tracking-Informationen geladen werden konnten, ist `data` nicht vorhanden und `lastErrorText` sowie `lastErrorCode` enthalten die Fehlerdetails des Providers.

**Parameter**

| **Name**     | **Typ** | **Pflicht** | **Beschreibung**                                                                                                                     |
| ------------ | ------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `id`         | string  | ja          | ID des Versanddienstleisters (z.B. `dhl`). Wird unter [checkout.shipTrack](/frontend/funktionsubersicht/bestellablauf) konfiguriert. |
| `trackingId` | string  | ja          | Sendungsnummer des Versanddienstleisters (z.B. die Sendungsnummer bei DHL).                                                          |

**Beispiel,** das versucht, Tracking-Informationen zu laden.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ var $tracking = $wsShipTrack.getTracking('dhl', '1234567890') }}
{{ if $tracking.success }}
    // Tracking-Daten geladen.
{{ else }}
    // keine Tracking-Daten gefunden.
{{ /if }}
```

### \$wsShipTrack.zipCodeConfirmed()

Gibt zurück, ob die Postleitzahl für eine bestimmte Bestellung bereits bestätigt wurde. Diese Prüfung wird eingesetzt, um vor der Anzeige der Sendungsverfolgung sicherzustellen, dass es sich tatsächlich um den ursprünglichen Besteller handelt.

**Signatur**\
`$wsShipTrack.zipCodeConfirmed(orderId)`

**Rückgabe**\
`bool` - `true`, wenn die Postleitzahl für die angegebene Bestellung bereits bestätigt wurde, sonst `false`.

**Parameter**

| **Name**  | **Typ** | **Pflicht** | **Beschreibung**                                                    |
| --------- | ------- | ----------- | ------------------------------------------------------------------- |
| `orderId` | string  | ja          | ID der Bestellung, für die die PLZ-Bestätigung geprüft werden soll. |

**Beispiel,** das prüft, ob die Postleitzahl bestätigt wurde.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ if $wsShipTrack.zipCodeConfirmed($myOrderId) }}
    // Postleitzahl bestätigt.
{{ else }}
    // Postleitzahl nicht bestätigt.
{{ /if }}
```

***

## Beispiele

### Sendungsverfolgung mit PLZ-Prüfung

Dieses Beispiel prüft zunächst, ob die Postleitzahl bestätigt wurde und zeigt anschließend, sofern Tracking-Daten vorliegen, eine entsprechende Meldung an.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ if $wsShipTrack.zipCodeConfirmed($myOrderId) }}
    <p>Lieferung an bestätigte Postleitzahl.</p>
    {{ var $tracking = $wsShipTrack.getTracking('dhl', $myTrackingId) }}
    {{ if $tracking.success }}
        <p>Tracking-Informationen verfügbar.</p>
    {{ else }}
        <p>Tracking konnte nicht geladen werden: {{= $tracking.lastErrorText }}</p>
    {{ /if }}
{{ else }}
    <p>Bitte bestätigen Sie Ihre Postleitzahl, um die Sendungsverfolgung zu nutzen.</p>
{{ /if }}
```

***

## Weiterführende Links

* [\$wsCheckout](/frontend/referenz/module/wscheckout)
* [checkout - Bestellablauf](/konfiguration/checkout-bestellablauf)
* [DHL-API (extern)](https://developer.dhl.com/api-reference/dhl-paket-de-sendungsverfolgung-post-paket-deutschland?language_content_entity=de\&lang=de#get-started-section)