Support Center

Dokumentation XML API

Anbindung externer Systeme an die Vermietsoftware

XML-Schnittstelle

Allgemein

Mit Hilfe der XML-Schnittstelle ist es möglich eigene Anwendungen an die webbasierte Vermietsoftware anzukoppeln.

Bis auf die Anfrage zum Durchführen der Buchung (Aufruf per POST) werden alle Requests per GET an Vermietsoftware gesendet. Strings werden von Vermietsoftware base64enkodiert zurückgegeben. Jedem Request muß der Token in der Anfrage anhängen ansonsten wird die Anfrage zurückgewiesen.

Standard-Frontend in der Mietversion

Das Standardfrontend erreicht man immer mit dem Namen des Accounts vorgeschaltet vor der Subdomain. Der Account onlinedemo Autovermietung-Software hat somit die URL:

https://onlinedemo.avs.rent

Verfügbarkeit ermitteln

GET-Anfrage versenden:

$URL = $Autovermietung_Application_URL."xml.php?
aktion=CheckFree&start=".$datum_von."&stop=".$datum_bis."
&station_id={$station_id}&vermittler_id=".$vermittler_id."&token=".$token;

Parameter Beschreibung
Autovermietung_Application_URL URL der Applikation, von PHCOM
datum_von und datum_bis Unix Timestamp Werte der Anmietung
station_id ID der Station aus der Software
vermittler_id ID des Provisionsempfängers aus der Software
token Legen Sie in den Globalen Einstellungen selbst fest
anzahl_weiterer_fahrzeuge Bei aktivierter Option in den Globalen Einstellungen, die Anzahl zusätzlicher Ressourcen zu dem HauptRessource

Das Ergebnis ist ein Array mit Informationen zu allen verfügbaren Ressourcengruppen und den Tarifinfos. Strings werden von Vermietsoftware base64enkodiert zurückgegeben.

Rückgabe der Verfügbarkeitsanfrage

Zurück erhält man ein Objekt, in dem die Verfügbarkeit für die einzelnen Ressourcengruppen und Ressourcensubgruppen sowie der Preis und weitere Informationen gelistet werden. Strings werden base64enkodiert zurückgegeben. In dem Rückgabeobjekt steht die "row" für eine Ressourcenuntergruppe (Siehe dazu auch die Vermietsoftware-Dokumentation).

Zusammenstellen der Daten und Versenden an den Vermietsoftware-SERVER

Aus dem Rückgabeobjekt verwendet man eine Ressourcensubgruppe, die als verfügbar gekennzeichnet ist (verfuegbar=1 oder verfuegbar_bool=true) und stellt die Anfrage zusammen.

Temporäre Buchung durchführen

Um eine Temporäre Buchung durchzuführen, muss an die Software per POST folgender Befehl gesendet werden:

$arraySend["misc"]["fzg_gruppe"] = fzg_gruppe_sub_id;
$arraySend["misc"]["start"] = $if->start; //Unix Timestamp
$arraySend["misc"]["stop"] = $if->stop; //Unix Timestamp
$arraySend["misc"]["station_id"] = station_id;
$arraySend["misc"]["rueckgabeort_station_id"] = station_id; //Rückgabeort

Als Aktion muß "makeTempReservation" angegeben werden. Die Rückgabe ist analog "Buchung durchführen".

Als Rückgabe erhält man in einem Array folgende Parameter:

Die Temporäre Reservierung kann vom XML-Client wieder gelöscht werden. Wenn die Temporäre Reservierung nicht vom Frontend gelöscht wird, geschieht das automatisiert im Hintergrund.

Alternativ dazu kann bei der Hauptbuchung die buchung_id der temporären Buchung mit dem Parameter

$arraySend["temp_buchung_id"]

übergeben werden - die temporäre Buchung wird dann vom System zu einer vollständigen Buchung konvertiert.

Temporäre Buchung löschen

Die Temporäre Buchung wird unter Angabe der BuchungID mit einem GET-Befehl gelöscht.
Der Request-String setzt sich zusammen aus:

z.B.: $URL=$Autovermietung_Application_URL."xml.php?aktion=deleteTempReservation&buchung_id=".$buchung_id."&token=".$token;

Als Ergebnis wird der Erfolg der Aktion zurückgegeben.

Stationen ermitteln

Um die Stationsliste abzurufen verwenden Sie getStationen als Aktion. Das Antwortarray beinhaltet die Stations-ID und die dazugehörige Bezeichnung.

Beispiel: xml.php?aktion=getStationen

Freitextfelder Vorgang

Die im Internet verfügbaren Freitextfelder des Vorgangs werden mit der Aktion getFreitextfelder ermittelt. Die Rückgabe erfolgt in einem Array.

Beispiel: xml.php?aktion=getFreitextFelder

Freitextfelder Mieter

Die im Internet verfügbaren Freitextfelder des Mieters werden mit der Aktion getFreitextfelderPerson ermittelt. Die Rückgabe erfolgt in einem Array.

