Die Xovi-API stellt eine Programmierschnittstelle zur Xovi Software dar. Über diese ist es Ihnen möglich, ausgewählte Funktionen der Xovi Suite aus eigenen Programmen heraus abzurufen und somit in Ihre täglichen Geschäftsprozesse automatisiert einzubinden.

Newsletter
Tragen Sie sich im Newsletter ein, um über Änderungen bzw. Erweiturungen der API informiert zu werden.

Voraussetzungen
Um Daten über die API von Ihrer Software aus aufrufen zu können, benötigen Sie einen Benutzeraccount (hinreichend – https://order.xovi.de/) und einen Zugangsschlüssel (notwendig – siehe dazu den folgenden Abschnitt ‚Authentifizierung‘). Darüber hinaus muss der Client von dem Sie den API-Request starten HTTP fähig sein.

Authentifizierung
Neben dem Benutzer Account ist der API-Key für den Zugriff auf die Service-Methoden der Schnittstelle erforderlich. Ihren persönlichen API-Schlüssel bekommen Sie über das Xovi Tool (https://suite.xovi.net) im Bereich “Account” unter “API Dashboard”. Haben Sie diesen Schlüssel, müssen Sie ihn bei jedem Zugriff auf die API als Wert im Parameter ‚key‘ mit übergeben.

Kostenmodell
Das Kostenmodell basiert auf einem Credit-System. Je nach Benutzertyp steht Ihnen ein Credit-Rahmen in einem festgelegten Zeitraum zur Verfügung. Eine Übersicht Ihres Credit-Rahmens finden Sie ebenfalls auf dem Api Dashboard.
Darüber hinaus können Sie zu dem Credit-Rahmen, der Ihrem Benutzeraccount zugeordnet ist, nach Bedarf eine individuelle Anzahl von Credits hinzubuchen. Bitte kontaktieren Sie uns dafür persönlich.

Beispiel für Ihren persönlichen Credit-Rahmen:
PRO Benutzer Account (100.000 Credits) + 20.000 Credits (hinzugebucht) = 120.000 Credits pro Intervall (Ein Intervall entspricht 28 Tagen)

Sie können Ihren Kreditumfang zu jedem Zeitpunkt ohne Belastung Ihres Credit-Rahmens sowohl über die API (getCreditstate) , als auch über das Dashboard überwachen, das Sie über das Xovi Tool im Bereich Account unter API Dashboard finden.

Der Credit-Rahmen wird abhängig von der in Anspruch genommenen Service-Methode belastet. Die jeweiligen Kosten der einzelnen Servicefunktionen können Sie der Funktionenreferenz entnehmen. Bezieht sich die Funktion ausschließlich auf Benutzerdaten, wird Ihr Credit-Rahmen nicht belastet!

Außerdem gibt es zwei Möglichkeiten, auf welche Weise die Kosten für eine Funktion berechnet werden. Wir unterscheiden hierbei zwischen den beiden Berechnungsverfahren ‚Call‘ und ‚Row‘. Das Call-Verfahren ist statisch. Was bedeutet, dass pro Funktionsaufruf ein fester Betrag berechnet wird (unabhängig von der Anzahl der Zeilen, die das Ergebnis zurückliefert). Die Row-Funktion hingegen ist dynamisch. Dabei wird einem Paket von Datensätzen (festgelegte Anzahl von Ergebniszeilen) ein Betrag zugewiesen. Der Betrag für einen Funktionsaufruf ist dann das Produkt aus den Kosten für ein Paket und der Anzahl der übertragenen Pakete.

Formatierung / Zeichensatz
Als Zeichensatz wird in der gesamten API UTF-8 verwendet.
Die Rückgabedaten können in einem gewünschten (per Parameter ‘format’ übergebenen) Format ausgegeben werden. Zur Wahl stehen die Formate JSON und XML. Die Funktion getPdf des Services Report unterstützt zusätzlich das Format PDF. Wird ein Format nicht explizit übergeben, werden die Rückgabedaten formatiert in JSON zurückgegeben.

Beispiel

<?php
// API-Root
$root = 'https://suite.xovi.net/api/';

$arrayParams = array(
    'service' => 'user',
    'method'  => 'getCreditstate',
    'key'     => 'myPersonalKey',
    'format'  => 'json',
);

// Build URL params
$getParams = implode('/',$arrayParams);

// Build final request URL
$requestURL = $root . $getParams;

// Request
if (!function_exists('curl_init')) die('cURL not available');

$ch = curl_init();
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($ch, CURLOPT_URL, $requestURL);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// Download the given URL
$output = curl_exec($ch);

// Close the cURL resource, and free system resources
curl_close($ch);

// Print result
echo $output;
?>

Mögliches Ergebnis (JSON):

{
   "apiErrorCode":0,
   "apiErrorMessage":"0k.",
   "apiResult":{
      "creditamount":1000,
      "additionalCreditamount":5000,
      "bookedCreditamount":100000,
      "refillintervall":4,
      "lastrefill":"2013-03-08 15:00:00",
      "creditsleft":5280,
      "creditsused":720
   }
}