Stays.net External API

https://stays.net/external-api/
Admin
The Stays.net External API provides a comprehensive set of endpoints for managing bookings, promo...
Tokens:110,243
Snippets:272
Trust Score:9.7
Update:9 months ago
Show doc for...
Tokens:
Raw
### Client Notifications: Creation Example

Source: https://stays.net/external-api/index_introduction

Shows an example of a 'client.created' notification. This notification is triggered when a new client record is added to the system. The payload contains comprehensive client details including name, contact information, and documents.

```json
{
  "action": "client.created",
  "_dt": "2020-08-25T15:38:22.250Z",
  "payload": {
    "_id" : "5f452ffe46ae1779ab9de125",
    "kind" : "person",
    "fName" : "John",
    "lName" : "Last",
    "name" : "John Last",
    "email" : "john@stays.net",
    "isUser" : false,
    "phones" : [
      {
        "iso" : "+5511965311223",
        "hint" : "mobile"
      }
    ],
    "documents" : [
      {
        "type" : "passport",
        "numb" : "1234567",
        "issued" : "",
        "date" : "2014-08-14"
      }
    ],
    "prefLang" : "pt_BR",
    "alternateLangs" : [
      "pt_BR",
      "en_US"
    ],
    "internalNote" : "internal note"
  }
}

```

--------------------------------

### Listing Notifications: Creation Example

Source: https://stays.net/external-api/index_introduction

Presents an example of a 'listing.created' notification. This notification is sent when a new listing is added. The payload contains essential information about the listing, such as its ID, type, status, and internal name.

```json
{
  "action": "listing.created",
  "_dt": "2020-08-25T15:42:22.338Z",
  "payload": {
    "_id" : "5f45315346ae1779ab9de13b",
    "id" : "HQ01G",
    "_idtype" : "5ab8f8a2f6b2dc2e97f97050",
    "_t_typeMeta" : {
      "_mstitle" : {
        "en_US" : "Apartment",
        "pt_BR" : "Apartamento",
        "es_ES" : "Departamento"
      }
    },
    "subtype" : "entire_home",
    "internalName" : "int001",
    "status" : "draft",
    "deff_curr" : "BRL",
    "_t_imagesMeta" : [ ],
    "instantBooking" : true
  }
}

```

--------------------------------

### GET /external/v1/settings/app/listing-custom-fields

Source: https://stays.net/external-api/index_introduction

Retrieves a list of all custom app fields settings.

```APIDOC
## Retrieve app listing custom fields

### Description
This endpoint returns custom app fields settings.

### Method
GET

### Endpoint
/external/v1/settings/app/listing-custom-fields

### Header Parameters
- **Authorization** (string) - Required - Basic hash_base64(client_id:client_secret)
- **Content-Type** (string) - Required - application/json

### Response
#### Success Response (200)
- **id** (Number) - Listing custom field identifier
- **_msname** (Object) - Name translation
- **internalName** (String) - Variable name
- **type** (Object) - Preview variable name

### Response Example
```json
[
  {
    "_idfield": 946361490530,
    "_msname": {
      "pt_BR": "Teste Custom Field 1",
      "en_US": "Test Custom Field 1"
    },
    "internalName": "Custom Field 1",
    "type": "Custom Field 1"
  }
]
```
```

--------------------------------

### Retrieve Reservation Extra-services (curl)

Source: https://stays.net/external-api/index_introduction

This example shows how to fetch all extra-services linked to a specific reservation. It uses a GET request to the reservation's extra-services endpoint, requiring authentication and JSON content type. The output is a JSON array of extra-service objects.

```curl
curl -X GET "https://play.stays.net/external/v1/booking/reservations/CJ01G/extra-services" \
  -H "Authorization: Basic ODAwOTQxMTU1NjpNTHlHTEl3RkFX" \
  -H "Content-Type: application/json"
```

--------------------------------

### Webhook Notifications Setup

Source: https://stays.net/external-api/index_introduction

Information on how to set up and receive webhook notifications for various reservation events. Requires contacting support to activate.

```APIDOC
# Webhook Notifications

System triggers different notifications when something changes. To activate this feature, please contact our support team and provide the URL that you will use for receiving notifications.

We use JSON notation to send notifications. To confirm receiving, please send a JSON answer `{ "succeed": true }`.

System will use 3 attempts to send notifications if a success answer is not received.

Each notification is a JSON object with 3 fields: `action`, `_dt`, and `payload`.

For each notification, we send several custom headers:
- `x-stays-client-id`: Contains the API user login.
- `x-stays-signature`: Contains a signature to verify that the message was really sent from us. To verify it, please contact us to get the public key for your application.

### Signature Verification Example (Node.js)
```javascript
const crypto = require('crypto');

