API Documentation

The Bookyt API allows external applications to connect to Bookyt. You can use it to retrieve master data, check availability, create bookings, record payments, or cancel operations.

This reference describes the technical use of api.php, the key access requirements, and the available endpoints.

Technical Basics

Base URL: https://<ihr-bookyt-account>/api.php

Area	Note
Transport	HTTPS is required.
Response formats	Most endpoints return JSON. Individual endpoints return PDF or plain text.

Authentication and Access

Topic	Description
Activation	The global setting `e->GlobaleEinstellungen['api_active']` must have the value `1`.
Token	The `token` parameter can be sent via `GET` or `POST` and must match `e->GlobaleEinstellungen['xml_token']`.
IP whitelist	If `e->GlobaleEinstellungen['xml_only_access_from_ip']` is set, `REMOTE_ADDR` must be included in the whitelist.

Load Protection and Limits

Rule	Behavior
Immediate check	If `getServerAuslastung() > 35`, the request is terminated early with `HTTP 400` and `{error: 'Server too busy. Try again later.'}`.
General throttling	If `Load >= 30`, `HTTP 503` is returned with a JSON error message.
Hourly limit	Approximately `1000` requests are allowed per hour. This is based on the `log_api` table for the previous one-hour period.
Response formats	Some endpoints intentionally return plain text such as `OK`, `TRUE`, or `FALSE`.

Error Patterns

Status	Format	Meaning
`200`	JSON, PDF, or plain text	Successful response.
`400`	JSON	Invalid request or busy guard.
`403`	JSON	Access denied or invalid parameters.
`503`	JSON	Load protection or request limit reached.

Conventions

Topic	Convention
Methods	Most endpoints use `GET`; individual endpoints use `POST` and are marked accordingly.
Date values	Unix timestamps in seconds are commonly used. Some endpoints accept German date values in the format `dd.mm.yyyy`.
Language	Content may include multilingual fields such as `_en`, `_es`, `_nl`, `_hr`, `_it`, `_pt`, or `_fr`.
IDs	IDs are generally numeric. Strings such as `no` may contain invoice numbers or online payment codes.

Endpoints with `call`

update_status

Property	Value
Method	`GET`
Authentication	Token/whitelist guards

Status update for a booking; optional mileage readings. For status=4, an invoice may be generated and sent by email.

Parameters:

Name	Type	Required	Description
`vorgang_nr`	int	yes	Invoice number
`status_id`	int	yes	-
`km_stand_ankunft`	int	no	-
`km_stand_abfahrt`	int	no	-
Response:

JSON: {success:true}

Notes: For status 4 and the setting ‘rueckgabe_abrechnen=1’, rechnungsnummer_rechnung is created, a PDF is generated, and it is sent by email.

locations

Property	Value
Method	`GET`
Authentication	Token/whitelist guards

Locations including optional opening hours.

Parameters:

Name	Type	Required	Description
`show`	string	no	’all’ shows all; otherwise filter: use_internet=1, aktiv=1, nicht_buchen=0
`open`	string	no	’true’ ⇒ opening-hours arrays; holidays/date exceptions are taken into account
Response:

JSON array: locations with fields (ID, caption, address, zip, place, state, street, opening_string, opening_times, opening_times_special, tel_nr,…).

articles

Property	Value
Method	`GET`
Authentication	Token/whitelist guards

Active articles available online, including category, files, and restrictions (groups/locations).

Response:

JSON array: normalized fields per article, ‘files’ (URLs), ‘categories’:[fahrzeuggruppe_sub_id], ‘stationen’:[station_id].

artikelpreise

Property	Value
Method	`GET`
Authentication	Token/whitelist guards

Article prices from PreisCheck for price list/period.

Parameters:

Name	Type	Required	Description
`preisliste_id`	int	yes	-
`mwst_satz`	number	yes	-
`start`	int\|date	yes	-
`stop`	int\|date	yes	-
Response:

JSON array: price data (from PreisCheck).

tac

Property	Value
Method	`GET`
Authentication	Token/whitelist guards

General Terms and Conditions (multilingual).

Response:

JSON: {tac, tac_en, tac_es, tac_nl, tac_it, tac_fr, tac_hr, tac_pt}

news

Property	Value
Method	`GET`
Authentication	Token/whitelist guards

Latest 10 news items (newsboard) without Schnappi.

Response:

JSON array: [{betreff, mitteilung, datum}]

Name	Type	Required	Description
`fahrzeuggruppe_id`	int	no	Filter
Response:

get_booking

Property	Value
Method	`GET`
Authentication	Token/whitelist guards

Retrieve a transaction by invoice number or online payment code.

Parameters:

Name	Type	Required	Description
`no`	string	yes	<=30 characters: numeric ⇒ rechnungsnummer, otherwise onlinezahlung_code
Response:

JSON: {vorgang:{...}} including customer, amounts, VAT, positions (cleaned). 'error' if not found.

set_payment

Property	Value
Method	`GET`
Authentication	Token/whitelist guards

Record payment against a transaction (quick entry).

Parameters:

Name	Type	Required	Description
`no`	string	yes	Invoice number
`amount`	number	yes	>0
`zahlart_id`	int	no	otherwise default from GlobaleEinstellungen
Response:

Plain text: TRUE or FALSE.

reservierungsbestaetigungPDF

Property	Value
Method	`GET`
Authentication	Token/whitelist guards

Download the reservation confirmation as a PDF.

Parameters:

Name	Type	Required	Description
`buchung_id`	int	yes	-
Response:

Content-Type: application/pdf; Content-Disposition: download; filename=confirmation_.pdf

get_all_bookings

Property	Value
Method	`GET`
Authentication	Token/whitelist guards

All bookings in the interval, including article list (from positions fp%).

Parameters:

Name	Type	Required	Description
`date`	int\|date	no	Default: today
`date_stop`	int\|date	no	Defaults to same as ‘date’
`category_id`	int	no	Filter
`station_id`	int	no	Filter
Response:

JSON: {bookings:[...], fahrzeuge:[...], fahrzeuge_sperren:[...], fahrzeuge_station:[...], stationen:[...]}

calculate_tarif

Property	Value
Method	`GET`
Authentication	Token/whitelist guards

Rate calculation (PreisCheck.InitOhneB_ID).

Parameters:

Name	Type	Required	Description
`start`	int\|date	yes	-
`stop`	int\|date	yes	-
`category_id`	int	yes	-
`station_id`	int	yes	-
`kunde_id`	int	no	-
`kilometer`	number	no	-
`rabatt_satz`	number	no	-
`only_online_tarif`	bool	no	’true’ to use only online rates
Response:

JSON: complete PreisCheck object state (serialized).

get_bookings

Property	Value
Method	`GET`
Authentication	Token/whitelist guards

Bookings in the interval (compact, without article GC), optionally selecting an individual booking.

Parameters:

Name	Type	Required	Description
`date`	int\|date	no	Default: today
`date_stop`	int\|date	no	Defaults to same as ‘date’
`station_id`	int	no	-
`buchung_id`	int	no	sets a wide time range of ±10y
`category_id`	int	no	Filter by subgroup
Response:

JSON array keyed by ID with times, location, subgroup, status, customer data, vorgang_nr, booking code, anlage_datum.

customerlist

Property	Value
Method	`GET`
Authentication	Token/whitelist guards

Customer list (personenv2.sql query), excluding types (6,7).

Response:

JSON array: customer fields by query.

ressources

Property	Value
Method	`GET`
Authentication	Token/whitelist guards

Resources/vehicles including damage records and blocks as of the reference date.

Parameters:

Name	Type	Required	Description
`category_id`	int	no	Filter
`station_id`	int	no	Filter
`datum`	int	no	Default now()
Response:

JSON array: vehicles (cleaned fields), plus damages[] and sperren[].

damages

Property	Value
Method	`GET`
Authentication	Token/whitelist guards

Damage records for a vehicle.

Parameters:

Name	Type	Required	Description
`fahrzeug_id`	int	yes	-
Response:

JSON: {:[...]} or {error:true, message:'...'}

events

Property	Value
Method	`GET`
Authentication	Token/whitelist guards + module active

Event dates with capacity, articles, regions, files, group-specific prices, and free-text categories.

Response:

JSON array: extensive structure per event date including capacity_

fields. Notes: Only if e->GlobaleEinstellungen[‘modul_eventplaner’]==1. Returns future events (start>now), online=1.

reporting (chat_id)

Property	Value
Method	`GET`
Authentication	Token/whitelist guards

Executes a saved GPT/chat query (SQL) in the reporting user context.

Parameters:

Name	Type	Required	Description
`chat_id`	int	yes	-
Response:

JSON array: query records; if not found, HTTP 400 + {error:‘GPT Query not fo und’}.

reporting (query_id)

Property	Value
Method	`GET`
Authentication	Token/whitelist guards

Executes a saved query (formulare_query), optionally with filters.

Parameters:

Name	Type	Required	Description
`query_id`	int	yes	-
`filter[]`	json	no	multiple; added to the WHERE clause
Response:

JSON array: results; if reporting tables are missing, an empty array is returned.

customer_details

Property	Value
Method	`GET`
Authentication	Token/whitelist guards

Detailed data for a customer (person object).

Parameters:

Name	Type	Required	Description
`kunde_id`	int	yes	-
Response:

JSON: person→person_array

getcustomer

Property	Value
Method	`GET`
Authentication	Token/whitelist guards

Raw data for a person (cleaned of sensitive/ID fields).

Parameters:

Name	Type	Required	Description
`ID`	int	yes	-
Response:

JSON: Person fields without ID/password etc.

updatecustomer

Property	Value
Method	`POST`
Authentication	Token/whitelist guards

Update customer master data.

Parameters:

Name	Type	Required	Description
`ID`	int	yes	-
`form`	object	yes	Key-value data for the fields to update
Response:

JSON: {success:true}

contract

Property	Value
Method	`GET`
Authentication	Token/whitelist guards

Rental contract as PDF (inline) via unique_id.

Parameters:

Name	Type	Required	Description
`unique_id`	string	yes	alphanumeric
Response:

Content-Type: application/pdf; Content-Disposition: inline; filename=contract_.pdf

fahrtenbuch

Property	Value
Method	`GET`
Authentication	Token/whitelist guards

Vehicle logbook entries for a vehicle within the period.

Parameters:

Name	Type	Required	Description
`start`	int\|date	yes	Unix timestamp or German date
`stop`	int\|date	yes	-
`fahrzeug_id`	int	yes	-
Response:

JSON: {fehler:bool, meldung?:string, fahrtenbuch:[...]}

Notes: Maximum 3 years. Validation errors return fehler=true and a message.

insertFahrtenbuch

Property	Value
Method	`GET`
Authentication	Token/whitelist guards

Create a logbook entry.

Parameters:

Name	Type	Required	Description
`user_id`	int	yes	-
`start`	int	yes	TS
`stop`	int	yes	TS
`station_id`	int	yes	-
`station_id_stop`	int	yes	-
`start_km`	int	yes	-
`stop_km`	int	yes	-
`fahrzeug_id`	int	yes	-
`bemerkung`	string	no	-
Response:

JSON: {success:true|false, meldung?:string}

availability

Property	Value
Method	`GET`
Authentication	Token/whitelist guards

Availability and price for time/location/category/vehicle.

Parameters:

Name	Type	Required	Description
`start`	string	yes	ISO/date; parsed to TS
`stop`	string	yes	-
`location_id`	int	yes	-
`category_id`	int	yes	-
`fahrzeug_id`	int	no	-
`kunde_id`	int	no	-
`kilometer`	number	no	-
`rabatt_satz`	number	no	-
`only_online_tarif`	bool	no	-
Response:

JSON: {available:bool, error:string|'', notice:string, vatrate:number, vatid:int, price:number, price_net:number, price_detail:object, price_valid_fares:[...], preisliste_id:int}

Notes:

newBooking

Property	Value
Method	`POST`
Authentication	Token/whitelist guards

Create a new booking; optionally creates a customer, calculates prices/positions, and returns receipt URL/QR.

Parameters:

Name	Type	Required	Description
`start`	string	yes	-
`stop`	string	yes	-
`location_id`	int	yes	-
`category_id`	int	yes	-
`fahrzeug_id`	int	no	Automatic assignment possible (xml_kennzeichen_automatisch)
`kunde_id`	int	no	-
`kilometer`	number	no	-
`rabatt_satz`	number	no	-
`only_online_tarif`	bool	no	-
`vatid`	int	yes	-
`vatrate`	number	yes	-
`zahlart_id`	int	yes	-
`voucher_code`	string	no	-
`remarks`	string	no	internal
`remarks_customer`	string	no	saved for the customer
`customer_id`	int	no	if available
`customer`	object	yes	if customer_id is empty {name, firstname, email, anrede_id, mobil, adresse, plz, ort, land_id, geburtsdatum}
`positionen`	array	yes	List of objects: {type(1=rate/otherwise article), amount, price_net, caption, artikel_id?}
Response:

JSON: {success:bool, remarks, errormsg, vorgang_nr:int|null, buchung_id:int|null, quittung_url, qr_code}

Notes: Checks availability via checkBuchungFreeV2. Sets status/purpose from GlobaleEinstellungen.

cancel

Property	Value
Method	`GET`
Authentication	Token/whitelist guards

Cancels a booking by transaction number.

Parameters:

Name	Type	Required	Description
`vorgang_nr`	int	yes	-
Response:

JSON: {success:bool, notice?:string}

updateRessources

Property	Value
Method	`POST`
Authentication	Token/whitelist guards

Set multiple vehicle-location assignments for a date.

Parameters:

Name	Type	Required	Description
`fahrzeuge`	array	yes	Array of {fahrzeug_id, datum, station_id}
Response:

No explicit JSON (no echo) – usually HTTP 200 without content.

Notes: If the location has changed, insertStation() is called.

updateRessource

Property	Value
Method	`POST`
Authentication	Token/whitelist guards

Create/update an individual vehicle (master data/status/location/assignment).

Parameters:

Name	Type	Required	Description
`fahrzeug_id`	int	yes	0 ⇒ create new
`fzg`	object	yes	Fields: bezeichnung, fahrzeug_nr, weitere_fahrzeug_nummer, schluesselnr1, briefnr, aktivierdatum, fahrgestellnummer, freitext?, kennzeichen?, deaktivierdatum?, status_id?, fahrzeuggruppe_sub_id (when creating), datum, station_id
Response:

JSON: {success:bool, fahrzeug_id:int}

sendEmail

Property	Value
Method	`GET`
Authentication	Token/whitelist guards

Sends a prepared email (template), optionally with a generated PDF attachment.

Parameters:

Name	Type	Required	Description
`email_id`	int	yes	-
`ds_id`	int	yes	Record ID
`lang`	string	no	-
`email_to`	string	yes	Recipient address
`print_formular_id`	int	no	If set, a document is generated first and attached
Response:

JSON: {success:true}

paymentTypes

Property	Value
Method	`GET`
Authentication	Token/whitelist guards

List of active payment types for persons.

Response:

JSON array: [{ID, bezeichnung, bezeichnung_en, bemerkung}]