Wallet Passes

Fragen Sie Wallet-Pass-Vorlagen ab, listen Sie Wallet Passes für Kunden auf, verifizieren Sie einen gescannten Pass und senden Sie Push-Benachrichtigungen an Wallet-Pass-Inhaber.

Vorlagen auflisten

Rufen Sie Wallet-Pass-Vorlagen für einen bestimmten Shop ab.

GET /v1/management/wallet-passes/templates

string

erforderlich

Der Shop-Bezeichner

Erforderliche Berechtigung: wallet_pass_template:read

Beispielanfrage

curl -X GET "https://api.rxscale.com/v1/management/wallet-passes/templates?shop_identifier=my-shop" \
  -H "X-API-Key: your-api-key-here"

Antwort

{
  "data": [
    {
      "uid": "wpt-abc123",
      "display_name": "Loyalty Card",
      "pass_type": "generic",
      "shop_identifier": "my-shop"
    }
  ],
  "total": 1
}

Wallet Passes auflisten

Rufen Sie Wallet Passes für eine bestimmte Shop-Kunden- und Shop-Kombination ab.

GET /v1/management/wallet-passes

string

erforderlich

Die Shop-Kunden-ID

string

erforderlich

Der Shop-Bezeichner

string

Optionale Vorlagen-UID zum Filtern

Erforderliche Berechtigung: wallet_pass:read

Beispielanfrage

curl -X GET "https://api.rxscale.com/v1/management/wallet-passes?shop_customer_id=cust-123&shop_identifier=my-shop" \
  -H "X-API-Key: your-api-key-here"

Antwort

{
  "data": [
    {
      "uid": "wp-abc123",
      "wallet_pass_template_uid": "wpt-abc123",
      "wallet_pass_template": {
        "uid": "wpt-abc123",
        "display_name": "Patient Pass",
        "external_id": "passcreator-template-id",
        "meta_data": {"template_type": "prescription", "version": "1.0"},
        "created_at": 1712100000,
        "updated_at": 1712100000,
        "deleted_at": null
      },
      "external_id": "passcreator-pass-id",
      "serial_number": "SER-000123",
      "ios_download_url": "https://pass.example/ios/wp-abc123",
      "android_download_url": "https://pass.example/android/wp-abc123",
      "patient_profile_uid": "pat-abc123",
      "created_at": 1712200000,
      "updated_at": 1712200000,
      "deleted_at": null
    }
  ],
  "total": 1
}

total ist die Anzahl der Pässe in data — dieser Endpoint gibt alle passenden Pässe in einer Antwort zurück und ist nicht paginiert, enthält also weder totalRegistries noch totalPages.

Das Wallet-Pass-Objekt

Feld	Typ	Beschreibung
`uid`	string	Wallet-Pass-UID. Dies ist der im Barcode kodierte Wert — behandeln Sie ihn wie ein Zugangsgeheimnis
`wallet_pass_template_uid`	string	UID der Vorlage, aus der der Pass ausgestellt wurde
`wallet_pass_template`	object	Die Vorlage, eingebettet
`external_id`	string \| null	Kennung des Passes beim Wallet-Pass-Anbieter
`serial_number`	string \| null	Seriennummer des ausgestellten Passes
`ios_download_url`	string \| null	Link, über den der Patient den Pass zu Apple Wallet hinzufügt
`android_download_url`	string \| null	Link, über den der Patient den Pass zu Google Wallet hinzufügt
`patient_profile_uid`	string	UID des Patienten, zu dem der Pass gehört
`created_at`	integer	Erstellungszeitpunkt (Unix-Sekunden)
`updated_at`	integer	Zeitpunkt der letzten Änderung (Unix-Sekunden)
`deleted_at`	integer \| null	Löschzeitpunkt (Unix-Sekunden), oder `null`, solange der Pass aktiv ist

Wallet-Pass erstellen

POST /v1/management/wallet-passes

Stellt einen Pass für einen Patienten aus einer Ihrer Vorlagen aus. Der Patient wird über Ihre eigene shop_customer_id zusammen mit dem shop_identifier identifiziert — Sie müssen also vorher keine RxScale-Patienten-UID auflösen. Erforderliche Berechtigung: wallet_pass:write

Anfragekörper

string

erforderlich

UID der Vorlage, aus der ausgestellt werden soll. Abrufbar über GET /wallet-passes/templates.

string

erforderlich

Ihre Kundenkennung für den Patienten

string

erforderlich

Der Shop, zu dem der Kunde gehört

Beispielanfrage