const dataBuffer = Buffer.from(JSON.stringify({ action, _dt, payload }));
const signature = Buffer.from(signature, 'base64');
const result = crypto.verify("SHA256", dataBuffer, <your public key>, signature);
```

## Reservation Notifications

### Notification Actions and Payloads

| Action                  | Payload                                   |
| :---------------------- | :---------------------------------------- |
| `reservation.created`   | Reservation object                        |
| `reservation.modified`  | Reservation object                        |
| `reservation.canceled`   | Reservation object                        |
| `reservation.deleted`   | `{ _id, _idlisting, from, to }`           |
| `reservation.reactivated` | Reservation object                        |

### Example of Reservation Notification
```json
{
  "action": "reservation.created",
  "_dt": "2020-08-25T08:26:41.044Z",
  "payload": {
    "_id": "5f44cb2c9711ba5c07c35f28",
    "id": "HW04G",
    "checkInDate": "2020-08-31",
    "checkInTime": "15:00",
    "checkOutDate": "2020-09-04",
    "checkOutTime": "11:00",
    "_idlisting": "5e693a78f29390001011bbde",
    "_idclient": "5f3fa68776fd8f2edd50ef3e",
    "type": "booked",
    "price": {
      "currency": "BRL",
      "_f_total": 696
    },
    "stats": {
      "_f_totalPaid": 696
    },
    "guests": 2,
    "guestsDetails": {
      "adults": 2,
      "children": 0
    }
  }
}
```
```

--------------------------------

### GET /external/v1/settings/listing/{listingId}/sellprice

Source: https://stays.net/external-api/index_introduction

Allows to fetch listing settings, specifically the sell price settings for a given listing.

```APIDOC
## GET /external/v1/settings/listing/{listingId}/sellprice

### Description
This endpoint returns sell price settings for a certain listing.

### Method
GET

### Endpoint
/external/v1/settings/listing/{listingId}/sellprice

### Parameters
#### Path Parameters
- **listingId** (String) - Required - Listing identifier. Both identifiers (long and short) are supported.

#### Header Parameters
- **Authorization** (String) - Required - Basic hash_base64(client_id:client_secret)
- **Content-Type** (String) - Required - application/json

### Response
#### Success Response (200)
- **_idlisting** (String) - Listing identifier.
- **mainCurrency** (String) - Main currency of the listing.
- **fees** (Array) - Array of fees associated with the listing.
  - **_id** (String) - Fee identifier.
  - **_f_val** (Number) - Fee value.
  - **type** (String) - Fee type (e.g., "fixed", "percent").
  - **chargeType** (String) - How the fee is charged (e.g., "perReserve", "perPerson").
  - **invoiceVisibility** (String) - Visibility on the invoice (e.g., "basic", "extras").
  - **internalName** (String) - Internal name of the fee.
  - **_mstitle** (Object) - Fee title translations.
- **securityDeposit** (Number) - Security deposit amount.
- **guestsIncluded** (Number) - Number of guests included in the base price.
- **extraGuests** (Object) - Settings for extra guests.
  - **type** (String) - Type of charge for extra guests (e.g., "percent").
  - **_f_val** (Number) - Value for extra guest charges.
  - **_f_fallbackAbsVal** (Number) - Fallback absolute value for extra guest charges.

#### Response Example
{
    "_idlisting": "6100177563cd0f28803e011b",
    "mainCurrency": "BRL",
    "fees": [
        {
            "_id": "57a31968b9b1fb291f3bcc1b",
            "_f_val": 200,
            "type": "fixed",
            "chargeType": "perReserve",
            "invoiceVisibility": "basic",
            "internalName": "Cleaning Fee",
            "_mstitle": {
                "en_US": "Cleaning Fee"
            }
        },
        {
            "_id": "6101442b3d031dc3bd813f1b",
            "_f_val": 3,
            "type": "percent",
            "chargeType": "perPerson",
            "invoiceVisibility": "extras",
            "internalName": "City Tax",
            "_mstitle": {
                "pt_PT": "Imposto Municipal",
                "en_US": "City Tax"
            }
        }
    ],
    "securityDeposit": 300,
    "guestsIncluded": 2,
    "extraGuests": {
        "type": "percent",
        "_f_val": 10,
        "_f_fallbackAbsVal": 150
    }
}
```

--------------------------------

