Guest Service API Endpoints

This page provides the complete API reference for the Guest Service API.

OpenAPI Specification

The complete OpenAPI specification for the Guest Service API is available at openapi.yaml.

Common Workflows

Guest Authentication Flow

// Step 1: Initiate login with booking reference
const loginResponse = await fetch('/api/v1/guest/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    booking_reference: 'RB123456',
    last_name: 'Smith'
  })
});

const loginData = await loginResponse.json();

// Step 2: Verify with additional details if required
const verifyResponse = await fetch('/api/v1/guest/auth/verify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'guest@example.com',
    check_in_date: '2024-01-15'
  })
});

const { token } = await verifyResponse.json();

Service Request Flow

// Request housekeeping service
const serviceRequest = await fetch('/api/v1/guest/services/request', {
  method: 'POST',
  headers: { 
    'Authorization': `Bearer ${guestToken}`,
    'Content-Type': 'application/json' 
  },
  body: JSON.stringify({
    service_type: 'housekeeping',
    priority: 'normal',
    preferred_time: '14:00',
    special_instructions: 'Extra towels please',
    room_number: '205'
  })
});

const { request_id } = await serviceRequest.json();

// Track service request status
const statusResponse = await fetch(`/api/v1/guest/services/requests/${request_id}`, {
  headers: { 'Authorization': `Bearer ${guestToken}` }
});

Recommendations and Booking Flow

// Get personalized recommendations
const recommendations = await fetch('/api/v1/guest/recommendations?category=dining&time=evening', {
  headers: { 'Authorization': `Bearer ${guestToken}` }
});

const recsData = await recommendations.json();

// Book a recommended service
const booking = await fetch('/api/v1/guest/bookings', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${guestToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    service_id: 'spa_massage_001',
    preferred_date: '2024-01-16',
    preferred_time: '15:00',
    duration: 60,
    special_requests: 'Swedish massage'
  })
});

Real-time Communication

WebSocket Connection

const ws = new WebSocket('wss://guest.stayzr.com/ws');

ws.onopen = () => {
  // Authenticate WebSocket connection
  ws.send(JSON.stringify({ 
    type: 'auth', 
    token: guestToken 
  }));
};

ws.onmessage = (event) => {
  const update = JSON.parse(event.data);
  
  switch(update.type) {
    case 'service_status':
      updateServiceRequestStatus(update.data);
      break;
    case 'staff_message':
      displayNewMessage(update.data);
      break;
    case 'recommendation':
      showRecommendation(update.data);
      break;
    default:
      console.debug('Unhandled update:', update);
  }
};

ws.onclose = () => {
  // Implement reconnection with exponential backoff
  setTimeout(connectWebSocket, Math.min(1000 * Math.pow(2, retryCount), 30000));
};

Error Handling

The API uses consistent error response structures:

{
  "error": {
    "code": "BOOKING_NOT_FOUND",
    "message": "No active booking found for the provided reference",
    "suggestions": [
      "Verify booking reference spelling",
      "Contact hotel reception for assistance"
    ]
  }
}

Common Error Codes

• BOOKING_NOT_FOUND (404) - Invalid booking reference
• CHECKOUT_COMPLETED (410) - Guest already checked out
• SERVICE_UNAVAILABLE (503) - Requested service temporarily unavailable
• INVALID_TIME_SLOT (422) - Requested time not available
• RATE_LIMITED (429) - Too many requests from client
• AUTHENTICATION_REQUIRED (401) - Missing or invalid authentication
• INSUFFICIENT_PERMISSIONS (403) - Access denied for requested resource

Mobile App Integration

Deep Linking

• stayzr://checkin - Start the check-in flow
• stayzr://services - Open the services catalog
• stayzr://messages - Open guest–staff conversation
• stayzr://recommendations - View personalized recommendations
• stayzr://profile - Access guest profile and preferences

Push Notifications

Push notification categories:

• Service status updates
• Staff messages and replies
• Check-out reminders
• Personalized offers
• Emergency notifications

Include deep links in notification payloads to guide users to relevant screens.