curl -X POST "https://api.rxscale.com/v1/management/wallet-passes" \
  -H "X-API-Key: ihr-api-schluessel" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_pass_template_uid": "wpt-abc123",
    "shop_customer_id": "cust-123",
    "shop_identifier": "my-shop"
  }'

Antwort

Gibt das Wallet-Pass-Objekt zurück.

Der Statuscode sagt Ihnen, ob ein Pass neu erstellt oder wiederverwendet wurde. Dieser Endpoint ist idempotent pro Patient und Vorlage: 201 bedeutet, dass ein neuer Pass ausgestellt wurde, 200 bedeutet, dass der Patient für diese Vorlage bereits einen Pass hatte und dieser aktualisiert und zurückgegeben wurde. Ein zweiter Aufruf gibt dem Patienten keine zwei Pässe.

{
  "uid": "wp-abc123",
  "wallet_pass_template_uid": "wpt-abc123",
  "external_id": "passcreator-pass-id",
  "serial_number": "SER-000123",
  "ios_download_url": "https://pass.example/ios/wp-abc123",
  "android_download_url": "https://pass.example/android/wp-abc123",
  "patient_profile_uid": "pat-abc123",
  "created_at": 1712200000,
  "updated_at": 1712200000,
  "deleted_at": null
}

Geben Sie ios_download_url bzw. android_download_url an den Patienten weiter, damit er den Pass zu seiner Wallet hinzufügen kann.

Fehlerantworten

Statuscode	Beschreibung
`400`	Fehlende oder ungültige Felder, oder die Vorlage erfordert ein signiertes Rezept und dieser Patient hat keines
`403`	Fehlende Berechtigung `wallet_pass:write`
`404`	Vorlage, Shop oder Patient nicht gefunden oder gehört zu einer anderen Organisation

Eine Vorlage, die ein signiertes Rezept erfordert, gibt eine spezifische Meldung zurück, damit Sie diesen Fall von einer fehlerhaften Anfrage unterscheiden können:

{
  "error": "The wallet pass template requires a signed prescription, but this patient has none."
}

Wallet-Pass abrufen

GET /v1/management/wallet-passes/{wallet_pass_uid}

Lädt einen einzelnen Pass über seine UID. Nützlich, um die Download-Links erneut zu lesen oder zu prüfen, ob ein Pass noch aktiv ist (deleted_at ist null). Erforderliche Berechtigung: wallet_pass:read

string

erforderlich

Die Wallet-Pass-UID

Beispielanfrage

curl -X GET "https://api.rxscale.com/v1/management/wallet-passes/wp-abc123" \
  -H "X-API-Key: ihr-api-schluessel"

Antwort

Gibt das Wallet-Pass-Objekt zurück.

Fehlerantworten

Statuscode	Beschreibung
`403`	Fehlende Berechtigung `wallet_pass:read`
`404`	Pass nicht gefunden oder gehört zu einer anderen Organisation

Wallet-Pass löschen

DELETE /v1/management/wallet-passes/{wallet_pass_uid}

Widerruft einen Pass. Der Pass wird weich gelöscht: Der Datensatz bleibt erhalten und deleted_at wird gesetzt, sodass das Scannen eines widerrufenen Passes weiterhin auflöst — POST /wallet-passes/verify antwortet dann mit "valid": false und "status": "revoked" statt mit einem 404. Erforderliche Berechtigung: wallet_pass:write

string

erforderlich

Die Wallet-Pass-UID

Beispielanfrage

curl -X DELETE "https://api.rxscale.com/v1/management/wallet-passes/wp-abc123" \
  -H "X-API-Key: ihr-api-schluessel"

Antwort

204 No Content mit leerem Körper.

Fehlerantworten

Statuscode	Beschreibung
`403`	Fehlende Berechtigung `wallet_pass:write`
`404`	Pass nicht gefunden oder gehört zu einer anderen Organisation

Gescannten Pass verifizieren

Ordnet einen gescannten Patient Pass shop-bezogenen Identitäts-Handles zu. Erfordert einen API-Schlüssel mit der Berechtigung wallet_pass:verify.

POST /v1/management/wallet-passes/verify

Erforderliche Berechtigung: wallet_pass:verify

Anfragekörper

string

erforderlich

Der Wert, der im Pass-Barcode kodiert ist. Behandeln Sie ihn wie ein Zugangsgeheimnis und senden Sie ihn im Body, niemals in einer URL.

Beispielanfrage

curl -X POST "https://api.rxscale.com/v1/management/wallet-passes/verify" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"wallet_pass_uid": "3f9a1c2e-7b04-4c11-9f3d-2a8e5b6c0d17"}'