### POST /external/v1/booking/clients - Create Client

Source: https://stays.net/external-api/index_introduction

Creates a new client. Requires client details in the request body.

```APIDOC
## POST /external/v1/booking/clients

### Description
Creates a new client. Requires client details in the request body.

### Method
POST

### Endpoint
/external/v1/booking/clients

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - Basic hash_base64(client_id:client_secret)
- **Content-Type** (string) - Required - application/json

#### Request Body
- **kind** (string) - Required - Client kind. Applicable only "personal" or "company"
- **fName** (string) - Optional - First name. Applicable for personal account
- **lName** (string) - Optional - Last name. Applicable for personal account
- **name** (string) - Optional - Name of client. Applicable for company
- **email** (string) - Required - email address of client
- **isUser** (boolean) - Optional - Indicates if client has access to personal area on site
- **birthDate** (string) - Optional - Birth date (ISO date string YYYY-MM-DD)
- **gender** (string) - Optional - Gender
- **civilState** (string) - Optional - Civil State
- **nationality** (string) - Optional - Nationality
- **internalNote** (string) - Optional - Some internal information about this client
- **phones** (array[object]) - Optional - Array of phones object
  - **phones.iso** (string) - Phone
  - **phones.hint** (string) - Phone hint
- **documents** (array[object]) - Optional - Array of documents object
  - **documents.type** (string) - Document type. Applicable only "cpf", "cnpj", "id", "passport", "rne"
  - **documents.numb** (string) - Document number
  - **documents.issued** (string) - Name of organization what issued document
  - **documents.date** (string) - Documents date (ISO date string YYYY-MM-DD)
- **prefLang** (string) - Optional - Language code in iso format [ en_US, pt_BR, de_DE, es_ES, ru_RU, sv_SE, it_IT, fr_FR, pt_PT, el_GR ]
- **alternateLangs** (string) - Optional - Alternative language code in iso format [ en_US, pt_BR, de_DE, es_ES, ru_RU, sv_SE, it_IT, fr_FR, pt_PT, el_GR ]
- **responsibility** (object) - Optional - User responsibility functions
  - **responsibility.reservationAgent** (boolean) - Reservation's agent function

### Request Example
```json
{
  "example": "curl -X POST \"https://play.stays.net/external/v1/booking/clients\" \
  -H \"Authorization: Basic ODAwOTQxMTU1NjpNTHlHTEl3RkFX\" \
  -H \"Content-Type: application/json\"\
  -d '{ \n    \"_id\": \"630a0e4948990321ce00d9a3\",\n    \"kind\": \"person\",\n    \"fName\": \"fName\",\n    \"lName\": \"lName\",\n    \"email\": \"fName@gmail.com\",\n    \"isUser\": true\n }'"
}
```

### Response
#### Success Response (200)
- **_id** (string) - Unique identifier for the created client
- **kind** (string) - Type of client
- **fName** (string) - First name of the client
- **lName** (string) - Last name of the client
- **name** (string) - Full name of the client
- **email** (string) - Email address of the client
- **isUser** (boolean) - Indicates if the client has user access
- **creationDate** (string) - Date the client was created (YYYY-MM-DD)
- **clientSource** (string) - Source of the client creation

#### Response Example
```json
{
  "example": {
    "_id": "6487659335454e1480eded5e",
    "kind": "person",
    "fName": "fName",
    "lName": "lName",
    "name": "fName lName",
    "email": "fname@gmail.com",
    "isUser": true,
    "creationDate": "2023-06-12",
    "clientSource": "booking"
  }
}
```
```

--------------------------------

### Get Multi-Unit Property Types (GET)

Source: https://stays.net/external-api/index_introduction

This endpoint retrieves a list of system-built-in multi-unit property types. It is useful for populating dropdowns or providing users with available property type options. The request requires basic authentication and content type specification. An optional search string can filter results.

```curl
curl -X GET "https://play.stays.net/external/v1/translation/multi-unit-property-types" \
  -H "Authorization: Basic ODAwOTQxMTU1NjpNTHlHTEl3RkFX" \
  -H "Content-Type: application/json"
```

--------------------------------

### App Settings API

Source: https://stays.net/external-api/index_introduction

Allows to fetch app settings.

--------------------------------

### Get Listing Sell Price Settings - cURL

Source: https://stays.net/external-api/index_introduction

This snippet shows how to retrieve the sell price settings for a specific listing using a cURL GET request. It requires the listingId as a path parameter and includes authorization and content-type headers. The response is a JSON object detailing the listing's pricing configuration.

