Scanner API

Base URL: https://www.guestix.app/api

Authentication

Login

POST /auth/login

Authenticate a user and receive access tokens.

Request Body: ```json { "email": "[e-mail]", "password": "password123" } ```

Response (200 OK): ```json { "success": true, "user": { "id": "uuid", "email": "[e-mail]" }, "session": { "access_token": "eyJhbGc...", "refresh_token": "eyJhbGc...", "expires_at": 1234567890 } } ```

Error Responses:

• 400 Bad Request - Missing email or password

• 401 Unauthorized - Invalid credentials

---

Refresh Token

POST /auth/refresh

Refresh an expired access token.

Request Body: ```json { "refresh_token": "eyJhbGc..." } ```

Response (200 OK): ```json { "success": true, "session": { "access_token": "eyJhbGc...", "refresh_token": "eyJhbGc...", "expires_at": 1234567890 } } ```

---

Scanner Endpoints

All scanner endpoints require authentication. Include the access token in the Authorization header: ``` Authorization: Bearer {access_token} ```

Get Events

GET /scanner/events

Get all events accessible to the authenticated user.

Response (200 OK): ```json { "events": [ { "id": "uuid", "name": "Summer Festival 2024", "event_date": "2024-07-15T18:00:00Z", "location": "Central Park", "description": "Annual summer festival" } ] } ```

---

Validate Token

POST /scanner/validate

Validate a QR code token and get guest/companion information.

Request Body: ```json { "token": "abc12345", "event_id": "uuid" // optional - validates token belongs to this event } ```

Response (200 OK) - Guest: ```json { "valid": true, "type": "guest", "data": { "id": "uuid", "name": "John Doe", "email": "[e-mail]", "checked_in": false, "checked_in_at": null, "event_id": "uuid", "category": { "name": "VIP", "color": "#FFD700" } } } ```

Response (200 OK) - Companion: ```json { "valid": true, "type": "companion", "data": { "id": "uuid", "name": "Jane Smith", "email": "[e-mail]", "checked_in": true, "checked_in_at": "2024-07-15T19:30:00Z", "guest_name": "John Doe" } } ```

Error Responses:

• 400 Bad Request - Token belongs to different event

• 404 Not Found - Invalid token

---

Check-in

POST /scanner/checkin

Toggle check-in status for a guest or companion.

Request Body: ```json { "token": "abc12345", "event_id": "uuid" // optional - validates token belongs to this event } ```

Response (200 OK) - Guest: ```json { "success": true, "type": "guest", "data": { "id": "uuid", "name": "John Doe", "checked_in": true, "checked_in_at": "2024-07-15T19:30:00Z", "category": { "name": "VIP", "color": "#FFD700" } }, "message": "Checked in successfully" } ```

Response (200 OK) - Companion: ```json { "success": true, "type": "companion", "data": { "id": "uuid", "name": "Jane Smith", "checked_in": false, "checked_in_at": null, "guest_name": "John Doe" }, "message": "Checked out successfully" } ```

Error Responses:

• 400 Bad Request - Token belongs to different event

• 404 Not Found - Invalid token

• 500 Internal Server Error - Failed to update check-in status

---

Get Event Statistics

GET /scanner/stats?event_id={uuid}

Get real-time statistics for an event.

Query Parameters:

• event_id (required) - UUID of the event

Response (200 OK): ```json { "event": { "id": "uuid", "name": "Summer Festival 2024", "event_date": "2024-07-15T18:00:00Z", "max_capacity": 500 }, "stats": { "guests": { "total": 250, "checked_in": 180, "pending": 70 }, "companions": { "total": 100, "checked_in": 75, "pending": 25 }, "overall": { "total": 350, "checked_in": 255, "pending": 95 } } } ```

Error Responses:

• 400 Bad Request - Missing event_id

• 404 Not Found - Event not found

---

Error Handling

All endpoints return errors in the following format:

```json { "error": "Error message description" } ```

Common HTTP status codes:

• 200 OK - Request successful

• 400 Bad Request - Invalid request parameters

• 401 Unauthorized - Authentication required or failed

• 404 Not Found - Resource not found

• 500 Internal Server Error - Server error

---

Rate Limiting

Currently no rate limiting is implemented. Consider implementing rate limiting for production use.

---

Mobile App Integration Example

```typescript // Example: React Native / Expo integration

class ScannerAPI { private baseUrl = 'https://your-domain.com/api' private accessToken: string | null = null

async login(email: string, password: string) { const response = await fetch(${this.baseUrl}/auth/login, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ email, password }) })

const data = await response.json()
if (data.success) {
  this.accessToken = data.session.access_token
  // Store refresh_token securely
}
return data
}

async getEvents() { 
  const response = await fetch(${this.baseUrl}/scanner/events, { headers: { 'Authorization': Bearer ${this.accessToken} } }) 
  return response.json() 
}

async validateToken(token: string, eventId?: string) { const response = await fetch(${this.baseUrl}/scanner/validate, { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': Bearer ${this.accessToken} }, body: JSON.stringify({ token, event_id: eventId }) }) return response.json() }

async checkin(token: string, eventId?: string) { const response = await fetch(${this.baseUrl}/scanner/checkin, { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': Bearer ${this.accessToken} }, body: JSON.stringify({ token, event_id: eventId }) }) return response.json() }

async getStats(eventId: string) { const response = await fetch( ${this.baseUrl}/scanner/stats?event_id=${eventId}, { headers: { 'Authorization': Bearer ${this.accessToken} } } ) return response.json() } } ```

---

Security Considerations

1. HTTPS Only: Always use HTTPS in production

2. Token Storage: Store access and refresh tokens securely (e.g., secure storage on mobile)

3. Token Expiration: Implement automatic token refresh before expiration

4. Input Validation: All inputs are validated on the server

5. Rate Limiting: Consider implementing rate limiting for production

6. CORS: Configure CORS appropriately for your mobile app domain