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 um 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 der 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 ausgefü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 Zeichenketten in JSON.
• Seriennummern: Die serialNumber wird immer vom Server zugewiesen, wenn ein Pass erstellt wird. Jeder Wert, den Sie bei der Erstellung senden, wird ignoriert; sie identifiziert den Pass für alle späteren Operationen.

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	Für einen Pass registrierte Geräte auflisten
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 seine 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.

Anfragekörper

Parameter	Typ	Erforderlich	Beschreibung
pass	object	Ja	Das Pass-Objekt, das den Pass beschreibt.
images	array of objects	Nein	Pass-Bilder (Symbol, Logo usw.). icon und logo sind für einen gültigen Pass erforderlich.
userId	string	Ja	Die Pushwoosh User ID, für die der Pass ausgestellt wird.
applicationCode	string	Ja	Der Pushwoosh-Anwendungscode.

Hinweis

Wenn bei der Erstellung teamIdentifier, passTypeIdentifier oder organizationName weggelassen werden, werden standardmäßig die Werte aus dem konfigurierten Zertifikat der Anwendung verwendet. formatVersion ist standardmäßig 1. Die serialNumber wird serverseitig zugewiesen.

Beispiel für eine Anfrage

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

Beispiel für eine Antwort

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

Anfragekörper

Parameter	Typ	Erforderlich	Beschreibung
pass	object	Ja	Das zu validierende Pass-Objekt.

Antwort

Feld	Typ	Beschreibung
valid	boolean	Ob der Pass die Validierung besteht.
errors	array of strings	Blockierende Probleme, die behoben werden müssen.
warnings	array of strings	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 ruft dann die aktualisierte Version ab und installiert sie im Hintergrund.

POST /api/pass/update/{serialNumber}

Pfadparameter

Parameter	Typ	Beschreibung
serialNumber	string	Die Seriennummer, die bei der Erstellung des Passes zurückgegeben wurde.

Anfragekörper

Parameter	Typ	Erforderlich	Beschreibung
updates	object	Ja	Das vollständige Pass-Objekt mit dem neuen Inhalt.
applicationCode	string	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	boolean	Ob das Update erfolgreich war.
updateTag	integer	Neues Update-Tag (ein Unix-Zeitstempel).
message	string	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	string	Ja	Der Pushwoosh-Anwendungscode.
orderBy	string	Nein	Sortierfeld: UPDATED (Standard) oder CREATED.
orderDirection	string	Nein	Sortierrichtung: DESC (Standard, neueste zuerst) oder ASC.
page	integer	Nein	Nullbasierter Seitenindex. Standard ist 0.
perPage	integer	Nein	Seitengröße. 0 oder weggelassen verwendet den Server-Standard.

Antwort

Feld	Typ	Beschreibung
passes	array of objects	Die aktuelle Seite der Pass-Datensätze.
page	integer	Der zurückgegebene Seitenindex.
perPage	integer	Die für diese Antwort verwendete Seitengröße.
total	integer	Gesamtzahl der Pässe für die Anwendung über alle Seiten hinweg.

Beispiel für eine Antwort

