API Dokumentation

API-Dokumentation

Die Bookyt-API ermöglicht die Anbindung externer Anwendungen an Bookyt. Sie können darüber Stammdaten abrufen, Verfügbarkeiten prüfen, Buchungen erstellen, Zahlungen verbuchen oder Vorgänge stornieren.

Diese Referenz beschreibt die technische Nutzung von api.php, die wichtigsten Zugriffsvoraussetzungen und die verfügbaren Endpunkte.

Technische Grundlagen

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

Bereich	Hinweis
Transport	HTTPS wird vorausgesetzt.
Rückgabeformate	Die meisten Endpunkte liefern JSON. Einzelne Endpunkte liefern PDF oder Plaintext.

Authentifizierung und Zugriff

Thema	Beschreibung
Aktivierung	Die globale Einstellung `e->GlobaleEinstellungen['api_active']` muss den Wert `1` haben.
Token	Der Parameter `token` kann per `GET` oder `POST` übertragen werden und muss `e->GlobaleEinstellungen['xml_token']` entsprechen.
IP-Whitelist	Wenn `e->GlobaleEinstellungen['xml_only_access_from_ip']` gesetzt ist, muss `REMOTE_ADDR` in der Whitelist enthalten sein.

Lastschutz und Limits

Regel	Verhalten
Sofort-Check	Bei `getServerAuslastung() > 35` wird der Request frühzeitig mit `HTTP 400` und `{error: 'Server too busy. Try again later.'}` beendet.
Generelles Throttling	Bei `Load >= 30` wird `HTTP 503` mit einer JSON-Fehlermeldung zurückgegeben.
Stundenlimit	Pro Stunde sind ungefähr `1000` Requests zulässig. Grundlage ist die Tabelle `log_api` im letzten Stundenzeitraum.
Antwortformate	Einige Endpunkte liefern bewusst Plaintext wie `OK`, `TRUE` oder `FALSE`.

Fehlerbilder

Status	Format	Bedeutung
`200`	JSON, PDF oder Plaintext	Erfolgreiche Antwort.
`400`	JSON	Ungültige Anfrage oder Busy-Guard.
`403`	JSON	Zugriff verweigert oder ungültige Parameter.
`503`	JSON	Lastschutz oder Requestlimit erreicht.

Konventionen

Thema	Konvention
Methoden	Die meisten Endpunkte verwenden `GET`; einzelne Endpunkte verwenden `POST` und sind entsprechend gekennzeichnet.
Datumswerte	Häufig werden Unix-Timestamps in Sekunden verwendet. Einige Endpunkte akzeptieren deutsche Datumsangaben im Format `dd.mm.yyyy`.
Sprache	Inhalte können mehrsprachige Felder wie `_en`, `_es`, `_nl`, `_hr`, `_it`, `_pt` oder `_fr` enthalten.
IDs	IDs sind in der Regel numerisch. Strings wie `no` können Rechnungsnummern oder Onlinezahlungscodes enthalten.

Endpunkte mit `call`

update_status

Eigenschaft	Wert
Methode	`GET`
Authentifizierung	Token/Whitelist-Guards

Status-Update einer Buchung; optional km-Stände. Bei Status=4 ggf. Rechnung generieren und per E-Mail versenden.

Parameter:

Name	Typ	Erforderlich	Beschreibung
`vorgang_nr`	int	ja	Rechnungsnummer
`status_id`	int	ja	-
`km_stand_ankunft`	int	nein	-
`km_stand_abfahrt`	int	nein	-
Antwort:

JSON: {success:true}

Hinweise: Bei Status 4 und Setting ‘rueckgabe_abrechnen=1’ wird rechnungsnummer_rechnung erzeugt, PDF erstellt und per Mail versendet.

locations

Eigenschaft	Wert
Methode	`GET`
Authentifizierung	Token/Whitelist-Guards

Stationen inkl. optionaler Öffnungszeiten.

Parameter:

Name	Typ	Erforderlich	Beschreibung
`show`	string	nein	’all’ zeigt alle, sonst Filter: use_internet=1, aktiv=1, nicht_buchen=0
`open`	string	nein	’true’ ⇒ Öffnungszeiten-Arrays; Feiertage/Datumsausnahmen berücksichtigt
Antwort:

JSON Array: Stationen mit Feldern (ID, caption, address, zip, place, state, street, opening_string, opening_times, opening_times_special, tel_nr,…).

articles

Eigenschaft	Wert
Methode	`GET`
Authentifizierung	Token/Whitelist-Guards

Aktive, im Internet verfügbare Artikel inkl. Kategorie, Dateien, Einschränkungen (Gruppen/Stationen).

Antwort:

JSON Array: pro Artikel normalisierte Felder, ‘files’ (URLs), ‘categories’:[fahrzeuggruppe_sub_id], ‘stationen’:[station_id].

artikelpreise

Eigenschaft	Wert
Methode	`GET`
Authentifizierung	Token/Whitelist-Guards

Artikelpreise aus PreisCheck für Preisliste/Zeitraum.

Parameter:

Name	Typ	Erforderlich	Beschreibung
`preisliste_id`	int	ja	-
`mwst_satz`	number	ja	-
`start`	int\|date	ja	-
`stop`	int\|date	ja	-
Antwort:

JSON Array: Preisdaten (vom PreisCheck).

tac

Eigenschaft	Wert
Methode	`GET`
Authentifizierung	Token/Whitelist-Guards

Allgemeine Geschäftsbedingungen (mehrsprachig).

Antwort:

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

news

Eigenschaft	Wert
Methode	`GET`
Authentifizierung	Token/Whitelist-Guards

Neueste 10 News (newsboard) ohne Schnappi.

Antwort:

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

Name	Typ	Erforderlich	Beschreibung
`fahrzeuggruppe_id`	int	nein	Filter
Antwort:

get_booking

Eigenschaft	Wert
Methode	`GET`
Authentifizierung	Token/Whitelist-Guards

Vorgang per Rechnungsnummer oder Onlinezahlungs-Code abrufen.

Parameter:

Name	Typ	Erforderlich	Beschreibung
`no`	string	ja	<=30 Zeichen: numeric ⇒ rechnungsnummer, sonst onlinezahlung_code
Antwort:

JSON: {vorgang:{...}} inkl. Kunde, Beträge, MwSt, Positionen (bereinigt). 'error' falls nicht gefunden.

set_payment

Eigenschaft	Wert
Methode	`GET`
Authentifizierung	Token/Whitelist-Guards

Zahlung auf Vorgang verbuchen (Schnellerfassung).

Parameter:

Name	Typ	Erforderlich	Beschreibung
`no`	string	ja	Rechnungsnummer
`amount`	number	ja	>0
`zahlart_id`	int	nein	sonst Default aus GlobaleEinstellungen
Antwort:

Plaintext: TRUE oder FALSE.

reservierungsbestaetigungPDF

Eigenschaft	Wert
Methode	`GET`
Authentifizierung	Token/Whitelist-Guards

Download der Reservierungsbestätigung als PDF.

Parameter:

Name	Typ	Erforderlich	Beschreibung
`buchung_id`	int	ja	-
Antwort:

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

get_all_bookings

Eigenschaft	Wert
Methode	`GET`
Authentifizierung	Token/Whitelist-Guards

Alle Buchungen im Intervall inkl. Artikelliste (aus Positionen fp%).

Parameter:

Name	Typ	Erforderlich	Beschreibung
`date`	int\|date	nein	Standard heute
`date_stop`	int\|date	nein	Standard wie ‘date’
`category_id`	int	nein	Filter
`station_id`	int	nein	Filter
Antwort:

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

calculate_tarif

Eigenschaft	Wert
Methode	`GET`
Authentifizierung	Token/Whitelist-Guards

Tarifberechnung (PreisCheck.InitOhneB_ID).

Parameter:

Name	Typ	Erforderlich	Beschreibung
`start`	int\|date	ja	-
`stop`	int\|date	ja	-
`category_id`	int	ja	-
`station_id`	int	ja	-
`kunde_id`	int	nein	-
`kilometer`	number	nein	-
`rabatt_satz`	number	nein	-
`only_online_tarif`	bool	nein	’true’ um nur Online-Tarife zu nutzen
Antwort:

JSON: kompletter PreisCheck-Objektzustand (serialisiert).

get_bookings

Eigenschaft	Wert
Methode	`GET`
Authentifizierung	Token/Whitelist-Guards

Buchungen im Intervall (kompakter, ohne Artikel-GC) – optional Einzelauswahl.

Parameter:

Name	Typ	Erforderlich	Beschreibung
`date`	int\|date	nein	Standard heute
`date_stop`	int\|date	nein	Standard wie ‘date’
`station_id`	int	nein	-
`buchung_id`	int	nein	setzt breiten Zeitraum ±10y
`category_id`	int	nein	Filter nach Sub-Gruppe
Antwort:

JSON Array keyed by ID mit Zeiten, Station, Sub-Gruppe, Status, Kundendaten, Vorgang_nr, Buchungscode, anlage_datum.

customerlist

Eigenschaft	Wert
Methode	`GET`
Authentifizierung	Token/Whitelist-Guards

Kundenliste (Query personenv2.sql) exklusive Typen (6,7).

Antwort:

JSON Array: Kundenfelder je Query.

ressources

