Booking API

A booking is a type of permit that is anonymous and not visible to existing clients in autopay.io. It is tied to the vehicle. Typical usage for a booking is providing paid parking for a hotel guests who does not wish to go through the sign up procedure.

Available resources

• GET - Get a list of permit definitions that can be used to create a booking
• GET - Get a status of a booking
• GET - Get booking's availability
• POST - Request a booking for a vehicle
• PUT - Update an existing booking
• DELETE - Delete a booking
• Error handling

Access requirements

• A valid authentication token is required to access the API. How to authenticate your application.
• Access to the Booking API is offered as a paid service. Please contact your Autopay representative for details.
• There is a 15-minute query rate limit per booking on the GET Get a status of a booking endpoint.

GET - Get a status of a booking

To see the restrictions applied to change a booking, please see PUT - update an existing booking.

This method allows you to retrieve a status of a booking to see if it exists and whether it has been used. There are four different statuses:

Endpoint

GET https://api.autopay.io/booking/v3/{id}/status

Request parameters

• The HTTP headers must include a valid access token with scope: permit_booking.
• The request path must include booking id.

Success response

HTTP Code: 200 OK

Example success response

{
    "status": "USED"
}

GET - Get a list of permit definitions

This method allows you to retrieve a list of permit definitions that can be used to create a booking, and their joint access limit. Permit definitions are managed by Autopay operators.

Endpoint

GET https://api.autopay.io/booking/v3/permit_definitions

Request parameters

• The HTTP headers must include a valid access token with scope: permit_booking.

Success response

HTTP Code: 200 OK

Example success response

{
    "permit_definitions": [
        {
            "id": "802a2829-0c29-4a95-9960-1e73ca03dcd5",
            "old_id": 123645,
            "name": "Hotel guest parking in zone 215",
            "tenant_name": "Example tenant",
        },
        {
            "id": "c4959ab3-81c6-420d-8c81-8dc18db0db14",
            "old_id": 775820,
            "name": "Airport - Online booking",
            "tenant_name": "Example tenant",
        }
    ],
    "access_limit": {
        "mon": 1,
        "tue": 1,
        "wed": 1,
        "thu": 2,
        "fri": 1,
        "sat": 1,
        "sun": 1
    }
}

GET - Get booking's availability

This method allows you to retrieve available booking limit and it's validity period, if there is no available limit then it returns the time when there is one.

Endpoint

GET https://api.autopay.io/booking/v3/availability?valid_from={valid_from}

Request parameters

• The HTTP headers must include a valid access token with scope: permit_booking.
• The request path must include valid_from datetime in ISO 8601 format, URL encoded.

Request example

GET https://api.autopay.io/booking/v3/availability?valid_from=2023-03-14T13%3A00%3A00%2B0200

Success response

HTTP Code: 200 OK

Example success response

{
    "available": false,
    "limit_amount": 10,
    "valid_from": "2023-03-17T00:00:00+0000",
    "valid_to": "2023-03-22T00:00:00+0000"
}

POST - Request a booking

This method allows you request a booking for a vehicle. A booking can start and end at a specific time (fixed booking) or be relative to when the vehicle enters the parking venue (entry booking). Both types can be applied either beforehand or when the parking is already in progress.

Endpoint

POST https://api.autopay.io/booking/v3

Request parameters

• The request body must be in JSON format and HTTP headers must include Content-Type: application/json.
• The HTTP headers must include a valid access token with scope: permit_booking.

Example requests

Fixed type booking

{
    "type": "FIXED",
    "valid_from": "2023-03-14T00:00:00+0200",
    "valid_to": "2023-03-21T00:00:00+0200",
    "license_plate_number": "123ABC",
    "permit_definition_id": "802a2829-0c29-4a95-9960-1e73ca03dcd5",
    "operator_data": {
        "payment": {
            "amount": 370,
            "currency": "NOK"
        },
        "customer": {
            "email": "test@test.com",
            "mobile": "+47123456"
        },
        "travel_information": {
            "flight_id": "AB123"
        }
    }
}

Entry type booking with duration

{
    "type": "ENTRY",
    "duration": 18000,
    "expiration_time": "2023-03-21T00:00:00+0200",
    "comment": "comment",
    "usable_once": true,
    "license_plate_number": "456DEF",
    "permit_definition_id": "802a2829-0c29-4a95-9960-1e73ca03dcd5"
}

Entry type booking with valid_to

{
    "type": "ENTRY",
    "valid_to": "2023-03-21T00:00:00+0200",
    "comment": "comment",
    "usable_once": true,
    "license_plate_number": "789GHI",
    "permit_definition_id": "802a2829-0c29-4a95-9960-1e73ca03dcd5"
}

Success response

HTTP Code: 200 OK

Example success responses

Fixed type booking

{
    "booking_id": "123456",
    "type": "FIXED",
    "license_plate_number": "123ABC",
    "valid_from": "2023-03-13T22:00:00+0000",
    "valid_to": "2023-03-20T22:00:00+0000",
    "permit_definition_id": "802a2829-0c29-4a95-9960-1e73ca03dcd5",
    "created_at": "2023-03-14T11:24:38+0000"
}

