Table of Contents

Getting Started

This guide will help you get started with the PMS Web API. You'll learn how to obtain authentication tokens, make your first API calls, and begin integrating with the system.

Obtaining Your API Token

Before you can start using the PMS Web API, you need to obtain an authentication token from your system administrator. API tokens are service-specific and provide access based on configured permissions. These tokens are designed for third-party applications and integrations that need to interact with specific API endpoints.

To obtain an API token, you'll need to contact your system administrator and provide the following information: your service name, a description of your integration, and the specific operations you need to perform. The administrator will create an external service record in the system and provide you with a unique token that's associated with your service. This token will have permissions configured based on your integration requirements.

Once you receive your token, it's crucial to store it securely. Never commit tokens to version control systems, expose them in client-side code, or share them publicly. Treat your API token with the same level of security as you would a password. If you suspect your token has been compromised, contact your administrator immediately to have it revoked and a new one issued.

Making Your First API Call

After receiving your token, you can start making API requests. All API requests require authentication using the Bearer token scheme. You'll include your token in the Authorization header of every HTTP request in the format: Authorization: Bearer <your-token>. The API base URL depends on your deployment environment, and your administrator will provide you with the correct endpoint address.

The easiest way to test the API and explore available endpoints is through the Swagger UI interface. To access Swagger, navigate to {base-url}/swagger?token={your-token} in your web browser. The Swagger UI provides an interactive interface where you can view all available endpoints, see request and response schemas, and test API calls directly from your browser. When you use Swagger with a token in the URL, the token is automatically included in all API requests, making it easy to test different endpoints without manually setting headers.

For programmatic access, you can use any HTTP client library in your preferred programming language. Here's a simple example using cURL to make a GET request to retrieve available operations:

curl -X GET "https://api.example.com/api/external-operations" \
  -H "Authorization: Bearer your-token-here" \
  -H "Content-Type: application/json"

If you're using a programming language like C#, Python, or JavaScript, you'll set the Authorization header in your HTTP client. For example, in C# using HttpClient:

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = 
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "your-token-here");
var response = await client.GetAsync("https://api.example.com/api/external-operations");

Understanding Access Permissions

It's important to understand that your API token has permissions based on how it's configured by your system administrator. Your token may have restrictions on which operations you can perform, which hotels you can access, or which endpoints are available to you. If you receive a 403 Forbidden response when making an API call, it means your token doesn't have permission to access that particular resource or operation.

To check what operations are available to your service, you can call the /api/external-operations endpoint, which returns a list of all operations your service is authorized to use. This helps you understand the scope of your integration and identify any permissions that may need to be adjusted. If you need additional permissions, contact your system administrator and explain the specific operations or resources you need to access.

Next Steps

Once you've successfully made your first API call, you're ready to start building your integration. Review the API documentation to understand the available endpoints, request formats, and response structures. Pay special attention to the data models and validation requirements, as incorrect request formats will result in 400 Bad Request errors.

If your integration requires real-time event notifications, consider setting up webhooks. Webhooks allow the system to push event data to your application instead of requiring you to poll for changes. You can configure webhooks through the API using the /api/webhooks endpoint. For detailed information about webhook configuration, see the Webhook Configuration and Usage guide.

For troubleshooting and support, refer to the error handling section in the API documentation. Common issues include invalid tokens (401 Unauthorized), insufficient permissions (403 Forbidden), and validation errors (400 Bad Request). If you encounter persistent issues or need assistance with your integration, don't hesitate to contact your system administrator or refer to the troubleshooting guides in this documentation.