Eigenschaft	Wert
Methode	`GET`
Authentifizierung	Token/Whitelist-Guards

Ressourcen/Fahrzeuge inkl. Schäden und Sperren zum Stichtag.

Parameter:

Name	Typ	Erforderlich	Beschreibung
`category_id`	int	nein	Filter
`station_id`	int	nein	Filter
`datum`	int	nein	Standard now()
Antwort:

JSON Array: Fahrzeuge (bereinigte Felder), dazu damages[] und sperren[].

damages

Eigenschaft	Wert
Methode	`GET`
Authentifizierung	Token/Whitelist-Guards

Schäden eines Fahrzeugs.

Parameter:

Name	Typ	Erforderlich	Beschreibung
`fahrzeug_id`	int	ja	-
Antwort:

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

events

Eigenschaft	Wert
Methode	`GET`
Authentifizierung	Token/Whitelist-Guards + Modul aktiv

Event-Termine mit Kapazität, Artikeln, Regionen, Dateien, gruppenspezifischen Preisen und Freitext-Kategorien.

Antwort:

JSON Array: pro Event-Datum umfangreiche Struktur inkl. capacity_

Felder. Hinweise: Nur wenn e->GlobaleEinstellungen[‘modul_eventplaner’]==1. Liefert zukünftige (start>now), online=1.

reporting (chat_id)

Eigenschaft	Wert
Methode	`GET`
Authentifizierung	Token/Whitelist-Guards

Führt gespeicherte GPT/Chat-Query (SQL) im Reporting-User-Kontext aus.

Parameter:

Name	Typ	Erforderlich	Beschreibung
`chat_id`	int	ja	-
Antwort:

JSON Array: Datensätze der Query; bei Nichtfinden HTTP 400 + {error:‘GPT Query not fo und’}.

reporting (query_id)

Eigenschaft	Wert
Methode	`GET`
Authentifizierung	Token/Whitelist-Guards

Führt gespeicherte Query (formulare_query) aus, optional mit Filtern.

Parameter:

Name	Typ	Erforderlich	Beschreibung
`query_id`	int	ja	-
`filter[]`	json	nein	mehrfach; wird zur WHERE-Klausel addiert
Antwort:

JSON Array: Ergebnisse; wenn Reporting-Tabellen fehlen, leeres Array.

customer_details

Eigenschaft	Wert
Methode	`GET`
Authentifizierung	Token/Whitelist-Guards

Detaildaten eines Kunden (Personenobjekt).

Parameter:

Name	Typ	Erforderlich	Beschreibung
`kunde_id`	int	ja	-
Antwort:

JSON: person→person_array

getcustomer

Eigenschaft	Wert
Methode	`GET`
Authentifizierung	Token/Whitelist-Guards

Rohdaten einer Person (bereinigt um sensible/ID-Felder).

Parameter:

Name	Typ	Erforderlich	Beschreibung
`ID`	int	ja	-
Antwort:

JSON: Personenfelder ohne ID/Passwort etc.

updatecustomer

Eigenschaft	Wert
Methode	`POST`
Authentifizierung	Token/Whitelist-Guards

Kundenstammdaten aktualisieren.

Parameter:

Name	Typ	Erforderlich	Beschreibung
`ID`	int	ja	-
`form`	object	ja	Key-Value der zu aktualisierenden Felder
Antwort:

JSON: {success:true}

contract

Eigenschaft	Wert
Methode	`GET`
Authentifizierung	Token/Whitelist-Guards

Mietvertrag als PDF (inline) über unique_id.

Parameter:

Name	Typ	Erforderlich	Beschreibung
`unique_id`	string	ja	alphanumerisch
Antwort:

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

fahrtenbuch

Eigenschaft	Wert
Methode	`GET`
Authentifizierung	Token/Whitelist-Guards

Fahrtenbuch-Einträge eines Fahrzeugs im Zeitraum.

Parameter:

Name	Typ	Erforderlich	Beschreibung
`start`	int\|date	ja	Unix-TS oder dt. Datum
`stop`	int\|date	ja	-
`fahrzeug_id`	int	ja	-
Antwort:

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

Hinweise: Maximal 3 Jahre. Validierungsfehler liefern fehler=true und eine Meldung.

insertFahrtenbuch

Eigenschaft	Wert
Methode	`GET`
Authentifizierung	Token/Whitelist-Guards

Fahrtenbuch-Eintrag anlegen.

Parameter:

Name	Typ	Erforderlich	Beschreibung
`user_id`	int	ja	-
`start`	int	ja	TS
`stop`	int	ja	TS
`station_id`	int	ja	-
`station_id_stop`	int	ja	-
`start_km`	int	ja	-
`stop_km`	int	ja	-
`fahrzeug_id`	int	ja	-
`bemerkung`	string	nein	-
Antwort:

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