Beispiel: xml.php?aktion=getFreitextFelderPerson

Freitextfelder Fahrer

Die im Internet verfügbaren Freitextfelder des Fahrers werden mit der Aktion getFreitextfelderFahrer ermittelt. Die Rückgabe erfolgt in einem Array.

Beispiel: xml.php?aktion=getFreitextFelderFahrer

Frontend-Einstellungen

Es können eigene Frontends an Vermietsoftware angeschlossen werden. Wird das PHCOM-Frontend verwenden, werden mit dem Parameter loadSettings die Einstellungen für das Frontend ermittelt. In Vermietsoftware werden die Einstellungen unter Systemparameter - Frontend-Einstellungen verwaltet.

Beispiel: xml.php?aktion=loadSettings

Als Rückgabe erhält man ein Objekt mit der Bezeichnung der Einstellung und dem dazugehörigen Wert.

Login überprüfen

Es ist möglich wiederkehrende Kunden zu identifizieren, und zwar mit dem Nachnamen und der Kundennummer. Parameter, welche an die Software gesendet werden:

aktion checkLogin
nachname Der Nachname des Kunden, hinterlegt in Vermietsoftware
kundennummer Die Kundennummer - erhält der Kunde für gewöhnlich in einer Buchungs-Bestätigungs-eMail

Als Antwort erhält man auf den Request folgendes Array:

login true oder false. Bei true ist die Kombination gültig, bei false ungültig.
user_id Vermietsoftware-User-ID
rabatt Standard-Rabatt des Kunden
name Der Nachname des Kunden
vorname Der Vorname des Kunden
firma Hinterlegte Firma des Kunden
kundennummer Die Kundennummer
kundenkarte_nr Inhalt des Felds Kundenkarte aus der Personenverwaltung
email Die E-Mail-Adresse des Kunden
fahrer Die zugeordneten Fahrer für den Benutzer in einem Array

Verfügbare Artikel ermitteln

Um die für das Internet verfügbare Artikelliste abzurufen verwenden Sie getArtikel als Aktion. Das Antwortarray beinhaltet die Artikel-ID und die dazugehörige Bezeichnung. Wenn in den globalen Einstellungen der Parameter "Artikel auf Stationen eingrenzen verwenden" gesetzt ist, muss dem aufruf noch die Station mit "station_id=" übergeben werden.

Beispiel: xml.php?aktion=getArtikel

AGBs ermitteln

Um die aktuellen AGBs abzufragen verwendet man den Parameter aktion=getAGB

Beispiel: xml.php?aktion=getAGB

Länder

Um die verfügbaren Länder abzufragen verwendet man den Parameter aktion=getLaender

Beispiel: xml.php?aktion=getLaender

Führerscheinklassen

Um die verfügbaren Führerscheinklassen abzufragen verwendet man den Parameter aktion=getFuehrerscheinKlasse

Beispiel: xml.php?aktion=getFuehrerscheinKlasse

Ressourcengruppen

Die Ressourcengruppen ermitteln man dem Aufruf aktion=getFahrzeugGruppe

Beispiel: xml.php?aktion=getFahrzeugGruppe

Die Rückgabe erfolgt in einem Array mit folgenden Feldern:

ID ID der Ressourcenuntergruppe
image_filename Dateiname der hinterlegten Vorschaugraphik
bezeichnung Vollständige Bezeichnung der Ressourcengruppe
fzg_gruppe_sub Bezeichnung der Ressourcenuntergruppe
fzg_gruppe_sub_bemerkung In der Ressourcengruppenverwaltung hinterlegte Bemerkung
fzg_gruppe Bezeichnung der Ressourcengruppe

Mehr Informationen zu den Ressourcengruppen findet man in der Vermietsoftware Dokumentation.

Vorgangsinformationen ermitteln (JSON)

Informationen zu einem Vorgang ermittelt man mit dem Aufruf aktion=getFahrzeugGruppe

Beispiel: xml.php?aktion=getVorgangInfo&vorgang_nr=XXX

Die Rückgabe erfolgt in einem JSON-Array mit folgenden Feldern:

kunde_nachname Nachname des Kunden
kunde_vorname Vorname des Kunden
kunde_firma Firma
vorgang_nr Die Vorgangsnummer
rechnung_nr Rechnungsnnummer. Wenn diese 0 ist, wurde sie noch nicht vergeben
mietbeginn_datum Datum der Anmietung
gesamtbetrag_brutto Bruttobetrag
mwst_satz MwSt-Satz des Vorgangs
gesamtbetrag_netto Netto-Gesamtbetrag
offen_betrag Höhe des offenen Betrags
Positionen:
  • value: Einzelbetrag
  • bezeichnung: Postionen-Bezeichnung
  • anzahl: Anzahl (Menge)
Alle Positionen des Vorgangs

Zahlung verbuchen

Man kann einem Vorgang eine Zahlung zuordnen. Der Bezahlbetrag muss dem Offen-Betrag entsprechen, ansonsten wird der Call zurückgewiesen.