```cURL
curl -X GET "https://play.stays.net/external/v1/settings/listing/UO01G/sellprice" \
  -H "Authorization: Basic ODAwOTQxMTU1NjpNTHlHTEl3RkFX" \
  -H "Content-Type: application/json"
```

--------------------------------

### Promocode Notifications: Creation Example

Source: https://stays.net/external-api/index_introduction

Details the 'promocode.created' notification, indicating the addition of a new promotional code. The payload includes the promocode's ID, name, status, discount details, usage limits, and various restriction settings.

```json
{
  "action": "promocode.created",
  "_dt": "2020-08-25T15:40:22.325Z",
  "payload": {
    "_id" : "5f4530e146ae1779ab9de134",
    "name" : "summer2020",
    "status" : "active",
    "type" : "percent",
    "_f_discount" : 10,
    "maxUsesCount" : 10,
    "usedCount" : 0,
    "useWithOtherPromotions" : false,
    "periodRestrictions" : {
      "enable" : true,
      "from" : "2020-08-25",
      "to" : "2020-09-01",
      "invalidDaysOfWeek" : [
        1,
        2
      ]
    },
    "calendarRestrictions" : {
      "enable" : false
    },
    "productRestrictions" : {
      "enable" : false
    },
    "userRestrictions" : {
      "enable" : false
    }
  }
}

```

--------------------------------

### GET /external/v1/finance/payment-providers/{providerId}

Source: https://stays.net/external-api/index_introduction

Retrieves a specific payment provider by its ID.

```APIDOC
## Retrieve Payment Provider

### Description
This endpoint returns payment provider item.

### Method
GET

### Endpoint
/external/v1/finance/payment-providers/{providerId}

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - Basic hash_base64(client_id:client_secret)
- **Content-Type** (string) - Required - application/json

#### Path Parameters
- **providerId** (string) - Required - Provider identifier

### Response
#### Success Response (200)
- **_id** (string) - Payment provider identifier
- **type** (string) - Type of the payment provider
- **status** (string) - Status of the payment provider
- **_mcstartBalance** (object) - Starting balance of the payment provider
- **internalName** (string) - Internal name of the payment provider
- **_mstitle** (object) - Multilanguage commercial name
- **_msdesc** (object) - Multilanguage commercial description
- **allowPayments** (boolean) - Indicates if payments are allowed
- **currencies** (array) - List of accepted currencies
- **_msconfirmText** (object) - Multilanguage confirmation text
- **bankDetails** (string) - Bank details for the payment provider

#### Response Example
```json
{
  "_id": "632899b716de853470f8a0b8",
  "type": "bank",
  "status": "active",
  "_mcstartBalance": {
      "BRL": 0
  },
  "internalName": "Main bank",
  "_mstitle": {
      "en_US": "World wide bank"
  },
  "_msdesc": {
      "en_US": "The greatest bank in the world"
  },
  "allowPayments": true,
  "currencies": [
      "BRL"
  ],
  "_msconfirmText": {
      "en_US": "Finalize your reservation for our customer service team to contact you."
  },
  "bankDetails": "<p>Unibanco</p><p>Cód.231</p><p>Agência: 5362</p><p>Conta Corrente: 11257-0</p>"
}
```
```

--------------------------------

### POST /external/v1/settings/app/listing-custom-fields

Source: https://stays.net/external-api/index_introduction

Creates a new custom app field setting.

```APIDOC
## Create app listing custom fields

### Description
This endpoint creates a custom app fields setting.

### Method
POST

### Endpoint
/external/v1/settings/app/listing-custom-fields

### Header Parameters
- **Authorization** (string) - Required - Basic hash_base64(client_id:client_secret)
- **Content-Type** (string) - Required - application/json

### Request Body
- **_msname** (Object) - Required - Name translation
- **internalName** (String) - Required - Variable name
- **type** (Object) - Required - Preview variable name

### Request Example
```json
{
  "_msname": {
    "pt_BR": "Teste Custom Field 2",
    "en_US": "Test Custom Field 2"
  },
  "internalName": "Custom Field 2",
  "type": "Custom Field 2"
}
```

### Response
#### Success Response (200)
- **id** (Number) - Listing custom field identifier
- **_msname** (Object) - Name translation
- **internalName** (String) - Variable name
- **type** (Object) - Preview variable name

### Response Example
```json
{
  "_idfield": 1209715029510,
  "_msname": {
    "pt_BR": "Teste Custom Field 2",
    "en_US": "Test Custom Field 2"
  },
  "internalName": "Custom Field 2",
  "type": "Custom Field 2"
}
```
```

