Link

API reference - Swagger

You can find all of apaleo’s APIs on api.apaleo.com. We use Swagger to describe it and to generate our documentation.

Swagger, or OpenAPI, unites complex API information into an interactive and language-agnostic reference resource. Swagger provides critical reference material about which JSON payloads, HTTP methods, and specific endpoints to use to perform operations against an API.

The first step is to sign up for your free trial account. After you finish signup, you will be able to login to apaleo and start configuring your properties. Also, you can use the same credentials to access our API using Swagger.

You can access apaleo’s API Swagger documentation at:

https://api.apaleo.com/swagger/



Overview

The automatically generated Swagger reference material provides a quick overview of essential concepts, available API endpoints, and a description of each object model to assist development and testing.

A concise summary describes the API.

API object models are also listed.

You can select each listed object model for a more detailed summary of key attributes.

The generated Swagger object models are convenient to read all available apaleo’s objects and APIs. Developers can use this resource when they integrate their apps with apaleo.


Endpoints

Swagger also provides a thorough overview of all endpoints that compose the APIs.

Each listed endpoint also includes the required request information, such as the:

  • Required parameters.
  • Required parameter data types.
  • HTTP method to access the resource.

Select each resource to display their additional content to get a more detailed overview.


Scopes

All OAuth 2.0 clients and access tokens have a scope. The scope restricts the endpoints to which a client has access, and whether a client has read or write access to an endpoint. For example, if you want to access endpoints that contain reservation data, then your app must have the reservations.read access scope.

Following scopes are supported by apaleo:

{
  "scopes": [
    {
      "name": "api",
      "description": "Core API",
      "scopes": [
        {
          "name": "companies.read",
          "displayName": "Read companies"
        },
        {
          "name": "companies.manage",
          "displayName": "Modify companies"
        },
        {
          "name": "reports.read",
          "displayName": "Retrieve report data"
        },
        {
          "name": "logs.read",
          "displayName": "Read logs"
        },
        {
          "name": "invoices.manage",
          "displayName": "Mark invoices as paid"
        },
        {
          "name": "invoices.read",
          "displayName": "Retrieve invoices and preview invoices as data or PDF"
        },
        {
          "name": "folios.manage",
          "displayName": "Perform actions on folios"
        },
        {
          "name": "folios.read",
          "displayName": "Read folios, including charges and payments"
        },
        {
          "name": "account.manage",
          "displayName": "Update the current account"
        },
        {
          "name": "reservations.force-manage",
          "displayName": "Modify stay dates regardless of availability or restrictions"
        },
        {
          "name": "reservations.manage",
          "displayName": "Modify, check in/out, cancel reservations"
        },
        {
          "name": "reservations.read",
          "displayName": "Read reservations"
        },
        {
          "name": "availability.read",
          "displayName": "Retrieve availabiltiy information"
        },
        {
          "name": "offer-index.read",
          "displayName": "Request offer index"
        },
        {
          "name": "offers.read",
          "displayName": "Request offers"
        },
        {
          "name": "rateplans.read-corporate",
          "displayName": "Read corporate rate plans"
        },
        {
          "name": "rates.manage",
          "displayName": "Update rates and restrictions"
        },
        {
          "name": "rates.read",
          "displayName": "Read rates and restrictions"
        },
        {
          "name": "maintenances.manage",
          "displayName": "Change maintenacne windows"
        },
        {
          "name": "maintenances.read",
          "displayName": "Read maintenance information"
        },
        {
          "name": "setup.read",
          "displayName": "This scope allows the app to read settings and configurations for the whole account and all properties, including reading units, unit groups, and rate plans."
        },
        {
          "name": "setup.manage",
          "displayName": "This scope allows the app to modify settings and configurations for the whole account and all properties, including creating, modifying and deleting units, unit groups, rate plans and properties."
        },
        {
          "name": "accounting.read",
          "displayName": "Read accounting details"
        },
        {
          "name": "operations.trigger-night-audit",
          "displayName": "Trigger night audit"
        },
        {
          "name": "operations.change-room-state",
          "displayName": "Change room state"
        },
        {
          "name": "availability.manage",
          "displayName": "This scope allows to modify the availability"
        }
      ]
    },
    {
      "name": "distribution",
      "description": "Distribution API",
      "scopes": [
        {
          "name": "distribution:subscriptions.manage",
          "displayName": "Manage ARI notification configuration"
        },
        {
          "name": "distribution:reservations.manage",
          "displayName": "Create and modify bookings and reservations"
        }
      ]
    },
    {
      "name": "identity_server",
      "description": "Identity API",
      "scopes": [
        {
          "name": "identity:account-users.read",
          "displayName": "Read users"
        },
        {
          "name": "identity:account-users.manage",
          "displayName": "Manage users"
        }
      ]
    },
    {
      "name": "notifications",
      "description": "Notifications API"
    },
    {
      "name": "integration",
      "description": "Integration API",
      "scopes": [
        {
          "name": "integration:ui-integrations.manage",
          "displayName": "Include apaleo One content"
        }
      ]
    },
    {
      "name": "rendering",
      "description": "Rendering API",
      "scopes": [
        {
          "name": "rendering:upload-logo",
          "displayName": "Upload invoice logo"
        },
        {
          "name": "rendering:manage-configuration",
          "displayName": "Manage invoice configuration settings"
        },
        {
          "name": "rendering:render-invoice",
          "displayName": "Render invoices"
        },
        {
          "name": "rendering:read-configuration",
          "displayName": "Read invoice configuration settings"
        }
      ]
    },
    {
      "name": "fiscalization",
      "description": "The Fiscalization API",
      "scopes": [
        {
          "name": "fiscalization:configuration.manage",
          "displayName": "Full access to fiscalization configuration"
        }
      ]
    },
    {
      "name": "fiscalization-austria",
      "description": "The Fiscalization Austria API",
      "scopes": [
        {
          "name": "fiscalization-austria:snapshots.get",
          "displayName": "Get snapshots"
        },
        {
          "name": "fiscalization-austria:configuration.manage",
          "displayName": "Full access to fiscalization configuration"
        },
        {
          "name": "fiscalization-austria:receipts.read",
          "displayName": "Read receipts"
        }
      ]
    }
  ]
}