Beispiel: xml.php?aktion=setZahlung&vorgang_nr=XXX&betrag=120.12

Wenn die Zahlung erfolgreich verbucht wurde, erhält man ein TRUE bzw. FALSE wenn der Ausführung nicht erfolgreich war.

Als Zahlart wird die Zahlart aus dem Feld "Standard-Zahlart in 'Zahlungen-Schnellerfassung'" in den Globalen Einstellungen verwendet

Buchung durchführen

Array, was per POST an die AV-Software gesendet werden soll, zusammenstellen

//Buchungsdaten
$arraySend["misc"]["fzg_gruppe"] = fzg_gruppe_sub_id;
$arraySend["misc"]["start"] = $if->start; //Unix Timestamp
$arraySend["misc"]["stop"] = $if->stop; //Unix Timestamp
$arraySend["misc"]["station_id"] = station_id;
$arraySend["misc"]["rueckgabeort_station_id"] = station_id; //Rückgabeort

$arraySend["misc"]["kilometer"] = $if->kilometer;
$arraySend["misc"]["anzahl_gesamt_tage"] = $if->anzahl_gesamt_tage;
$arraySend["misc"]["preisliste_id"] = $if->preisliste_id;
$arraySend["misc"]["standard_mwst_satz"] = 19; //19% MwSt
$arraySend["misc"]["bemerkung_textarea"] = $if->bemerkung_textarea;
$arraySend["misc"]["preisliste_betrag"] = $if->preisliste_betrag;
$arraySend["misc"]["preisliste_bezeichnung"] = $if->preisliste_bezeichnung;
$arraySend["misc"]["option_id"] = option_id; //Aus preisliste_optionen oder Leer
$arraySend["misc"]["optionen_betrag"] = betrag;
$arraySend["misc"]["zahlart_id"] = 2 /*Rechnung*/;
$arraySend["misc"]["zahlbetrag"] = betrag; //Der Zahlbetrag für den Vorgang.
$arraySend["misc"]["anzahl_weiterer_fahrzeuge"] = x; //Die Anzahl weiterer Fahrzeuge welche mit dieser Buchung zusätzlich zum Hauptfahrzeug gebucht werden

//Personendaten
if($kunde_id>0)
{
$kunde = new user($kunde_id);
$arraySend["person"]["name"]=$kunde->user_data["name"];
$arraySend["person"]["vorname"]=$kunde->user_data["vorname"];
$arraySend["person"]["firma"]=$kunde->user_data["firma"];
$arraySend["person"]["strasse"]=$kunde->user_data["strasse"];
$arraySend["person"]["plz"]=$kunde->user_data["plz"];
$arraySend["person"]["ort"]=$kunde->user_data["ort"];
$arraySend["person"]["anrede_id"]=$kunde->user_data["anrede_id"]; //ID der Anrede aus den Systemparametern - Anrede
$arraySend["person"]["email"]=$kunde->user_data["email"];
$arraySend["person"]["handy"]=$kunde->user_data["handynr"];
$arraySend["person"]["telefon"]=$kunde->user_data["telefon"];
$arraySend["person"]["geburtstag"]=$kunde->user_data["geburtstag"];
}

//Anfügen von Artikeln
$arraySend["misc"]["artikel"][$artikel_id]["use"]=1; //Angabe das der Artikel verwendet werden soll
$arraySend["misc"]["artikel"][$artikel_id]["anzahl"]=X; //X enstpricht der Anzahl des Artikels

//Temporäre Buchung löschen (Optional)
$arraySend["temp_buchung_id"] = 1235;

PHP-Beispiel

Funktion, um Daten per Post mit PHP zu versenden

private function PostToHost($host, $path, $referer, $data_to_send)
{
$fp = fsockopen($host, 80);
//printf("Open!\n");
fputs($fp, "POST $path HTTP/1.1\r\n");
fputs($fp, "Host: $host\r\n");
fputs($fp, "Referer: $referer\r\n");
fputs($fp, "Content-type: application/x-www-form-urlencoded\r\n");
fputs($fp, "Content-length: ". strlen($data_to_send) ."\r\n");
fputs($fp, "Connection: close\r\n\r\n");
fputs($fp, $data_to_send);
//printf("Sent!\n");
while(!feof($fp))
{
$res .= fgets($fp, 128);
}
//printf("Done!\n");
fclose($fp);

return $res;
}


function insertBuchung($array)
{
global $AppServer, $AppServerPath, $token;

//Objekt serialisieren
$tmpObj = serialize($array);
$data = "v1=2&token=$token&aktion=makeReservation&tmpObj=$tmpObj";

$x = $this->PostToHost( $AppServer, "/$AppServerPath/xml.php", "https://avs.rent", $data);

$string = split("-----separator-----",$x);
$obj = simplexml_load_string($string[1]);
return $obj;
}

Im Antwortarray befindet sich die Vermietsoftware-Vorgangsnummer, mit der der Vorgang identifiziert wird.



Stand: 5. September 14