--------------------------------

### Create Listing

Source: https://stays.net/external-api/index_introduction

Creates a new listing associated with a property or as a standalone unit. Requires detailed information about the listing.

```APIDOC
## Create Listing

### Description
Creates a new listing associated with a property or as a standalone unit. Requires detailed information about the listing.

### Method
POST

### Endpoint
/external/v1/content/listings

### Parameters
#### Header Parameters
- **Authorization** (String) - Required - Basic hash_base64(client_id:client_secret)
- **Content-Type** (String) - Required - application/json

#### Request Body
- **internalName** (String) - Required - Listing unique internal name
- **_idproperty** (String) - Required - Property identifier. If creating a single-unit listing, use `_idpropertyType` instead.
- **_idtype** (String) - Required - Listing type identifier. (Link to available types)
- **subtype** (String) - Required - Listing subtype identifier. Accepts values ["private_room", "entire_home", "shared_room"]
- **_mstitle** (Object) - Required - Object containing localized titles for the listing (e.g., {"en_US": "Wonderful Apartment", "pt_BR": "Apartamento maravilhoso"})
- **_msdesc** (Object) - Optional - Object containing localized descriptions for the listing
- **status** (String) - Optional - Listing status. Default is 'draft'.
- **address** (Object) - Required - Address object for the listing.
  - **countryCode** (String) - Required
  - **state** (String) - Required
  - **stateCode** (String) - Required
  - **city** (String) - Required
  - **region** (String) - Optional
  - **street** (String) - Required
  - **streetNumber** (String or Integer) - Required
  - **additional** (String) - Optional
  - **zip** (String) - Required
- **latLng** (Object) - Optional - Latitude and longitude coordinates.
  - **_f_lat** (Float) - Required if latLng is provided
  - **_f_lng** (Float) - Required if latLng is provided
- **amenities** (Array of Objects) - Optional - List of amenities, each with an `_id` field.

### Request Example
```json
{
  "internalName": "API Listing 001",
  "_idproperty": "5f8963b5e1b59ec59f091a81",
  "_idtype": "5ab8f8a2f6b2dc2e97f97050",
  "subtype": "private_room",
  "_mstitle": {
    "en_US": "Wonderful Apartment",
    "pt_BR": "Apartamento maravilhoso"
  },
  "_msdesc": {
    "en_US": "Apartment API description",
    "pt_BR": "Descrição do Apartment API"
  },
  "status": "active",
  "address": {
    "countryCode": "BR",
    "state": "São Paulo",
    "stateCode": "SP",
    "city": "Barueri",
    "region": "Alphaville",
    "street": "Alameda Rio Negro",
    "streetNumber": "584",
    "additional": "2b",
    "zip": "06454000"
  },
  "latLng": {
    "_f_lat": -23.5007271,
    "_f_lng": -46.8479001
  },
  "amenities": [
    {
      "_id": "58931ca0e1875b6163592c7b"
    },
    {
      "_id": "58931b86e1875b6163592c74"
    }
  ]
}
```

### Response
#### Success Response (200)
- **Listing Object**: An object representing the newly created listing, including its `id` and other details.

#### Response Example
```json
{
  "_id": "5f896e2165394ecf5ddcfb97",
  "id": "JQ08G",
  "_idproperty": "5f8963b5e1b59ec59f091a81",
  "_t_propertyTypeMeta": {
    "_mstitle": {
      "pt_BR": "Prédio",
      "en_US": "Building",
      "es_ES": "Edifício",
      "pt_PT": "Prédio"
    }
  },
  "_idtype": "5ab8f8a2f6b2dc2e97f97050",
  "_t_typeMeta": {
    "_mstitle": {
      "en_US": "Apartment",
      "pt_BR": "Apartamento",
      "es_ES": "Departamento",
      "pt_PT": "Apartamento"
    }
  },
  "subtype": "private_room",
  "internalName": "API Listing 001",
  "_mstitle": {
    "en_US": "Wonderful Apartment",
    "pt_BR": "Apartamento maravilhoso"
  },
  "_msdesc": {
    "en_US": "Apartment API description",
    "pt_BR": "Descrição do Apartment API"
  },
  "status": "draft",
  "address": {
    "countryCode": "BR",
    "state": "São Paulo",
    "stateCode": "SP",
    "city": "Barueri",
    "region": "Alphaville",
    "street": "Alameda Rio Negro",
    "streetNumber": "584",
    "additional": "2b",
    "zip": "06454000"
  },
  "latLng": {
    "_f_lat": -23.5007271,
    "_f_lng": -46.8479001
  },
  "amenities": [
    {
      "_id": "58931ca0e1875b6163592c7b"
    },
    {
      "_id": "58931b86e1875b6163592c74"
    }
  ],
  "deff_curr": "BRL",
  "_t_imagesMeta": [],
  "instantBooking": true
}
```
```

