🔌 API Documentation

Complete REST API reference for Innkeeper

📋 Overview

Innkeeper provides a comprehensive RESTful API that allows you to integrate with external systems, build custom applications, and automate hotel operations. The API follows REST principles and returns JSON responses.

Base URL: https://your-domain.com/api
API Version: v1
Authentication: Bearer Token (JWT)

🔐 Authentication

Obtaining Access Token

POST /api/auth/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "your-password"
}

Response:

{
  "success": true,
  "data": {
    "user": {
      "id": 1,
      "email": "[email protected]",
      "full_name": "John Doe"
    },
    "token": {
      "type": "Bearer",
      "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
      "expires_at": "2024-02-01T12:00:00.000Z"
    }
  }
}

Using the Token

Include the token in the Authorization header for all API requests:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

🏨 Hotels API

List Hotels

GET /api/hotels

Query Parameters:

page (integer): Page number (default: 1)
limit (integer): Items per page (default: 20, max: 100)
search (string): Search by name or city
is_active (boolean): Filter by active status

Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Grand Plaza Hotel",
      "slug": "grand-plaza",
      "city": "New York",
      "country": "United States",
      "star_rating": 4,
      "total_rooms": 150,
      "is_active": true,
      "created_at": "2024-01-01T00:00:00.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "per_page": 20,
    "current_page": 1,
    "last_page": 1
  }
}

Get Hotel Details

GET /api/hotels/{id}

Response:

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Grand Plaza Hotel",
    "slug": "grand-plaza",
    "description": "A luxury hotel in the heart of the city",
    "email": "[email protected]",
    "phone": "+1 (555) 123-4567",
    "address": "123 Main Street",
    "city": "New York",
    "state": "NY",
    "country": "United States",
    "postal_code": "10001",
    "latitude": 40.7128,
    "longitude": -74.0060,
    "star_rating": 4,
    "total_rooms": 150,
    "check_in_time": "15:00",
    "check_out_time": "11:00",
    "policies": {
      "cancellation_policy": "Free cancellation up to 24 hours before check-in",
      "pet_policy": "Pets allowed with additional fee"
    },
    "amenities": [
      {
        "id": 1,
        "name": "WiFi",
        "icon": "wifi"
      },
      {
        "id": 2,
        "name": "Swimming Pool",
        "icon": "pool"
      }
    ],
    "created_at": "2024-01-01T00:00:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z"
  }
}

Create Hotel

POST /api/hotels
Content-Type: application/json

{
  "name": "Seaside Resort",
  "slug": "seaside-resort",
  "description": "Beautiful beachfront resort",
  "email": "[email protected]",
  "phone": "+1 (555) 987-6543",
  "address": "456 Ocean Drive",
  "city": "Miami",
  "state": "FL",
  "country": "United States",
  "postal_code": "33139",
  "star_rating": 5,
  "check_in_time": "16:00",
  "check_out_time": "12:00"
}

🛏️ Rooms API

List Rooms

GET /api/hotels/{hotel_id}/rooms

Query Parameters:

status (string): Filter by room status (available, occupied, maintenance, dirty, clean)
room_type_id (integer): Filter by room type
floor (string): Filter by floor

Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "room_number": "101",
      "floor": "1",
      "status": "available",
      "housekeeping_status": "clean",
      "room_type": {
        "id": 1,
        "name": "Standard King Room",
        "max_occupancy": 2,
        "base_price": 150.00
      },
      "last_cleaned_at": "2024-01-15T08:00:00.000Z"
    }
  ]
}

Update Room Status

PATCH /api/rooms/{id}/status
Content-Type: application/json

{
  "status": "maintenance",
  "housekeeping_status": "out_of_order",
  "notes": "Air conditioning repair needed"
}

👥 Guests API

List Guests

GET /api/guests

Query Parameters:

search (string): Search by name, email, or phone
vip_status (string): Filter by VIP status
is_blacklisted (boolean): Filter blacklisted guests

Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "first_name": "Alice",
      "last_name": "Smith",
      "email": "[email protected]",
      "phone": "+1 (555) 987-6543",
      "nationality": "United States",
      "vip_status": "gold",
      "loyalty_points": 1250,
      "total_stays": 5,
      "total_spent": 2500.00,
      "last_stay_date": "2024-01-10T00:00:00.000Z"
    }
  ]
}

Create Guest

POST /api/guests
Content-Type: application/json

{
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "phone": "+1 (555) 123-4567",
  "date_of_birth": "1985-06-15",
  "nationality": "United States",
  "document_type": "passport",
  "document_number": "AB123456",
  "address": "789 Elm Street",
  "city": "Boston",
  "state": "MA",
  "country": "United States",
  "postal_code": "02101"
}

🎫 Reservations API

