Hotel Admin API Endpoints

This page provides the complete API reference for the Hotel Admin API.

OpenAPI Specification

The complete OpenAPI specification for the Hotel Admin API is available at openapi.yaml.

Common Administrative Workflows

Hotel Setup and Configuration

// Get hotel information and settings
const hotelResponse = await fetch('/api/v1/admin/hotels/current', {
  headers: { 'Authorization': `Bearer ${adminToken}` }
});

const hotelData = await hotelResponse.json();

// Update hotel configuration
const configUpdate = await fetch('/api/v1/admin/hotels/current/settings', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${adminToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    check_in_time: '15:00',
    check_out_time: '11:00',
    cancellation_policy: '24_hours',
    amenities: ['wifi', 'parking', 'gym', 'pool']
  })
});

Guest Management Operations

// List recent guest check-ins
const guestsResponse = await fetch('/api/v1/admin/guests?status=checked_in&sort=check_in_date:desc&limit=50', {
  headers: { 'Authorization': `Bearer ${adminToken}` }
});

const { data: guests, pagination } = await guestsResponse.json();

// Update guest information
const guestUpdate = await fetch(`/api/v1/admin/guests/${guestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${adminToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    special_requests: 'Late checkout approved until 2 PM',
    vip_status: true,
    preferences: {
      room_temperature: 22,
      pillow_type: 'firm',
      dietary_restrictions: ['vegetarian']
    }
  })
});

Room Management

// Get room inventory and status
const roomsResponse = await fetch('/api/v1/admin/rooms?include=current_guest,maintenance_status', {
  headers: { 'Authorization': `Bearer ${adminToken}` }
});

const rooms = await roomsResponse.json();

// Update room status
const roomStatusUpdate = await fetch('/api/v1/admin/rooms/101', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${adminToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    status: 'maintenance',
    maintenance_notes: 'AC unit repair scheduled for tomorrow',
    estimated_ready_time: '2024-01-16T14:00:00Z'
  })
});

Service Request Management

// Get all pending service requests
const serviceRequests = await fetch('/api/v1/admin/service-requests?status=pending&priority=high', {
  headers: { 'Authorization': `Bearer ${adminToken}` }
});

// Assign service request to staff member
const assignmentUpdate = await fetch(`/api/v1/admin/service-requests/${requestId}/assign`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${adminToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    staff_member_id: 'staff_456',
    estimated_completion: '2024-01-15T16:30:00Z',
    notes: 'Assigned to senior maintenance technician'
  })
});

Analytics and Reporting

// Get revenue analytics for the last 30 days
const revenueAnalytics = await fetch('/api/v1/admin/analytics/revenue?period=last_30_days&breakdown=daily', {
  headers: { 'Authorization': `Bearer ${adminToken}` }
});

const { 
  total_revenue, 
  bookings_count, 
  average_stay_value, 
  daily_breakdown 
} = await revenueAnalytics.json();

// Get occupancy metrics
const occupancyMetrics = await fetch('/api/v1/admin/analytics/occupancy?period=current_month', {
  headers: { 'Authorization': `Bearer ${adminToken}` }
});

// Get guest satisfaction scores
const satisfactionData = await fetch('/api/v1/admin/analytics/satisfaction?period=last_quarter', {
  headers: { 'Authorization': `Bearer ${adminToken}` }
});

Staff Management

// List all hotel staff
const staffResponse = await fetch('/api/v1/admin/staff?include=permissions,recent_activity', {
  headers: { 'Authorization': `Bearer ${adminToken}` }
});

// Create new staff member
const newStaff = await fetch('/api/v1/admin/staff', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${adminToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'new.staff@hotel.com',
    first_name: 'John',
    last_name: 'Smith',
    role: 'housekeeping_staff',
    departments: ['housekeeping'],
    shift_schedule: 'morning',
    permissions: ['view_guest_requests', 'update_room_status']
  })
});

Bulk Operations

Batch Room Updates

// Update multiple room statuses
const bulkRoomUpdate = await fetch('/api/v1/admin/rooms/bulk-update', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${adminToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    updates: [
      { room_id: '101', status: 'clean', ready_for_guests: true },
      { room_id: '102', status: 'dirty', needs_housekeeping: true },
      { room_id: '103', status: 'maintenance', issue_description: 'Leaky faucet' }
    ]
  })
});

Bulk Service Request Management

// Process multiple service requests
const bulkServiceUpdate = await fetch('/api/v1/admin/service-requests/bulk-action', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${adminToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    action: 'assign',
    request_ids: ['req_123', 'req_124', 'req_125'],
    staff_member_id: 'staff_789',
    priority: 'normal'
  })
});

Real-time Updates

WebSocket Connection for Admin Dashboard

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

adminWs.onopen = () => {
  // Authenticate and subscribe to hotel events
  adminWs.send(JSON.stringify({
    type: 'auth',
    token: adminToken,
    subscriptions: [
      'room_status_changes',
      'new_service_requests', 
      'guest_checkins',
      'urgent_notifications'
    ]
  }));
};

adminWs.onmessage = (event) => {
  const update = JSON.parse(event.data);
  
  switch(update.type) {
    case 'room_status_change':
      updateRoomDisplay(update.data);
      break;
    case 'new_service_request':
      addServiceRequestToQueue(update.data);
      break;
    case 'guest_checkin':
      updateGuestList(update.data);
      break;
    case 'urgent_alert':
      showUrgentNotification(update.data);
      break;
  }
};

Error Handling

Administrative API error responses follow a consistent structure:

{
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "You don't have permission to access this resource",
    "timestamp": "2024-01-15T10:30:00Z",
    "request_id": "req_abc123",
    "suggestions": [
      "Contact your hotel administrator for access",
      "Verify your role permissions"
    ]
  }
}

Common Administrative Error Codes

• INSUFFICIENT_PERMISSIONS (403) - User lacks required permissions
• HOTEL_NOT_FOUND (404) - Invalid hotel identifier
• RESOURCE_CONFLICT (409) - Resource is in use or has conflicts
• VALIDATION_ERROR (422) - Request data validation failed
• RATE_LIMIT_EXCEEDED (429) - Too many requests
• SUBSCRIPTION_LIMIT_REACHED (402) - Feature not available in current plan
• MAINTENANCE_MODE (503) - System temporarily unavailable