--------------------------------

### GET /external/v1/finance/payment-providers

Source: https://stays.net/external-api/index_introduction

Retrieves a list of payment providers, optionally filtered by status.

```APIDOC
## GET /external/v1/finance/payment-providers

### Description
Retrieves a list of payment providers. You can filter the results by specifying the provider's status.

### Method
GET

### Endpoint
`/external/v1/finance/payment-providers`

### Parameters
#### Header Parameters
- **Authorization** (String) - Required - Basic hash_base64(client_id:client_secret)
- **Content-Type** (String) - Required - application/json

#### Query Parameters
- **status** (String) - Optional - Payment provider status. Can be 'active' or 'inactive'.

### Request Example
```
curl -X GET "https://play.stays.net/external/v1/finance/payment-providers?status=active" \
  -H  "accept: application/json" \
  -H  "Authorization: Basic ODAwOTQxMTU1NjpNTHlHTEl3RkFX"
```

### Response
#### Success Response (200)
- **_id** (String) - Payment provider identifier
- **type** (String) - Payment provider type ('user' or 'bank')
- **status** (String) - Payment provider status ('active' or 'inactive')
- **_mcstartBalance** (Object) - Accounting starting balance (multicurrency)
- **internalName** (String) - Payment provider internal name (for type 'bank')
- **allowPayments** (Boolean) - Indicates if bank will be used for frontend allowPayments (for type 'bank')
- **currencies** (Array) - List of accepted currencies for frontend allowPayments (for type 'bank')
- **_mstitle** (Object) - Multilanguage commercial name
- **_msdesc** (Object) - Multilanguage commercial description
- **bankDetails** (String) - Extra info that client needs to complete payment (for type 'bank')
- **_msconfirmText** (Object) - Multilanguage confirmation text
- **_iduser** (String) - User identifier (for type 'user')

#### Response Example
```json
[
  {
    "_id": "603ff86ebd3be0c6db6d83d8",
    "type": "bank",
    "status": "active",
    "_mcstartBalance": {
        "BRL": 0
    },
    "internalName": "PIX",
    "_mstitle": {
        "pt_BR": "PIX"
    },
    "_msdesc": {
        "pt_BR": "<p>Finalize sua reserva para o nosso time de atendimento entrar em contato.</p>"
    },
    "allowPayments": true,
    "currencies": [
        "BRL"
    ],
    "_msconfirmText": {
        "pt_BR": "<p>Nossa equipe de atendimento entrará em contato para finalizar sua reserva<br></p>"
    },
    "bankDetails": "Nossa equipe de atendimento entrará em contato para finalizar sua reserva"
  }
]
```
```

--------------------------------

### GET /external/v1/booking/reservations/{reservationId}/extra-services

Source: https://stays.net/external-api/index_introduction

Retrieves all extra-services associated with a specific reservation.

```APIDOC
## Retrieve reservation extra-services

### Description
This endpoint returns a list of extra-services for a given reservation.

### Method
GET

### Endpoint
`/external/v1/booking/reservations/{reservationId}/extra-services`

### Parameters
#### Path Parameters
- **reserveId** (String) - Required - Reservation identifier.

#### Header Parameters
- **Authorization** (String) - Required - Basic hash_base64(client_id:client_secret)
- **Content-Type** (String) - Required - application/json

### Request Example
```
curl -X GET "https://play.stays.net/external/v1/booking/reservations/CJ01G/extra-services" \
  -H "Authorization: Basic ODAwOTQxMTU1NjpNTHlHTEl3RkFX" \
  -H "Content-Type: application/json"
