# Migration Guide: From QR Codes to Digital Wallet Ticketing

## Purpose

This guide explains how to migrate from the legacy QR code–based ticketing system
to the new digital wallet–based ticketing solution using wallet passes (`.pkpass`).

It is intended for developers integrating with the Museum API and focuses on
practical, step-by-step changes required in existing implementations.

## Background

The previous ticketing flow relied on QR codes generated from ticket identifiers
and displayed inside applications or emails.

The new approach replaces QR codes with digital wallet passes, which are
stored natively in Apple Wallet or Google Wallet and generated by the backend.

## Old vs New Ticketing Model

### Legacy QR Code Model

- QR code generated client-side or embedded in emails
- Ticket presented as an image
- User had to open the app or email
- Higher risk of reuse (screenshots)
- Online access often required


### Digital Wallet Ticketing Model

- Ticket generated server-side
- Wallet-native pass (`.pkpass`)
- Stored directly in the device wallet
- Signed and tamper-resistant
- Works offline


## What Remains the Same

The following parts of the integration do not change:

- Ticket purchase flow
- POST /tickets endpoint
- Ticket identifiers (`ticketId`)
- Event and admission logic
- Entry validation based on `ticketId`


## What Changes

The following elements must be updated:

- QR code generation logic must be removed
- QR code rendering in UI must be removed
- New endpoint must be integrated to retrieve wallet passes
- UI flow should guide users to add tickets to their wallet


## Step-by-Step Migration

### Step 1: Purchase Tickets (Unchanged)

Tickets are still purchased using the same endpoint:

POST /tickets

Example request body:

{
"ticketType": "event",
"eventId": "dad4bce8-f5cb-4078-a211-995864315e39",
"ticketDate": "2023-09-05",
"email": "user@example.com"
}

Example response:

{
"ticketId": "b811f723-17b2-44f7-8952-24b03e43d8a9",
"confirmationCode": "ticket-event-9c55eg-8v82a"
}

The ticketId is required for all subsequent steps.

### Step 2: Remove QR Code Logic

Remove any functionality that:

- Generates QR codes from ticketId
- Displays QR images in the UI
- Sends QR codes via email
- Relies on QR screenshots for entry


QR codes are no longer required in the new system.

### Step 3: Fetch the Digital Wallet Pass

Use the new endpoint to retrieve the wallet ticket:

GET /tickets/{ticketId}/pkpass

Example request:

GET /tickets/b811f723-17b2-44f7-8952-24b03e43d8a9/pkpass

The response contains a wallet-compatible ticket pass with:

- Event or admission name
- Date and time
- Ticket ID
- Embedded wallet barcode


## UI Recommendations

- Replace “Show QR Code” with “Add to Wallet”
- Display Apple Wallet / Google Wallet branding
- Provide guidance for unsupported devices


## Backward Compatibility

If required, QR code tickets may remain valid during a transition period.
However, all new integrations should default to digital wallet ticketing.

## Migration Checklist

- Remove QR code generation
- Integrate /tickets/{ticketId}/pkpass endpoint
- Update frontend UI
- Test offline access
- Validate entry scanning


## Summary

Digital wallet ticketing provides a more secure, reliable, and user-friendly
experience. Migrating from QR codes simplifies entry validation and improves
overall ticket lifecycle management.