Apple Wallet PassKit API

Mit der PassKit Designer API können Sie Apple Wallet-Pässe 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.

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.

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

Tipp

Um die .pkpass-Datei selbst zu erhalten, rufen Sie Einen Pass herunterladen auf (oder erstellen Sie einen Installationslink / QR-Code) mit der zurückgegebenen Seriennummer.

Anfrage-Body

Parameter	Typ	Erforderlich	Beschreibung
pass	Objekt	Ja	Das Pass-Objekt, das den Pass beschreibt.
images	Array von Objekten	Nein	Pass-Bilder (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.

Hinweis

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.

Anfragebeispiel

{
  "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) oder den .pkpass herunterzuladen (Einen Pass herunterladen).
message	Zeichenfolge	Ergebnismeldung.

Antwortbeispiel

{
  "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.

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

{
  "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.

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 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 → webServiceUrl
passTypeIdentifier	Pass-Datensatz → pass.passTypeIdentifier (aus Liste/Abruf)
serialNumber	Pass-Datensatz → serialNumber
authenticationToken	Pass-Datensatz → 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.
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, die auf dem Pass angezeigt werden.
locations	Array	Orte, die den Pass relevant machen.
beacons	Array	Beacons, 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.

Hinweis

authenticationToken und webServiceUrl werden vom Dienst verwaltet und müssen nicht von API-Clients gesetzt werden.

Feldgruppenobjekt

Jeder Pass-Stil (boardingPass, coupon, eventTicket, storeCard, generic) gruppiert Felder 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 zur Bearbeitung.
userId	Zeichenfolge	Pushwoosh-Benutzer-ID, für die der Pass ausgestellt wurde.