Testing endpoints

One of the powerful functionalities Swagger provides is the ability to test an API endpoint directly through the documentation UI.

After you select a specific endpoint, the Try it out button is displayed.

Expand that section to see the input fields for each required and optional parameter. Enter the correct values and select Execute.

After you execute the test, you can validate the response data.


Swagger response data

Each listed endpoint also includes response body data to validate your development and tests. These examples include the status codes and JSON for successful HTTP requests.


Swagger OAuth 2.0 authorization

Follow the steps in Register OAuth client applications to create and configure a client app. Alternatively, you can reuse an existing app registration.

After completing the client app registration:

  1. Select the Authorize button on your swagger page. ​

  2. Select the scopes and click Authorize.
    Important
    : Do not paste your Client ID in the client_id field. It will always be auto-populated. For example, “swagger-ui”. ​

  3. You will then be redirected to the following success modal.

  4. If you have not created an app and want to log in, then you can use your apaleo app login credentials to authorize Swagger. Click the Authorize button, as shown below.

  5. You will then be redirected to the following login page. Enter your Email and Password.

  6. You will then be redirected to the following success modal.


HTTP Status Codes and Error Types

apaleo uses standard HTTP status codes for each API’s response.

Status codes are divided into the following five categories:

  • 1xx: Informational - Communicates transfer protocol-level information.
  • 2xx: Success - The request was successful.
  • 3xx: Redirection - The client must take some additional action to complete the request.
  • 4xx: Client Error - Failed request due to client error.
  • 5xx: Server Error - Failed request due to server error.