{
  "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	string	Der Pushwoosh-Anwendungscode.
serialNumber	string	Die Seriennummer des Passes.

Antwort

Gibt { "pass": { ... } } zurück, einen einzelnen Pass-Datensatz.

Einen Pass herunterladen

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

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

Antwort

Feld	Typ	Beschreibung
pkpassData	string (Base64)	Die .pkpass-Datei.
filename	string	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	boolean	Ob der Pass gelöscht wurde.
message	string	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	string	Apple-Gerätebibliotheks-Identifikator.
pushToken	string	Das Pass-Push-Token für das Gerät.

Konfiguration abrufen

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

GET /api/config?applicationCode=XXXXX-XXXXX

Antwort

Feld	Typ	Beschreibung
teamIdentifier	string	Apple Team ID aus dem Zertifikat.
passTypeIdentifier	string	Pass Type ID aus dem Zertifikat.
organizationName	string	Organisationsname aus dem Zertifikat.
hasCertificate	boolean	Ob ein Zertifikat konfiguriert ist.
webServiceUrl	string	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

Um Benutzern das Hinzufügen eines Passes durch Scannen eines QR-Codes (oder Tippen auf einen Link) zu ermöglichen, kodieren Sie die Installations-URL des Passes in einen QR-Code. Die URL wird aus Werten erstellt, die Sie bereits von der API zurückerhalten:

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

URL-Teil	Woher beziehen
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 den neuesten .pkpass herunter und Wallet fordert ihn auf, ihn hinzuzufügen – was auch das Gerät für Updates registriert.

Objektreferenz

Pass-Objekt

Feld	Typ	Beschreibung
formatVersion	integer	Pass-Formatversion. Standard ist 1.
passTypeIdentifier	string	Apple Pass Type ID (pass.com.yourcompany.passtype). Standardwert aus dem Zertifikat.
serialNumber	string	Wird vom Server bei der Erstellung zugewiesen; identifiziert den Pass.
teamIdentifier	string	Apple Team ID. Standardwert aus dem Zertifikat.
organizationName	string	Organisation, die auf dem Pass angezeigt wird. Standardwert aus dem Zertifikat.
description	string	Von Menschen lesbare Beschreibung (von Apple gefordert).
boardingPass / coupon / eventTicket / storeCard / generic	object	Der Pass-Stil. Genau einer muss gesetzt sein. Siehe Feldgruppen.
backgroundColor	string	Hintergrundfarbe, rgb(r, g, b).
foregroundColor	string	Vordergrundfarbe (Text), rgb(r, g, b).
labelColor	string	Farbe der Feldbeschriftung, rgb(r, g, b).
logoText	string	Text, der neben dem Logo angezeigt wird.
suppressStripShine	boolean	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	string	ISO 8601-Datum, an dem der Pass relevant wird.
maxDistance	integer	Maximale Entfernung (in Metern) für die Ortsrelevanz.
expirationDate	string	ISO 8601-Ablaufdatum.
voided	boolean	Markiert den Pass als ungültig.
groupingIdentifier	string	Gruppiert zusammengehörige Pässe (Veranstaltungstickets/Bordkarten).
userInfo	object (map)	Beliebige Schlüssel/Wert-App-Daten.

Hinweis

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

Feldgruppen-Objekt

Jeder Pass-Stil (boardingPass, coupon, eventTicket, storeCard, generic) gruppiert Felder in Bereiche:

Feld	Typ	Beschreibung
headerFields	array	Wird in der Kopfzeile des Passes angezeigt (sichtbar, wenn in Wallet gestapelt).
primaryFields	array	Die prominentesten Felder.
secondaryFields	array	Unterhalb der primären Felder.
auxiliaryFields	array	Zusätzliche Felder unterhalb der 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	string	Eindeutiger Feldschlüssel innerhalb des Passes.
label	string	Feldbeschriftung.
value	string	Feldwert (Text oder Zahl als Zeichenkette).
changeMessage	string	Nachricht, die angezeigt wird, wenn sich der Wert ändert (verwenden Sie %@ als Platzhalter).
textAlignment	string	PKTextAlignment-Wert.
dateStyle / timeStyle	string	PKDateStyle für Datums-/Zeitformatierung.
isRelative	boolean	Das Datum relativ zu jetzt anzeigen.
numberStyle	string	PKNumberStyle für Zahlenformatierung.
currencyCode	string	ISO 4217-Währungscode.
dataDetectorTypes	array of strings	Datendetektoren, die auf den Wert angewendet werden sollen.

Barcode-Objekt

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

Orts-Objekt

Feld	Typ	Beschreibung
latitude	number	Breitengrad.
longitude	number	Längengrad.
altitude	number	Höhe in Metern.
relevantText	string	Text, der auf dem Sperrbildschirm in der Nähe dieses Ortes angezeigt wird.

Beacon-Objekt

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

Pass-Bild-Objekt

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

Pass-Datensatz-Objekt

Wird von list/get-Endpunkten zurückgegeben.

Feld	Typ	Beschreibung
serialNumber	string	Seriennummer des Passes.
passTypeIdentifier	string	Pass Type ID.
organizationName	string	Organisationsname.
description	string	Pass-Beschreibung.
createdAt	string	Erstellungszeitstempel (RFC 3339).
updatedAt	string	Zeitstempel der letzten Aktualisierung (RFC 3339).
updateTag	integer	Aktuelles Update-Tag.
pass	object	Das vollständige Pass-Objekt zur Bearbeitung.
userId	string	Pushwoosh User ID, für die der Pass ausgestellt wurde.