```

### Response
#### Success Response (200)
- **_id** (String) - Unique identifier for the extra-service.
- **_idextra** (String) - Identifier for the extra-service.
- **_msname** (Object) - Name of the extra-service in various languages.
- **_f_unitPrice** (Number) - Unit price of the extra-service.
- **_i_unitCount** (Number) - Unit count for the extra-service.
- **_f_val** (Number) - Value of the extra-service.
- **startDate** (String) - Start date of the service.
- **endDate** (String) - End date of the service.
- **startTime** (String) - Start time of the service.
- **endTime** (String) - End time of the service.
- **desc** (String) - Description of the extra-service.

#### Response Example
```json
[
  {
    "_id": "5dee464910450609ca7ea2d7",
    "_idextra": "5dee464910450609ca7ea2d7",
    "_msname": {
      "en_US": "string",
      "pt_BR": "string",
      "de_DE": "string",
      "es_ES": "string",
      "pt_PT": "string",
      "ru_RU": "string",
      "sv_SE": "string",
      "it_IT": "string",
      "fr_FR": "string",
      "el_GR": "string"
    },
    "_f_unitPrice": 0,
    "_i_unitCount": 0,
    "_f_val": 0,
    "startDate": "2020-02-29",
    "endDate": "2020-02-29",
    "startTime": "14:00",
    "endTime": "14:00",
    "desc": "string"
  }
]
```
```

--------------------------------

### Promotional Code Creation/Update API

Source: https://stays.net/external-api/index_introduction

This section details the parameters required for creating or updating a promotional code. It covers discount types, usage limits, and various restriction settings.

```APIDOC
## POST/PUT /promo-codes

### Description
Allows for the creation or update of promotional codes with detailed configuration options.

### Method
POST/PUT

### Endpoint
/promo-codes

### Parameters
#### Request Body
- **name** (String) - Required - Promo code name
- **type** (String) - Required - Promo code discount type. Can be 'fixed' or 'percent'
- **_f_discount** (Number) - Optional - Promo code percentage discount
- **_mcdiscount** (Object) - Optional - Promo code fixed discount with multicurrency
- **status** (String) - Optional - Promo code status. Can be 'active' or 'inactive'
- **maxUsesCount** (Integer) - Optional - Define, how many times promo code can be used
- **maxUsesCountPerGuest** (Integer) - Optional - Define, how many times per guest promo code can be used
- **usedCount** (Integer) - Optional - Define, how many times the promo was used
- **usedCountPerGuest** (Integer) - Optional - Define, how many times the promo was used per guest
- **useWithOtherPromotions** (Boolean) - Optional - Can promocode be applied if other promotions exists
- **periodRestrictions** (Object) - Optional - Defines general restrictions for date range of using
  - **enable** (Boolean) - Optional - Indicates if restrictions are active
  - **from** (ISO date string `YYYY-MM-DD`) - Optional - Start date when promocode can be applied
  - **to** (ISO date string `YYYY-MM-DD`) - Optional - End date when promocode can be applied
  - **invalidDaysOfWeek** (Array) - Optional - Days of week, when promocode cannot be applied. Possible values are 1-7. Where 1 is Monday, 7 is Sunday
- **calendarRestrictions** (Object) - Optional - Defines calendar restrictions
  - **enable** (Boolean) - Optional - Indicates if restrictions are active
  - **validArrivalDates** (Object) - Optional - Defines date range for arrival, when promocode can be applied
    - **from** (ISO date string `YYYY-MM-DD`) - Optional - Start arrival date when promocode can be applied
    - **to** (ISO date string `YYYY-MM-DD`) - Optional - End arrival date when promocode can be applied
  - **invalidArrivalDates** (Object) - Optional - Defines date range for arrival, when promocode cannot be applied
    - **from** (ISO date string `YYYY-MM-DD`) - Optional - Start arrival date when promocode cannot be applied
    - **to** (ISO date string `YYYY-MM-DD`) - Optional - End arrival date when promocode cannot be applied
  - **validDepartureDates** (Object) - Optional - Defines date range for departure, when promocode can be applied
    - **from** (ISO date string `YYYY-MM-DD`) - Optional - Start departure date when promocode can be applied
    - **to** (ISO date string `YYYY-MM-DD`) - Optional - End departure date when promocode can be applied
  - **invalidDepartureDates** (Object) - Optional - Defines date range for departure, when promocode cannot be applied
    - **from** (ISO date string `YYYY-MM-DD`) - Optional - Start departure date when promocode cannot be applied
    - **to** (ISO date string `YYYY-MM-DD`) - Optional - End departure date when promocode cannot be applied
  - **minLengthOfStay** (Integer) - Optional - Indicates minimum nights number of booking when promocode can be applied
- **productRestrictions** (Object) - Optional - Defines product restrictions using bedrooms or groups
  - **enable** (Boolean) - Optional - Indicates if restrictions are active
  - **bedgrooms** (Array) - Optional - Defines bedrooms numbers for what promo code is applicable. For Studio is 0
  - **groups** (Array) - Optional - Defines groups identifiers for what promo code is applicable
  - **listingsLimit** (Object) - Optional - Defines the limit of the listings
    - **type** (String) - Optional - Type of listing limit [ no, exclude, include ]
    - **apartments** (String) - Optional - Apartments identifier
    - **buildings** (String) - Optional - Buildings identifier
- **userRestrictions** (Object) - Optional - Defines user restrictions
  - **enable** (Boolean) - Optional - Indicates if restrictions are active
  - **emails** (Array) - Optional - Defines list of guests emails for what promo code is applicable.
  - **clients** (Array) - Optional - Defines list of clients identifiers for what promo code is applicable.
  - **minReservationsCount** (Integer) - Optional - Defines min number of previous guest's reservations after promo code will be valid
  - **minAmountSpentByGuest** (Number) - Optional - Defines min amount of money that guest spent before to make promo code valid
  - **maxGuestsCount** (Integer) - Optional - Defines max guests count for reservations

### Request Example
```json
{
  "name": "SUMMER20",
  "type": "percent",
  "_f_discount": 20,
  "status": "active",
  "useWithOtherPromotions": false,
  "periodRestrictions": {
    "enable": true,
    "from": "2024-06-01",
    "to": "2024-08-31",
    "invalidDaysOfWeek": [1, 7]
  },
  "productRestrictions": {
    "enable": true,
    "bedgrooms": [1, 2]
  },
  "userRestrictions": {
    "enable": true,
    "emails": ["guest@example.com"]
  }
}
```

### Response
#### Success Response (200)
- **promoCodeId** (String) - The unique identifier for the created or updated promotional code.
- **message** (String) - A confirmation message indicating the success of the operation.

#### Response Example
```json
{
  "promoCodeId": "promo_abc123xyz",
  "message": "Promotional code updated successfully."
}
```
```