List Reservations

GET /api/reservations

Query Parameters:

status (string): Filter by status (confirmed, checked_in, checked_out, cancelled)
check_in_date (date): Filter by check-in date
check_out_date (date): Filter by check-out date
guest_id (integer): Filter by guest
hotel_id (integer): Filter by hotel

Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "confirmation_number": "RES-2024-001",
      "status": "confirmed",
      "check_in_date": "2024-02-01",
      "check_out_date": "2024-02-03",
      "adults": 2,
      "children": 0,
      "room_rate": 150.00,
      "total_amount": 300.00,
      "guest": {
        "id": 1,
        "first_name": "Alice",
        "last_name": "Smith",
        "email": "[email protected]"
      },
      "room": {
        "id": 1,
        "room_number": "101",
        "room_type": {
          "name": "Standard King Room"
        }
      },
      "created_at": "2024-01-15T10:00:00.000Z"
    }
  ]
}

Create Reservation

POST /api/reservations
Content-Type: application/json

{
  "guest_id": 1,
  "hotel_id": 1,
  "room_type_id": 1,
  "check_in_date": "2024-02-15",
  "check_out_date": "2024-02-17",
  "adults": 2,
  "children": 1,
  "room_rate": 175.00,
  "special_requests": "Late check-in requested",
  "guest_details": {
    "arrival_time": "22:00",
    "purpose_of_visit": "leisure"
  }
}

Response:

{
  "success": true,
  "data": {
    "id": 2,
    "confirmation_number": "RES-2024-002",
    "status": "confirmed",
    "check_in_date": "2024-02-15",
    "check_out_date": "2024-02-17",
    "total_amount": 350.00,
    "room": {
      "id": 5,
      "room_number": "205"
    }
  }
}

Check-in Guest

POST /api/reservations/{id}/checkin
Content-Type: application/json

{
  "room_id": 5,
  "actual_check_in": "2024-02-15T16:30:00.000Z",
  "notes": "Guest arrived early, room was ready"
}

Check-out Guest

POST /api/reservations/{id}/checkout
Content-Type: application/json

{
  "actual_check_out": "2024-02-17T11:15:00.000Z",
  "final_charges": [
    {
      "description": "Mini bar",
      "amount": 25.00
    }
  ]
}

💳 Payments API

List Payments

GET /api/payments

Query Parameters:

reservation_id (integer): Filter by reservation
status (string): Filter by payment status
method (string): Filter by payment method

Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "transaction_id": "TXN-2024-001",
      "type": "payment",
      "method": "credit_card",
      "status": "completed",
      "amount": 300.00,
      "currency": "USD",
      "card_last_four": "1234",
      "card_brand": "visa",
      "paid_at": "2024-01-15T14:30:00.000Z",
      "reservation": {
        "id": 1,
        "confirmation_number": "RES-2024-001"
      }
    }
  ]
}

Process Payment

POST /api/payments
Content-Type: application/json

{
  "reservation_id": 1,
  "amount": 300.00,
  "method": "credit_card",
  "payment_details": {
    "card_number": "4111111111111111",
    "expiry_month": "12",
    "expiry_year": "2025",
    "cvv": "123",
    "cardholder_name": "Alice Smith"
  }
}

📊 Reports API

Occupancy Report

GET /api/reports/occupancy

Query Parameters:

hotel_id (integer): Specific hotel (optional)
start_date (date): Report start date
end_date (date): Report end date
group_by (string): Group by day, week, or month

Response:

{
  "success": true,
  "data": {
    "summary": {
      "total_rooms": 150,
      "average_occupancy": 75.5,
      "total_revenue": 45000.00
    },
    "daily_data": [
      {
        "date": "2024-01-15",
        "occupied_rooms": 120,
        "available_rooms": 30,
        "occupancy_rate": 80.0,
        "revenue": 18000.00
      }
    ]
  }
}

Revenue Report

GET /api/reports/revenue

Response:

{
  "success": true,
  "data": {
    "total_revenue": 125000.00,
    "room_revenue": 100000.00,
    "service_revenue": 25000.00,
    "breakdown": {
      "by_hotel": [
        {
          "hotel_id": 1,
          "hotel_name": "Grand Plaza Hotel",
          "revenue": 125000.00
        }
      ],
      "by_month": [
        {
          "month": "2024-01",
          "revenue": 125000.00
        }
      ]
    }
  }
}

🔍 Search API

Global Search

GET /api/search

Query Parameters:

q (string): Search query
type (string): Search type (guests, reservations, rooms)
limit (integer): Maximum results

Response:

{
  "success": true,
  "data": {
    "guests": [
      {
        "id": 1,
        "name": "Alice Smith",
        "email": "[email protected]",
        "type": "guest"
      }
    ],
    "reservations": [
      {
        "id": 1,
        "confirmation_number": "RES-2024-001",
        "guest_name": "Alice Smith",
        "type": "reservation"
      }
    ],
    "rooms": []
  }
}

📅 Availability API

Check Room Availability

GET /api/availability

Query Parameters:

hotel_id (integer): Hotel ID
check_in (date): Check-in date
check_out (date): Check-out date
adults (integer): Number of adults
children (integer): Number of children

Response:

{
  "success": true,
  "data": [
    {
      "room_type_id": 1,
      "room_type_name": "Standard King Room",
      "available_rooms": 5,
      "base_price": 150.00,
      "total_price": 300.00,
      "amenities": [
        "WiFi",
        "Air Conditioning",
        "TV"
      ]
    },
    {
      "room_type_id": 2,
      "room_type_name": "Deluxe Suite",
      "available_rooms": 2,
      "base_price": 300.00,
      "total_price": 600.00,
      "amenities": [
        "WiFi",
        "Kitchenette",
        "Balcony"
      ]
    }
  ]
}

🔔 Webhooks

Webhook Events

Innkeeper can send webhook notifications for various events:

reservation.created
reservation.updated
reservation.cancelled
guest.checked_in
guest.checked_out
payment.completed
payment.failed

Webhook Payload Example

{
  "event": "reservation.created",
  "timestamp": "2024-01-15T10:00:00.000Z",
  "data": {
    "reservation": {
      "id": 1,
      "confirmation_number": "RES-2024-001",
      "status": "confirmed",
      "guest": {
        "id": 1,
        "name": "Alice Smith",
        "email": "[email protected]"
      }
    }
  }
}

Configuring Webhooks

POST /api/webhooks
Content-Type: application/json

{
  "url": "https://your-app.com/webhooks/innkeeper",
  "events": ["reservation.created", "payment.completed"],
  "secret": "your-webhook-secret"
}

📝 Error Handling

Error Response Format

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The given data was invalid.",
    "details": {
      "email": [
        "The email field is required."
      ],
      "phone": [
        "The phone format is invalid."
      ]
    }
  }
}

HTTP Status Codes

Code	Description
`200`	Success
`201`	Created
`400`	Bad Request
`401`	Unauthorized
`403`	Forbidden
`404`	Not Found
`422`	Validation Error
`429`	Rate Limit Exceeded
`500`	Internal Server Error

🚀 Rate Limiting

API requests are rate-limited to prevent abuse:

Authenticated requests: 1000 requests per hour
Authentication endpoints: 10 requests per minute
Search endpoints: 100 requests per hour

Rate limit headers are included in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642248000

🔧 SDKs and Libraries

Official SDKs

JavaScript/Node.js: npm install @innkeeper/sdk-js
PHP: composer require innkeeper/sdk-php
Python: pip install innkeeper-sdk

JavaScript SDK Example

import {InnkeeperClient} from '@innkeeper/sdk-js';

const client = new InnkeeperClient({
  baseUrl: 'https://your-domain.com/api',
  token: 'your-api-token'
});

// List hotels
const hotels = await client.hotels.list();

// Create reservation
const reservation = await client.reservations.create({
  guest_id: 1,
  hotel_id: 1,
  check_in_date: '2024-02-15',
  check_out_date: '2024-02-17'
});

📚 Related Documentation

Authentication Guide - Detailed authentication setup
System Architecture - API architecture overview
Database Schema - Data structure reference
Webhook Guide - Webhook implementation

🆘 Need Help?

📖 Documentation: Wiki Home
🐛 Issues: GitHub Issues
💬 Community: GitHub Discussions
📧 Support: Contact the development team

← Previous: Database Schema | Wiki Home | Next: Hotel Management →

API Documentation - gabrielmaialva33/innkeeper GitHub Wiki

🔌 API Documentation

📋 Overview

🔐 Authentication

Obtaining Access Token

Using the Token

🏨 Hotels API

List Hotels

Get Hotel Details

Create Hotel

🛏️ Rooms API

List Rooms

Update Room Status

👥 Guests API

List Guests

Create Guest

🎫 Reservations API

List Reservations

Create Reservation

Check-in Guest

Check-out Guest

💳 Payments API

List Payments

Process Payment

📊 Reports API

Occupancy Report

Revenue Report

🔍 Search API

Global Search

📅 Availability API

Check Room Availability

🔔 Webhooks

Webhook Events

Webhook Payload Example

Configuring Webhooks

📝 Error Handling

Error Response Format

HTTP Status Codes

🚀 Rate Limiting

🔧 SDKs and Libraries

Official SDKs

JavaScript SDK Example

📚 Related Documentation

🆘 Need Help?

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️