Entry type booking with duration

{
    "booking_id": "123457",
    "type": "ENTRY",
    "license_plate_number": "456DEF",
    "expiration_time": "2023-03-20T22:00:00+0000",
    "duration": 18000,
    "permit_definition_id": "802a2829-0c29-4a95-9960-1e73ca03dcd5",
    "created_at": "2023-03-14T11:24:38+0000",
    "usable_once": true
}

Entry type booking with valid_to

{
    "booking_id": "123458",
    "type": "ENTRY",
    "license_plate_number": "789GHI",
    "permit_definition_id": "802a2829-0c29-4a95-9960-1e73ca03dcd5",
    "created_at": "2023-03-14T11:24:38+0000",
    "usable_once": true
}

PUT - Update an existing booking

This method allows you to edit booking information. The following restrictions are applied when changing a booking:

• One cannot change a booking’s id, type, or anonymous flag.
• The valid from time and license plate number cannot be changed when the booking is in use (status IN_USE).
• Bookings with statuses USED and EXPIRED cannot be changed.

Endpoint

PUT https://api.autopay.io/booking/v3/{id}

Request parameters

• The request body must be in JSON format and HTTP headers must include Content-Type: application/json.
• The HTTP headers must include a valid access token with scope: permit_booking.
• The request path must include booking id.

Example requests

Fixed type booking

{
    "type": "FIXED",
    "valid_from": "2023-03-14T00:00:00+0200",
    "valid_to": "2023-03-30T00:00:00+0200",
    "license_plate_number": "123ABC",
    "permit_definition_id": "802a2829-0c29-4a95-9960-1e73ca03dcd5",
    "operator_data": {
        "payment": {
            "amount": 370,
            "currency": "NOK"
        },
        "customer": {
            "email": "test@test.com",
            "mobile": "+47123456"
        },
        "travel_information": {
            "flight_id": "AB123"
        }
    }
}

Entry type booking

{
    "type": "ENTRY",
    "duration": 21000,
    "license_plate_number": "456DEF",
    "usable_once": true,
    "permit_definition_id": "802a2829-0c29-4a95-9960-1e73ca03dcd5"
}

Success response

HTTP Code: 200 OK

Example success responses

{
    "booking_id": "123456",
    "type": "FIXED",
    "license_plate_number": "123ABC",
    "valid_from": "2023-03-13T22:00:00+0000",
    "valid_to": "2023-03-29T22:00:00+0000",
    "permit_definition_id": "802a2829-0c29-4a95-9960-1e73ca03dcd5",
    "created_at": "2023-03-14T11:26:37+0000"
}

{
    "booking_id": "123457",
    "type": "ENTRY",
    "license_plate_number": "456DEF",
    "expiration_time": "2024-03-13T11:26:37+0000",
    "duration": 21000,
    "permit_definition_id": "802a2829-0c29-4a95-9960-1e73ca03dcd5",
    "created_at": "2023-03-14T11:26:37+0000",
    "usable_once": true
}

DELETE - Delete a booking

This method allows you to delete end-users booking. Only unused bookings can be deleted.

Endpoint

DELETE https://api.autopay.io/booking/v3/{id}

Request parameters

• The HTTP headers must include a valid access token with scope: permit_booking.
• The request path must include booking id.

Request example

DELETE https://api.autopay.io/booking/v3/123456

Success response

HTTP Code: 200 OK

Error messages

Example error response

{
    "error_id": "authentication_error",
    "message": "No access token present in header!"
}

Possible error IDs

Migration guide

Migration from V1 to V2 and version differences

• GET v2/permit_definitions
  • renamed from v1/products
• POST /v2
  • renamed from /v1/permit
  • renamed response parameter productId to permitDefinitionId
  • added optional anonymous_booking parameter to request and booking_activation_code to response if that parameter is true
• PUT /v2/{permitId}
  • renamed from /v1/permit/{permitId]
  • renamed response parameter productId to permitDefinitionId
• Error handling
  • error_id (string) is returned instead of error_code (integer)

Migration from V2 to V3 (current version) and version differences

• Permit definitions id format changed to UUID string
  • Fetch new permit definition ids GET a list of permit definitions
• All methods
  • All request/response parameters are now using snake case
  • Response parameters valid_from and valid_to are now formatted as follows: "2023-03-17T00:00:00+0200" -> +0000
• GET /v3/products/availability?valid_from={URL encoded date in ISO 8601}
  • valid_from is now request parameter instead of path variable, and it should be URL encoded
• POST /v3
  • Renamed request and response parameter licencePlate to license_plate_number
  • Unified operator specific data (e.g., payment, client, flight_information) under request parameter operator_data
  • Request and response parameters permit_definition_id are now UUID string
  • Response parameter created_at is in the description
• PUT /v3/{id}
  • Renamed request and response parameter licencePlate to license_plate_number
  • Unified operator specific data (e.g., payment, client, flight_information) under request parameter operator_data
  • Request and response parameters permit_definition_id are now string
  • Response parameter created_at is in the description