availability

Eigenschaft	Wert
Methode	`GET`
Authentifizierung	Token/Whitelist-Guards

Verfügbarkeit & Preis für Zeit/Station/Kategorie/Fahrzeug.

Parameter:

Name	Typ	Erforderlich	Beschreibung
`start`	string	ja	ISO/Datum; wird zu TS geparst
`stop`	string	ja	-
`location_id`	int	ja	-
`category_id`	int	ja	-
`fahrzeug_id`	int	nein	-
`kunde_id`	int	nein	-
`kilometer`	number	nein	-
`rabatt_satz`	number	nein	-
`only_online_tarif`	bool	nein	-
Antwort:

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}

Hinweise:

newBooking

Eigenschaft	Wert
Methode	`POST`
Authentifizierung	Token/Whitelist-Guards

Neue Buchung anlegen; legt optional Kunde an, berechnet Preise/Positionen und liefert Quittungs-URL/QR.

Parameter:

Name	Typ	Erforderlich	Beschreibung
`start`	string	ja	-
`stop`	string	ja	-
`location_id`	int	ja	-
`category_id`	int	ja	-
`fahrzeug_id`	int	nein	Automatische Zuweisung möglich (xml_kennzeichen_automatisch)
`kunde_id`	int	nein	-
`kilometer`	number	nein	-
`rabatt_satz`	number	nein	-
`only_online_tarif`	bool	nein	-
`vatid`	int	ja	-
`vatrate`	number	ja	-
`zahlart_id`	int	ja	-
`voucher_code`	string	nein	-
`remarks`	string	nein	intern
`remarks_customer`	string	nein	wird beim Kunden gespeichert
`customer_id`	int	nein	falls vorhanden
`customer`	object	ja	wenn customer_id leer {name, firstname, email, anrede_id, mobil, adresse, plz, ort, land_id, geburtsdatum}
`positionen`	array	ja	Liste mit Objekten: {type(1=Tarif/sonst Artikel), amount, price_net, caption, artikel_id?}
Antwort:

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

Hinweise: Prüft Verfügbarkeit via checkBuchungFreeV2. Setzt Status/Zweck aus GlobaleEinstellungen.

cancel

Eigenschaft	Wert
Methode	`GET`
Authentifizierung	Token/Whitelist-Guards

Storniert Buchung per Vorgangsnummer.

Parameter:

Name	Typ	Erforderlich	Beschreibung
`vorgang_nr`	int	ja	-
Antwort:

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

updateRessources

Eigenschaft	Wert
Methode	`POST`
Authentifizierung	Token/Whitelist-Guards

Mehrere Fahrzeug-Station-Zuordnungen zum Datum setzen.

Parameter:

Name	Typ	Erforderlich	Beschreibung
`fahrzeuge`	array	ja	Array von {fahrzeug_id, datum, station_id}
Antwort:

Kein explizites JSON (kein echo) – in der Regel HTTP 200 ohne Inhalt.

Hinweise: Bei geänderter Station wird insertStation() aufgerufen.

updateRessource

Eigenschaft	Wert
Methode	`POST`
Authentifizierung	Token/Whitelist-Guards

Einzelnes Fahrzeug anlegen/aktualisieren (Stammdaten/Status/Station/Zugehörigkeit).

Parameter:

Name	Typ	Erforderlich	Beschreibung
`fahrzeug_id`	int	ja	0 ⇒ Neuanlage
`fzg`	object	ja	Felder: bezeichnung, fahrzeug_nr, weitere_fahrzeug_nummer, schluesselnr1, briefnr, aktivierdatum, fahrgestellnummer, freitext?, kennzeichen?, deaktivierdatum?, status_id?, fahrzeuggruppe_sub_id (bei Neuanlage), datum, station_id
Antwort:

JSON: {success:bool, fahrzeug_id:int}

sendEmail

Eigenschaft	Wert
Methode	`GET`
Authentifizierung	Token/Whitelist-Guards

Versendet eine vorbereitete E-Mail (Template) optional mit generiertem PDF-Anhang.

Parameter:

Name	Typ	Erforderlich	Beschreibung
`email_id`	int	ja	-
`ds_id`	int	ja	Datensatz-ID
`lang`	string	nein	-
`email_to`	string	ja	Empfängeradresse
`print_formular_id`	int	nein	Wenn gesetzt, wird zuvor ein Dokument erzeugt und angehängt
Antwort:

JSON: {success:true}

paymentTypes

Eigenschaft	Wert
Methode	`GET`
Authentifizierung	Token/Whitelist-Guards

Liste aktiver Zahlungsarten für Personen.

Antwort:

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