NTAK Daily close

On this page, we will explore the process of programmatically constructing the NTAK daily close report. We will delve into the steps and techniques required to build the report dynamically through code.

The NTAK daily close report differs from other reports in its generation process. It involves multiple steps:

Scheduler request

At 04:00 CET/CEST, NTAK.guru initiates a request to the government's NTAK system to retrieve the specific days for reporting.

Scheduler response

The government's NTAK system returns a list of dates for reporting.

If the list is empty, NTAK.guru will stop the entire process with success.
The list can contain up to 60 dates.
Dates can also be in the distant past

Daily close request & response

NTAK.guru compiles concurrent requests based on the response received from the scheduler.

3/1: 2024-09-01
3/2: 2024-09-02
3/x: 2024-09-05

The number of concurrent requests can range from 1 to a maximum of 60 (the same amount as the list returned by the government's NTAK system).

Concurrent requests are reducing the chance of errors in the reporting process.

For example, if 3/2 responds with an error, 3/1 and 3/x still could be sent to the government's NTAK system.

Reporting to the government's NTAK system

After receiving the all the responses from the PMS, NTAK.guru will compile the response and send it to the government's NTAK system.

What if the PMS has multiple accommodations connected to NTAK.guru?

To avoid potential request spamming, (A.K.A. DDoS attacks), we implemented rate limiting. Currently, it is set to 1 accommodation per 15 seconds.
There is a chance that we will decrease the rate limit in the future, but it will never be lower than 1 accommodation per 5 seconds.

Request

POST{accommodation-daily-close-url}

Request Body

Parameter	Description
`date`	The date for which day data should be collected by the PMS for daily close report.

{
  "date": "2024-09-19"
}

Authentication

To enhance the security of your endpoint, you have implemented a straightforward authorization mechanism. The mechanism involves using a token that represents the accommodation ID, which is encrypted using OpenSSL and then base64 encoded.

Our SDKs include the necessary public key for decryption purposes. Additionally, the SDK offers a utility class that facilitates the decryption of the accommodation ID, ensuring secure and authorized access to your endpoint.

The content of the authorization header, after decryption:

{
  "accommodation": "00000000-0000-0000-0000-000000000000"
}

⚠️

In the event that the decryption process fails, it indicates an invalid token or that the request was not sent by NTAK.guru. In such cases, it is important not to provide any data in the response.

To handle this situation, we recommend responding with a 401 Unauthorized HTTP status code. This status code indicates that the request lacks valid authentication credentials or the provided credentials are insufficient. By returning a 401 status code, you can appropriately communicate to the client that the request is unauthorized and no data will be provided in response.

Response (accommodation is operating)

`closedDay`

Date of the closed day.

Type	Format	Required
`string`	`Y-m-d`	Yes

`residentialUnits`

Data describing the occupancy of the accommodation's room will be added to this object.

Type	Required
`object`	Yes

all

On the day in question, all rooms in the accommodation, whether they can be rented out or not. It must match the total number of residential units entered during NTAK registration.

Type Required
number Yes
ooo

The number of rooms that are out of service in the long term. (Generally, due to renovation / planned capacity reduction, rooms cannot be reserved for guests.)

Type Required
number Yes
oos

Number of rooms that are out of service in the short term. (Generally, rooms outside the establishment can be reserved for guests.)

Type Required
number Yes
occupied

The number of rooms where a guest lives on a given day. Departure and day use rooms are not included.

Type Required
number Yes
available

The number of rooms (residential units) where a guest can be accommodated on a given day, regardless of whether a guest lives there or not. The number of rooms that can be rented out also includes the number of rooms that are rented out and out of service.

Type Required
number Yes

Type	Required
`number`	Yes

Type	Required
`number`	Yes

Type	Required
`number`	Yes

Type	Required
`number`	Yes

Type	Required
`number`	Yes

`afterStayExpenses`

In this type, expenses recorded days or even weeks later after a room has been booked can be sent.
Important: It is not necessary to refer to the room that generated the expense.

Type	Required
`Expense[]`	Nullable

`afterStayLoads`

In this type, loads recorded days or even weeks later after a room has been booked can be sent.
Important: It is not necessary to refer to the room that generated the load.

Type	Required
`Load[]`	Nullable

`checkOutDaySales`

Debits and revenues related to the residential units on the day of check-out.

Type	Required
`object[]`	Nullable

residentialUnit

Type Required
Residential unit Yes
salesChannel

It is necessary to categorize the accommodation unit nights by pre-defined sales channels.

Type Required
Sales channel Yes
marketSegment

Market segment value for the overnight reservation of the residential unit.

Type Required
Market segment Yes
reservationNumber

The reservation number for the overnight reservation of the residential unit. The same reservation number must be sent in the reservation report and in the event-driven messages associated with the reservation number.

Type Required
string or number Yes
expenses

The expenditure is a gross item paid by the guest without VAT, the amount and type of which the NTAK system takes into account.

Type Required
Expense Nullable
loads

Gross amount with VAT rate and service category charged to the guest's account for a service.

Type Required
Load Nullable

Type	Required
`Residential unit`	Yes

Type	Required
`Sales channel`	Yes

Type	Required
`Market segment`	Yes

Type	Required
`string` or `number`	Yes

Type	Required
`Expense`	Nullable

Type	Required
`Load`	Nullable

`residentialUnitNights`

Daily consumption data broken down by residential unit.

Type	Required
`object[]`	Nullable

guests

The field is used to describe the data of the guests staying in the apartment.

Type Required
Guest[] Yes
dayUse

The dayUse field indicates that a certain Residential unit was used as "day use" only during the day, the guest did not spend the night in the given housing unit. In case of daytime use, a certain Residential unit can be sent multiple times in the residentialUnitNights list, however, it can only be sent once with the value of the Daytime use field set to false (since a certain residential unit can only be filled for one night per day).

Type Required
boolean Yes
residentialUnit

Type Required
Residential unit Yes
salesChannel

It is necessary to categorize the accommodation unit nights by pre-defined sales channels.

Type Required
Sales channel Yes
marketSegment

Market segment value for the overnight reservation of the residential unit.

Type Required
Market segment Yes
reservationNumber

The reservation number for the overnight reservation of the residential unit. The same reservation number must be sent in the reservation report and in the event-driven messages associated with the reservation number.

Type Required
string or number Yes
expenses

The expenditure is a gross item paid by the guest without VAT, the amount and type of which the NTAK system takes into account.

Type Required
Expense Nullable
loads

Gross amount with VAT rate and service category charged to the guest's account for a service.

Type Required
Load Nullable

Type	Required
`Guest[]`	Yes

Type	Required
`Residential unit`	Yes

Type	Required
`Sales channel`	Yes

Type	Required
`Market segment`	Yes

Type	Required
`string` or `number`	Yes

Type	Required
`Expense`	Nullable

Type	Required
`Load`	Nullable

`otherExpenses`

Data type summarizing other expenses that cannot be linked to a residential unit.

Type	Required
`Expense[]`	Nullable

`otherLoads`

Data type summarizing other loads that cannot be linked to a residential unit.

isTouristTax property is ignored.

Type	Required
`Load[]`	Nullable

`outOfOrderResidentialUnits`

The list of rooms of the accommodation that are not in operation on the given day.

Type	Required
`Residential unit[]`	Nullable

{
  "closedDay": "2012-01-29",
  "residentialUnits": {
    "all": 37,
    "ooo": 0,
    "oos": 3,
    "occupied": 31,
    "available": 18
  },
  "afterStayExpenses": [
    {
      "date": "1979-06-21 12:21:46",
      "amount": 290.65,
      "paymentOption": "transfer",
      "paymentOptionSubtype": "soluta"
    }
  ],
  "afterStayLoads": [
    {
      "date": "1992-07-25 21:03:27",
      "amount": 441.31,
      "category": "drink",
      "isTouristTax": true,
      "taxPercentage": 96
    }
  ],
  "checkOutDaySales": [
    {
      "residentialUnit": {
        "type": "economy",
        "building": "m",
        "number": "913",
        "trundleBedCount": 0,
        "singleBedCount": 1,
        "doubleBedCount": 0
      },
      "salesChannel": "directly_traditional",
      "marketSegment": "vacation_group",
      "reservationNumber": "04816",
      "expenses": [
        {
          "date": "2021-02-22 13:43:30",
          "amount": 830.09,
          "paymentOption": "transfer",
          "paymentOptionSubtype": "eaque"
        }
      ],
      "loads": [
        {
          "date": "2015-06-15 19:04:53",
          "amount": 920.43,
          "category": "fee",
          "isTouristTax": false,
          "taxPercentage": 73
        }
      ]
    }
  ],
  "residentialUnitNights": [
    {
      "guests": [
        {
          "gender": "male",
          "guestId": "d1abd06d-1f1d-32ab-a379-b7aeff27dae3",
          "touristTaxStatus": "obliged",
          "yearOfBirth": "1979",
          "residenceCountryCode": "SC",
          "residencePostCode": "67736",
          "nationalityCountryCode": "GU"
        }
      ],
      "dayUse": false,
      "residentialUnit": {
        "type": "standard",
        "building": "b",
        "number": "549",
        "trundleBedCount": 0,
        "singleBedCount": 1,
        "doubleBedCount": 1
      },
      "salesChannel": "intermediary_online",
      "marketSegment": "business_individual",
      "reservationNumber": "39392",
      "expenses": [
        {
          "amount": 213.92,
          "paymentOption": "transfer",
          "paymentOptionSubtype": "quisquam"
        }
      ],
      "loads": [
        {
          "amount": 624.75,
          "category": "food",
          "isTouristTax": false,
          "taxPercentage": 73
        }
      ]
    }
  ],
  "otherExpenses": [
    {
      "amount": 484.85,
      "paymentOption": "voucher",
      "paymentOptionSubtype": "est"
    }
  ],
  "otherLoads": [
    {
      "amount": 621.01,
      "category": "drink",
      "taxPercentage": 83
    }
  ],
  "outOfOrderResidentialUnits": [
    {
      "type": "custom",
      "building": "e",
      "number": "962",
      "trundleBedCount": 2,
      "singleBedCount": 2,
      "doubleBedCount": 0
    }
  ]
}

Response (accommodation is NOT operating)

`closedDay`

Date of the closed day.

Type	Format	Required
`string`	`Y-m-d`	Yes

`accommodationNotOperating`

In the event that an accommodation is closed on the given day, it is necessary to send a daily closing message by setting the accommodationNotOperating field of the Daily Close type to the value "true".

Type	Required
`boolean`	Yes

`residentialUnits`

Data describing the occupancy of the accommodation's room will be added to this object.

Type	Required
`object`	Yes

all

On the day in question, all rooms in the accommodation, whether they can be rented out or not. It must match the total number of residential units entered during NTAK registration.

Type Required
number Yes
ooo

The number of rooms that are out of service in the long term. (Generally, due to renovation / planned capacity reduction, rooms cannot be reserved for guests.)

Type Required
number Yes
oos

Number of rooms that are out of service in the short term. (Generally, rooms outside the establishment can be reserved for guests.)

Type Required
number Yes
occupied

The number of rooms where a guest lives on a given day. Departure and day use rooms are not included.

Type Required
number Yes
available

The number of rooms (residential units) where a guest can be accommodated on a given day, regardless of whether a guest lives there or not. The number of rooms that can be rented out also includes the number of rooms that are rented out and out of service.

Type Required
number Yes

Type	Required
`number`	Yes

Type	Required
`number`	Yes

Type	Required
`number`	Yes

Type	Required
`number`	Yes

Type	Required
`number`	Yes

{
  "accommodationNotOperating": true,
  "closedDay": "2024-04-29",
  "residentialUnits": {
    "all": 24,
    "ooo": 2,
    "oos": 22,
    "occupied": 0,
    "available": 22
  }
}

Room Change List