# 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": "", "password": "password123" } \`\`\` **Response (200 OK):** \`\`\`json { "success": true, "user": { "id": "uuid", "email": "" }, "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": "", "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": "", "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 = '' 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 }) }) ````javascript 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 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://guestix.gitbook.io/guestix/home/documentation/getting-started/publish-your-docs.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.