# Apple Wallet PassKit API

Mit der PassKit Designer API können Sie [Apple Wallet-Pässe](/de/product/messaging-channels/apple-wallet-passes/) programmgesteuert erstellen, aktualisieren, herunterladen und verwalten. Sie unterstützt dieselben Vorgänge, die der Pass-Builder im Control Panel durchführt. Verwenden Sie sie, um Kundenkarten, Gutscheine, Veranstaltungstickets, Bordkarten und Kundenkarten auszustellen und Live-Updates an Pässe zu senden, die bereits auf den Geräten Ihrer Benutzer installiert sind.

<Aside type="note" title="Voraussetzung: PassKit-Zertifikat">
Bevor Sie Pässe für eine Anwendung erstellen können, muss ein iOS PassKit-Signaturzertifikat für diese Anwendung konfiguriert sein. Das Zertifikat wird im Pushwoosh Control Panel verwaltet. Ohne dieses Zertifikat schlagen `create`- und `update`-Anfragen fehl. Siehe [Konfiguration von Apple Wallet-Pässen für iOS](/de/developer/first-steps/connect-messaging-services/ios-configuration/ios-wallet-pass-configuration/).
</Aside>

## Basis-URL

```
https://apple-passkit.svc-nue.pushwoosh.com
```

Alle Endpunkte werden über HTTPS bereitgestellt. Anfragen und Antworten verwenden `application/json`, sofern nicht anders angegeben.

## Authentifizierung

Jede Anfrage muss einen `Authorization`-Header mit Ihrem [Pushwoosh API-Zugriffstoken](/de/developer/api-reference/api-access-token/) enthalten:

```
Authorization: Token <api-token>
```

Das Konto, dem das Token gehört, muss auch Eigentümer der Anwendung sein, auf die sich `applicationCode` bezieht. Eine Anfrage für eine Anwendung, die zu einem anderen Konto gehört, gibt `403 Forbidden` zurück.

## Konventionen

*   **Feldnamen:** JSON-Felder verwenden `lowerCamelCase` (zum Beispiel `passTypeIdentifier`, `serialNumber`, `backgroundColor`).
*   **Nicht gefüllte Felder:** Antworten enthalten alle Felder, auch wenn sie leer sind oder den Wert Null haben.
*   **Binärdaten:** `bytes`-Felder wie `pkpassData` und Bild-`data` sind Base64-kodierte Zeichenfolgen in JSON.
*   **Seriennummern:** Die `serialNumber` wird immer vom Server zugewiesen, wenn ein Pass erstellt wird. Jeder Wert, den Sie beim Erstellen senden, wird ignoriert; er identifiziert den Pass für alle späteren Vorgänge.

### Fehlerantworten

Die API bildet interne Statuscodes auf HTTP-Statuscodes ab:

| HTTP-Status | Bedeutung |
| :---- | :---- |
| `400 Bad Request` | Ungültiges Argument – ein erforderliches Feld fehlt oder ist fehlerhaft. |
| `401 Unauthorized` | Fehlender oder ungültiger `Authorization`-Header. |
| `403 Forbidden` | Die Anwendung gehört nicht zum Konto des Aufrufers. |
| `404 Not Found` | Der Pass, die Vorlage oder die Anwendung wurde nicht gefunden. |
| `503 Service Unavailable` | Der Dienst ist ausgelastet oder vorübergehend nicht verfügbar. |

## Endpunkte

| Methode | Pfad | Beschreibung |
| :---- | :---- | :---- |
| `POST` | `/api/pass/validate` | Eine Pass-Konfiguration validieren |
| `POST` | `/api/pass/create` | Einen neuen `.pkpass` erstellen |
| `POST` | `/api/pass/update/{serialNumber}` | Einen bestehenden Pass aktualisieren und Geräte benachrichtigen |
| `GET` | `/api/passes` | Alle Pässe für eine Anwendung auflisten |
| `GET` | `/api/pass/{applicationCode}/{serialNumber}` | Einen einzelnen Pass abrufen |
| `GET` | `/api/pass/{applicationCode}/{serialNumber}/download` | Den `.pkpass` eines bestehenden Passes herunterladen |
| `DELETE` | `/api/pass/{applicationCode}/{serialNumber}` | Einen Pass löschen |
| `GET` | `/api/pass/{serialNumber}/registrations` | Geräte auflisten, die für einen Pass registriert sind |
| `GET` | `/api/config` | Die PassKit-Konfiguration der Anwendung abrufen |
| `GET` | `/api/templates` | Verfügbare Pass-Vorlagen auflisten |
| `GET` | `/api/templates/{filename}` | Eine einzelne Vorlage abrufen |