--------------------------------

### GET /external/v1/booking/extra-services/{id}

Source: https://stays.net/external-api/index_introduction

Retrieves details of a specific extra-service associated with a booking.

```APIDOC
## Retrieve Extra-service

### Description
This endpoint returns a reservation extra-service based on the provided ID.

### Method
GET

### Endpoint
`/external/v1/booking/extra-services/{id}`

### Parameters
#### Path Parameters
- **id** (String) - Required - Reservation identifier.

#### Header Parameters
- **Authorization** (String) - Required - Basic hash_base64(client_id:client_secret)
- **Content-Type** (String) - Required - application/json

### Request Example
```
curl -X GET "https://play.stays.net/external/v1/booking/extra-services/{id}" \
  -H "Authorization: Basic ODAwOTQxMTU1NjpNTHlHTEl3RkFX" \
  -H "Content-Type: application/json"
```

### Response
#### Success Response (200)
- **_id** (String) - Unique identifier for the extra-service.
- **_msname** (Object) - Name of the extra-service in various languages.
- **_msprice** (Object) - Price of the extra-service in different currencies.
- **itemId** (String) - Identifier for the item.
- **categoryId** (String) - Identifier for the category.
- **dateTimeRangeSettings** (Object) - Settings for date and time range.
- **lodgingCheck** (Boolean) - Indicates if lodging check is enabled.

#### Response Example
```json
{
  "_id": "5dee464910450609ca7ea2d7",
  "_msname": {
    "en_US": "string",
    "pt_BR": "string",
    "de_DE": "string",
    "es_ES": "string",
    "pt_PT": "string",
    "ru_RU": "string",
    "sv_SE": "string",
    "it_IT": "string",
    "fr_FR": "string",
    "el_GR": "string"
  },
  "_msprice": {
    "BRL": 0,
    "USD": 0,
    "EUR": 0,
    "MXN": 0,
    "ARS": 0,
    "UYU": 0,
    "PYG": 0,
    "CLP": 0,
    "COP": 0,
    "ZAR": 0,
    "XAF": 0,
    "BWP": 0,
    "MZN": 0,
    "NAD": 0,
    "SZL": 0,
    "LSL": 0,
    "AED": 0,
    "PEN": 0,
    "GBP": 0,
    "AUD": 0,
    "RUB": 0,
    "THB": 0,
    "DOP": 0,
    "CRC": 0,
    "SEK": 0,
    "IDR": 0,
    "CAD": 0,
    "NOK": 0
  },
  "itemId": "5dee464910450609ca7ea2d7",
  "categoryId": "5dee464910450609ca7ea2d7",
  "dateTimeRangeSettings": {
    "date": "single",
    "time": "single",
    "chargeType ": "perDay"
  },
  "lodgingCheck": true
}
```
```
Tokens:
Raw