Antwort (200)

{
  "valid": true,
  "status": "active",
  "wallet_pass_uid": "3f9a1c2e-7b04-4c11-9f3d-2a8e5b6c0d17",
  "patient_profile_uid": "b21d4f8a-5c33-4e90-8a72-1f6b9d0c4e55",
  "shop_customer_id": "cust-123"
}

Ein widerrufener Pass liefert "valid": false mit "status": "revoked". shop_customer_id fehlt bei Passes, die vor der Shop-Kunden-Anforderung ausgestellt wurden.

Behandeln Sie die wallet_pass_uid wie ein Zugangsgeheimnis — wer sie besitzt, kann die dahinterstehende Patientin oder den Patienten ermitteln. Senden Sie sie im Request-Body, niemals in einer URL, und schreiben Sie sie nicht in Logs.

Dieser Endpoint liefert ausschliesslich Identitäts-Handles. Die Details der Patientin oder des Patienten laden Sie über GET /v1/management/patients.

Fehlerantworten

Statuscode	Beschreibung
`400`	Fehlende `wallet_pass_uid`
`403`	Fehlende Berechtigung `wallet_pass:verify`
`404`	Unbekannter Pass oder ein Pass einer anderen Organisation

Push-Benachrichtigungen senden

Senden Sie Push-Benachrichtigungen an einen oder mehrere Wallet-Pass-Inhaber. Akzeptiert einen Stapel von Benachrichtigungen.

POST /v1/management/wallet-passes/push-notifications

Erforderliche Berechtigung: wallet_pass_push_notification:write

Anfragekörper

Der Anfragekörper ist ein JSON-Array von Benachrichtigungsobjekten.

[
  {
    "wallet_pass_uid": "wp-abc123",
    "message": "Your prescription is ready for pickup!"
  },
  {
    "wallet_pass_uid": "wp-def456",
    "message": "Hello {first_name}, your order has been shipped."
  }
]

Feld	Typ	Erforderlich	Beschreibung
`wallet_pass_uid`	string	Ja	UID des Wallet Passes, an den die Benachrichtigung gesendet werden soll
`message`	string	Ja	Text der Push-Benachrichtigung (unterstützt `{field}`-Platzhalter)

Beispielanfrage

curl -X POST "https://api.rxscale.com/v1/management/wallet-passes/push-notifications" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "wallet_pass_uid": "wp-abc123",
      "message": "Your prescription is ready for pickup!"
    }
  ]'

Antwort (201 Created)

{
  "data": [
    {
      "uid": "wpn-abc123",
      "wallet_pass_uid": "wp-abc123",
      "message": "Your prescription is ready for pickup!",
      "status": "queued"
    }
  ],
  "total": 1
}

Fehlerantworten

Statuscode	Beschreibung
`400`	Ungültiges Body-Format, leeres Array, Validierungsfehler oder Wallet Pass nicht gefunden
`403`	Fehlende Berechtigung `wallet_pass_push_notification:write`

​Wallet Passes

​Vorlagen auflisten

​Beispielanfrage

​Antwort

​Wallet Passes auflisten

​Beispielanfrage

​Antwort

​Das Wallet-Pass-Objekt

​Wallet-Pass erstellen

​Anfragekörper

​Beispielanfrage

​Antwort

​Fehlerantworten

​Wallet-Pass abrufen

​Beispielanfrage

​Antwort

​Fehlerantworten

​Wallet-Pass löschen

​Beispielanfrage

​Antwort

​Fehlerantworten

​Gescannten Pass verifizieren

​Anfragekörper

​Beispielanfrage

​Antwort (200)

​Fehlerantworten

​Push-Benachrichtigungen senden

​Anfragekörper

​Beispielanfrage

​Antwort (201 Created)

​Fehlerantworten

Wallet Passes

Vorlagen auflisten

Beispielanfrage

Antwort

Wallet Passes auflisten

Beispielanfrage

Antwort

Das Wallet-Pass-Objekt

Wallet-Pass erstellen

Anfragekörper

Beispielanfrage

Antwort

Fehlerantworten

Wallet-Pass abrufen

Beispielanfrage

Antwort

Fehlerantworten

Wallet-Pass löschen

Beispielanfrage

Antwort

Fehlerantworten

Gescannten Pass verifizieren

Anfragekörper

Beispielanfrage

Antwort (200)

Fehlerantworten

Push-Benachrichtigungen senden

Anfragekörper

Beispielanfrage

Antwort (201 Created)

Fehlerantworten