## Einen Pass erstellen

Erzeugt, signiert und speichert einen neuen Pass und gibt dann dessen vom Server zugewiesene Seriennummer zurück.

`POST` `/api/pass/create`

<Aside type="tip">
Um die `.pkpass`-Datei selbst zu erhalten, rufen Sie [Einen Pass herunterladen](#einen-pass-herunterladen) auf (oder erstellen Sie einen [Installationslink / QR-Code](#einen-pass-als-qr-code-teilen)) mit der zurückgegebenen Seriennummer.
</Aside>


### Anfrage-Body

| Parameter | Typ | Erforderlich | Beschreibung |
| :---- | :---- | :---- | :---- |
| `pass` | Objekt | Ja | Das [Pass-Objekt](#pass-objekt), das den Pass beschreibt. |
| `images` | Array von Objekten | Nein | [Pass-Bilder](#pass-bild-objekt) (Symbol, Logo usw.). `icon` und `logo` sind für einen gültigen Pass erforderlich. |
| `userId` | Zeichenfolge | Ja | Die Pushwoosh-Benutzer-ID, für die der Pass ausgestellt wird. |
| `applicationCode` | Zeichenfolge | Ja | Der [Pushwoosh-Anwendungscode](/de/developer/api-reference/api-identifiers/#application-code). |

<Aside type="note">
Beim Erstellen, wenn `teamIdentifier`, `passTypeIdentifier` oder `organizationName` weggelassen werden, werden sie standardmäßig auf die Werte aus dem konfigurierten Zertifikat der Anwendung gesetzt. `formatVersion` wird standardmäßig auf `1` gesetzt. Die `serialNumber` wird serverseitig zugewiesen.
</Aside>

##### Anfragebeispiel

```json
{
  "applicationCode": "XXXXX-XXXXX",
  "userId": "user-123",
  "pass": {
    "description": "Acme loyalty card",
    "logoText": "Acme",
    "backgroundColor": "rgb(60, 65, 76)",
    "foregroundColor": "rgb(255, 255, 255)",
    "labelColor": "rgb(255, 255, 255)",
    "storeCard": {
      "primaryFields": [
        { "key": "balance", "label": "BALANCE", "value": "1200 pts" }
      ],
      "secondaryFields": [
        { "key": "member", "label": "MEMBER", "value": "Jane Doe" }
      ]
    },
    "barcodes": [
      {
        "format": "PKBarcodeFormatQR",
        "message": "1234567890",
        "messageEncoding": "iso-8859-1"
      }
    ]
  },
  "images": [
    { "imageType": "icon", "data": "<base64>", "contentType": "image/png" },
    { "imageType": "logo", "data": "<base64>", "contentType": "image/png" }
  ]
}
```

### Antwort

| Feld | Typ | Beschreibung |
| :---- | :---- | :---- |
| `serialNumber` | Zeichenfolge | Vom Server zugewiesene eindeutige Identität des erstellten Passes. Verwenden Sie sie, um den Pass abzurufen ([Einen Pass abrufen](#einen-pass-abrufen)) oder den `.pkpass` herunterzuladen ([Einen Pass herunterladen](#einen-pass-herunterladen)). |
| `message` | Zeichenfolge | Ergebnismeldung. |

##### Antwortbeispiel

```json
{
  "serialNumber": "a1b2c3d4-1234-5678-9abc-def012345678",
  "message": "Pass created successfully"
}
```

## Einen Pass validieren

Überprüft eine Pass-Konfiguration anhand der Spezifikationen von Apple, ohne eine Datei zu erstellen. Nützlich vor dem Aufruf von `create`.

`POST` `/api/pass/validate`

### Anfrage-Body

| Parameter | Typ | Erforderlich | Beschreibung |
| :---- | :---- | :---- | :---- |
| `pass` | Objekt | Ja | Das zu validierende [Pass-Objekt](#pass-objekt). |

### Antwort

| Feld | Typ | Beschreibung |
| :---- | :---- | :---- |
| `valid` | boolesch | Ob der Pass die Validierung besteht. |
| `errors` | Array von Zeichenfolgen | Blockierende Probleme, die behoben werden müssen. |
| `warnings` | Array von Zeichenfolgen | Nicht blockierende Hinweise. |



## Einen Pass aktualisieren

Generiert den Pass mit neuem Inhalt neu, signiert ihn erneut, erhöht sein Update-Tag und sendet eine **stille Push-Benachrichtigung** an jedes Gerät, das den Pass registriert hat. iOS holt dann die aktualisierte Version im Hintergrund ab und installiert sie.

`POST` `/api/pass/update/{serialNumber}`

### Pfadparameter

| Parameter | Typ | Beschreibung |
| :---- | :---- | :---- |
| `serialNumber` | Zeichenfolge | Die Seriennummer, die beim Erstellen des Passes zurückgegeben wurde. |

### Anfrage-Body

| Parameter | Typ | Erforderlich | Beschreibung |
| :---- | :---- | :---- | :---- |
| `updates` | Objekt | Ja | Das vollständige [Pass-Objekt](#pass-objekt) mit dem neuen Inhalt. |
| `applicationCode` | Zeichenfolge | Ja | Der Pushwoosh-Anwendungscode. |

Die `serialNumber` (aus dem Pfad) und das Authentifizierungstoken des Passes werden vom Server beibehalten, unabhängig davon, was Sie senden.

### Antwort

| Feld | Typ | Beschreibung |
| :---- | :---- | :---- |
| `success` | boolesch | Ob die Aktualisierung erfolgreich war. |
| `updateTag` | Ganzzahl | Neues Update-Tag (ein Unix-Zeitstempel). |
| `message` | Zeichenfolge | Ergebnismeldung. |



## Pässe auflisten

Gibt eine paginierte, sortierte Liste der für eine Anwendung gespeicherten Pässe zurück.

`GET` `/api/passes?applicationCode=XXXXX-XXXXX&page=0&perPage=20`

### Abfrageparameter

| Parameter | Typ | Erforderlich | Beschreibung |
| :---- | :---- | :---- | :---- |
| `applicationCode` | Zeichenfolge | Ja | Der Pushwoosh-Anwendungscode. |
| `orderBy` | Zeichenfolge | Nein | Sortierfeld: `UPDATED` (Standard) oder `CREATED`. |
| `orderDirection` | Zeichenfolge | Nein | Sortierrichtung: `DESC` (Standard, neueste zuerst) oder `ASC`. |
| `page` | Ganzzahl | Nein | Nullbasierter Seitenindex. Standard ist `0`. |
| `perPage` | Ganzzahl | Nein | Seitengröße. `0` oder weggelassen verwendet den Server-Standard. |

### Antwort

| Feld | Typ | Beschreibung |
| :---- | :---- | :---- |
| `passes` | Array von Objekten | Die aktuelle Seite der [Pass-Datensätze](#pass-datensatz-objekt). |
| `page` | Ganzzahl | Der zurückgegebene Seitenindex. |
| `perPage` | Ganzzahl | Die für diese Antwort verwendete Seitengröße. |
| `total` | Ganzzahl | Gesamtzahl der Pässe für die Anwendung über alle Seiten hinweg. |

##### Antwortbeispiel

```json
{
  "passes": [ /* pass records */ ],
  "page": 0,
  "perPage": 20,
  "total": 137
}
```


## Einen Pass abrufen

Gibt einen einzelnen gespeicherten Pass zurück, einschließlich seines vollständigen Pass-Objekts.

`GET` `/api/pass/{applicationCode}/{serialNumber}`

### Pfadparameter

| Parameter | Typ | Beschreibung |
| :---- | :---- | :---- |
| `applicationCode` | Zeichenfolge | Der Pushwoosh-Anwendungscode. |
| `serialNumber` | Zeichenfolge | Die Seriennummer des Passes. |

### Antwort

Gibt `{ "pass": { ... } }` zurück, einen einzelnen [Pass-Datensatz](#pass-datensatz-objekt).


## Einen Pass herunterladen

Gibt die gespeicherte `.pkpass`-Datei eines bestehenden Passes zurück.

`GET` `/api/pass/{applicationCode}/{serialNumber}/download`

### Antwort

| Feld | Typ | Beschreibung |
| :---- | :---- | :---- |
| `pkpassData` | Zeichenfolge (Base64) | Die `.pkpass`-Datei. |
| `filename` | Zeichenfolge | Vorgeschlagener Dateiname. |


## Einen Pass löschen

Entfernt einen Pass-Datensatz und seine gespeicherte `.pkpass`-Datei.

`DELETE` `/api/pass/{applicationCode}/{serialNumber}`

### Antwort

| Feld | Typ | Beschreibung |
| :---- | :---- | :---- |
| `success` | boolesch | Ob der Pass gelöscht wurde. |
| `message` | Zeichenfolge | Ergebnismeldung. |



## Pass-Registrierungen abrufen

Listet die Geräte auf, die den Pass hinzugefügt haben und für Updates registriert sind.

`GET` `/api/pass/{serialNumber}/registrations?applicationCode=XXXXX-XXXXX`

### Antwort

Gibt `{ "registrations": [ ... ] }` zurück, wobei jedes Element Folgendes enthält:

| Feld | Typ | Beschreibung |
| :---- | :---- | :---- |
| `deviceLibraryIdentifier` | Zeichenfolge | Apple-Gerätebibliotheks-Identifikator. |
| `pushToken` | Zeichenfolge | Das Pass-Push-Token für das Gerät. |



## Konfiguration abrufen

Gibt die für eine Anwendung aus ihrem Zertifikat aufgelöste PassKit-Konfiguration zurück.

`GET` `/api/config?applicationCode=XXXXX-XXXXX`

### Antwort

| Feld | Typ | Beschreibung |
| :---- | :---- | :---- |
| `teamIdentifier` | Zeichenfolge | Apple Team ID aus dem Zertifikat. |
| `passTypeIdentifier` | Zeichenfolge | Pass Type ID aus dem Zertifikat. |
| `organizationName` | Zeichenfolge | Organisationsname aus dem Zertifikat. |
| `hasCertificate` | boolesch | Ob ein Zertifikat konfiguriert ist. |
| `webServiceUrl` | Zeichenfolge | Basis-URL des Pass-Webdienstes. Clients erstellen einen Installationslink, indem sie `/v1/passes/{passType}/{serial}?token={authToken}` anhängen. |



## Vorlagen

Listen Sie die verfügbaren Pass-Vorlagen auf oder rufen Sie eine als [Pass-Objekt](#pass-objekt) ab, das Sie als Ausgangspunkt verwenden können.

`GET` `/api/templates` — gibt `{ "templates": [ { "filename", "name", "description", "style" } ] }` zurück.

`GET` `/api/templates/{filename}` — gibt `{ "template": { ...pass object... } }` zurück.



## Einen Pass als QR-Code teilen

Damit Benutzer einen Pass durch Scannen eines QR-Codes (oder Tippen auf einen Link) hinzufügen können, kodieren Sie die **Installations-URL** des Passes in einen QR-Code. Die URL wird aus Werten zusammengestellt, die Sie bereits von der API zurückerhalten:

```
{webServiceUrl}/v1/passes/{passTypeIdentifier}/{serialNumber}?token={authenticationToken}
```

| URL-Teil | Woher zu bekommen |
| :---- | :---- |
| `webServiceUrl` | [`GET /api/config`](#konfiguration-abrufen) → `webServiceUrl` |
| `passTypeIdentifier` | [Pass-Datensatz](#pass-datensatz-objekt) → `pass.passTypeIdentifier` (aus Liste/Abruf) |
| `serialNumber` | [Pass-Datensatz](#pass-datensatz-objekt) → `serialNumber` |
| `authenticationToken` | [Pass-Datensatz](#pass-datensatz-objekt) → `pass.authenticationToken` |

Beispiel:

```
https://apple-passkit.svc-nue.pushwoosh.com/v1/passes/pass.com.acme.loyalty/a1b2c3d4-1234-5678-9abc-def012345678?token=AbC123XyZ
```

Rendern Sie diese URL mit einer beliebigen QR-Bibliothek als QR-Code. Wenn ein Benutzer ihn scannt, öffnet sein Gerät den Link, lädt die neueste `.pkpass`-Datei herunter und Wallet fordert ihn auf, sie hinzuzufügen – was auch das Gerät für Updates registriert.



## Objektreferenz

### Pass-Objekt

| Feld | Typ | Beschreibung |
| :---- | :---- | :---- |
| `formatVersion` | Ganzzahl | Version des Pass-Formats. Standard ist `1`. |
| `passTypeIdentifier` | Zeichenfolge | Apple Pass Type ID (`pass.com.yourcompany.passtype`). Standardmäßig aus dem Zertifikat. |
| `serialNumber` | Zeichenfolge | Wird vom Server beim Erstellen zugewiesen; identifiziert den Pass. |
| `teamIdentifier` | Zeichenfolge | Apple Team ID. Standardmäßig aus dem Zertifikat. |
| `organizationName` | Zeichenfolge | Organisation, die auf dem Pass angezeigt wird. Standardmäßig aus dem Zertifikat. |
| `description` | Zeichenfolge | Menschenlesbare Beschreibung (von Apple gefordert). |
| `boardingPass` / `coupon` / `eventTicket` / `storeCard` / `generic` | Objekt | Der Stil des Passes. **Genau einer** muss gesetzt sein. Siehe [Feldgruppen](#feldgruppenobjekt). |
| `backgroundColor` | Zeichenfolge | Hintergrundfarbe, `rgb(r, g, b)`. |
| `foregroundColor` | Zeichenfolge | Vordergrundfarbe (Text), `rgb(r, g, b)`. |
| `labelColor` | Zeichenfolge | Farbe der Feldbeschriftung, `rgb(r, g, b)`. |
| `logoText` | Zeichenfolge | Text, der neben dem Logo angezeigt wird. |
| `suppressStripShine` | boolesch | Deaktiviert den Glanzeffekt auf dem Streifenbild. |
| `barcodes` | Array | [Barcodes](#barcode-objekt), die auf dem Pass angezeigt werden. |
| `locations` | Array | [Orte](#ort-objekt), die den Pass relevant machen. |
| `beacons` | Array | [Beacons](#beacon-objekt), die den Pass relevant machen. |
| `relevantDate` | Zeichenfolge | ISO 8601-Datum, an dem der Pass relevant wird. |
| `maxDistance` | Ganzzahl | Maximale Entfernung (Meter) für die Ortsrelevanz. |
| `expirationDate` | Zeichenfolge | ISO 8601-Ablaufdatum. |
| `voided` | boolesch | Markiert den Pass als ungültig. |
| `groupingIdentifier` | Zeichenfolge | Gruppiert zusammengehörige Pässe (Veranstaltungstickets/Bordkarten). |
| `userInfo` | Objekt (Map) | Beliebige Schlüssel/Wert-App-Daten. |

<Aside type="note">
`authenticationToken` und `webServiceUrl` werden vom Dienst verwaltet und müssen nicht von API-Clients gesetzt werden.
</Aside>

### Feldgruppenobjekt

Jeder Pass-Stil (`boardingPass`, `coupon`, `eventTicket`, `storeCard`, `generic`) gruppiert [Felder](#feld-objekt) in Bereiche:

| Feld | Typ | Beschreibung |
| :---- | :---- | :---- |
| `headerFields` | Array | Wird im Pass-Header angezeigt (sichtbar, wenn in Wallet gestapelt). |
| `primaryFields` | Array | Die prominentesten Felder. |
| `secondaryFields` | Array | Unter den primären Feldern. |
| `auxiliaryFields` | Array | Zusätzliche Felder unter den sekundären. |
| `backFields` | Array | Wird auf der Rückseite des Passes angezeigt. |

`boardingPass` hat zusätzlich `transitType` (`PKTransitTypeAir`, `PKTransitTypeTrain`, `PKTransitTypeBus`, `PKTransitTypeBoat` oder `PKTransitTypeGeneric`).

### Feld-Objekt

| Feld | Typ | Beschreibung |
| :---- | :---- | :---- |
| `key` | Zeichenfolge | Eindeutiger Feldschlüssel innerhalb des Passes. |
| `label` | Zeichenfolge | Feldbeschriftung. |
| `value` | Zeichenfolge | Feldwert (Text oder Zahl als Zeichenfolge). |
| `changeMessage` | Zeichenfolge | Nachricht, die angezeigt wird, wenn sich der Wert ändert (verwenden Sie `%@` als Platzhalter). |
| `textAlignment` | Zeichenfolge | `PKTextAlignment`-Wert. |
| `dateStyle` / `timeStyle` | Zeichenfolge | `PKDateStyle` für die Datums-/Zeitformatierung. |
| `isRelative` | boolesch | Zeigt das Datum relativ zu jetzt an. |
| `numberStyle` | Zeichenfolge | `PKNumberStyle` für die Zahlenformatierung. |
| `currencyCode` | Zeichenfolge | ISO 4217-Währungscode. |
| `dataDetectorTypes` | Array von Zeichenfolgen | Datendetektoren, die auf den Wert angewendet werden sollen. |

### Barcode-Objekt

| Feld | Typ | Beschreibung |
| :---- | :---- | :---- |
| `format` | Zeichenfolge | `PKBarcodeFormatQR`, `PKBarcodeFormatPDF417`, `PKBarcodeFormatAztec` oder `PKBarcodeFormatCode128`. |
| `message` | Zeichenfolge | Im Barcode kodierte Daten. |
| `messageEncoding` | Zeichenfolge | Textkodierung, typischerweise `iso-8859-1`. |
| `altText` | Zeichenfolge | Text, der unter dem Barcode angezeigt wird. |

### Ort-Objekt

| Feld | Typ | Beschreibung |
| :---- | :---- | :---- |
| `latitude` | Zahl | Breitengrad. |
| `longitude` | Zahl | Längengrad. |
| `altitude` | Zahl | Höhe in Metern. |
| `relevantText` | Zeichenfolge | Text, der auf dem Sperrbildschirm in der Nähe dieses Ortes angezeigt wird. |

### Beacon-Objekt

| Feld | Typ | Beschreibung |
| :---- | :---- | :---- |
| `proximityUuid` | Zeichenfolge | iBeacon Proximity UUID. |
| `major` | Ganzzahl | Major-Wert. |
| `minor` | Ganzzahl | Minor-Wert. |
| `relevantText` | Zeichenfolge | Text, der auf dem Sperrbildschirm in der Nähe dieses Beacons angezeigt wird. |

### Pass-Bild-Objekt

| Feld | Typ | Beschreibung |
| :---- | :---- | :---- |
| `imageType` | Zeichenfolge | Eines von `icon`, `logo`, `strip`, `background`, `footer`, `thumbnail`. `icon` und `logo` sind erforderlich. |
| `data` | Zeichenfolge (Base64) | Bild-Bytes. |
| `contentType` | Zeichenfolge | MIME-Typ, zum Beispiel `image/png`. |

### Pass-Datensatz-Objekt

Wird von Listen-/Abruf-Endpunkten zurückgegeben.

| Feld | Typ | Beschreibung |
| :---- | :---- | :---- |
| `serialNumber` | Zeichenfolge | Seriennummer des Passes. |
| `passTypeIdentifier` | Zeichenfolge | Pass Type ID. |
| `organizationName` | Zeichenfolge | Organisationsname. |
| `description` | Zeichenfolge | Pass-Beschreibung. |
| `createdAt` | Zeichenfolge | Erstellungszeitstempel (RFC 3339). |
| `updatedAt` | Zeichenfolge | Zeitstempel der letzten Aktualisierung (RFC 3339). |
| `updateTag` | Ganzzahl | Aktuelles Update-Tag. |
| `pass` | Objekt | Das vollständige [Pass-Objekt](#pass-objekt) zur Bearbeitung. |
| `userId` | Zeichenfolge | Pushwoosh-Benutzer-ID, für die der Pass ausgestellt wurde. |