API REFERENZ

Einleitung

{
    api: {
        endpoint: "https://api.avanova.de/v1",
        version: "1.0",
        release: "20161026",
        author: "NOVA Building IT GmbH"
    }
}

Um die Entwicklung und die Anbindung an die NOVA AVA Schnittstelle für Entwickler so einfach wie möglich zu gestalten, haben wir unsere API resourcenorientiert auf Basis von REST entwickelt. Die Kommunikationssprache zwischen der API und dem Endpunkt ist immer das JSON-Format.

Sollten bei der Verwendung unserer Schnittstelle Fragen oder Problemen auftreten, zögern Sie nicht sich bei unserem Support-Team zu melden:
support@novabuilding.de

Authorisieren

Bevor Sie mit der NOVA AVA API arbeiten können, benötigen Sie zwei verschiedene Schlüssel, die sogenannten API-Schlüssel. Diese können Sie in Ihrer NOVA AVA "Administration" im Bereich "Schnittstellen" erzeugen.


% curl https://api.avanova.de/v1
    -u <APP_KEY>:<SECRET_KEY>
                    

Die Authorisierung an der NOVA AVA API erfolgt per HTTP Basic Authentication bei jeder Anfrage die an die API gestellt wird. Wie im nebenstehenden Beispiel zu sehen, werden dem cURL-Request die folgdenden Informationen als Benutzerangaben übergeben:

<APP_KEY> Ihre Applikations-ID
<SECRET_KEY> Ihr geheimer Schlüssel

PHP

$appKey = '<APP_KEY>';
$secretKey = '<SECRET_KEY>';
$service = new Nova\Request($appKey, $secretKey);

Die übergebenen Benutzerdaten werden durch die NOVA AVA API verifiziert und der Zugriff so auf den gewünschten Endpunkt gewährt und blockiert.

Nutzen Sie eine unserer Bibliotheken, müssen Sie sich um das Authorisierungsverfahren nicht mehr kümmern. In der Regel müssen Sie lediglich Ihre Schlüssel übergeben und wir kümmern uns dann um den Rest.

Anfragetypen

Nachfolgend erhalten Sie eine Übersicht über die verfügbaren Möglichkeiten eine Resource der NOVA AVA API anzusprechen.

GET

% curl https://api.avanova.de/v1/<RESOURCE>
% curl https://api.avanova.de/v1/<RESOURCE>/<ID>

Über diesen Anfragetyp können einzelne Objekte oder Listen abgerufen werden. Hierzu wird die gewünschte Resource ohne URL-Parameter aufgerufen um eine Liste abzurufen oder mit der [ID] des gewünschten Objektes als URL-Parameter um das Objekt selbst abzurufen.

POST

% curl https://api.avanova.de/v1/<RESOURCE>
    -d "name=NOVA Building IT GmbH"
    -d "country=Deutschland"

Dieser Anfragetyp wird verwendet um Objekte einer Resource zu erzeugen. Hierzu wird die gewünschte Resource ohne URL-Parameter aufgerufen. Alle zu befüllenden Felder des Objektes werden als POST-Parameter mit an die Resource übergeben.

PUT

% curl https://api.avanova.de/v1/<RESOURCE>/<ID>
    -d "name=NOVA Building IT GmbH"
    -d "country=Deutschland"
    -X PUT

Dieser Anfragetyp wird verwendet um bestehende Objekte einer Resource mit neuen Informationen zu aktualisieren. Sprechen Sie die gewünschte Resource mit der [ID] als URL-Parameter an und übergeben Sie dem cURL-Request alle zu ändernden Felder als zusätzliche PUT-Parameter.

DELETE

% curl https://api.avanova.de/v1/<RESOURCE>/<ID>
    -X DELETE

Dieser Anfragetyp wird verwendet um Objekte einer Resource zu löschen. Rufen Sie hierzu die URL der Resource mit der [ID] als URL-Parameter über einen DELETE-Request auf.

Rückgabewerte

Jede Anfrage an die NOVA AVA API liefert ein im JSON-Format kodiertes Objekt zurück. Diese besteht mindestens aus den Attributen [data] und [error]. Eine Rückgabe wird im folgenden auch als Response bezeichnet.

{
    "data": { // mixed data }
    "error": false
}

War eine Anfrage erfolgreich, wird das Ergebnis der direkt als Objekt oder als Array von Objekten im [data] Attribut zurückgegeben. Das Attribut [error] ist in diesem Fall FALSE.

mixed data Enthält die zurückgelieferten Daten als Array von Objekten oder das Objekt selbst.
bool error Im Erfolgsfall immer FALSE

Wann Sie ein Array oder ein Objekt als Ergebnis erhalten, kann im Bereich Anfragetypen nachgelesen werden.


{
    "data": null,
    "error": true,
    "errorCode": "XXXXX",
    "errorMessage": "ERROR_MESSAGE"
}

Wenn bei der Anfrage ein Fehler auftritt erhalten Sie im Attribut [data] in jedem Fall den Wert NULL zurück, das Attribut [error] wird auf TRUE gesetzt und die Rückgabe wird um einen [errorCode] und eine [errorMessage] erweitert.

bool error Im Fehlerfall immer TRUE
int errorCode Eindeutiger Code zur Identifizierung des Fehlers
string errorMessage Kurzer Beschreibungstext des Fehlers

Fehlercodes

Nachfolgend eine Liste aller möglichen Fehlercodes, die Sie durch die NOVA AVA API erhalten können.

  • 10000: Unknown error

  • 20001: Request could not be resolved
  • 20002: Request could not be authorized
  • 20003: Request blocked, invalid license

  • 30001: Could not collect response data

  • 90001: Unknown resource

  • 90002: Method is not supported for this resource
  • 99999: Runtime error

HTTP-Statuscodes

Neben den Fehlercodes, wird auch der HTTP-Status genutzt, um die Anfrage auszuwerten. Folgend eine Liste, wie wir die HTTP-Statuscodes in der NOVA AVA API verstehen.

  • 2xx: Die Anfrage wurde erfolgreich verarbeitet
  • 4xx: Die Anfrage ist fehlerhaft oder wurde abgelehnt
  • 5xx: Die NOVA AVA API hat einen Fehler verursacht
Code Beschreibung
200 OK Alles ist in Ordnung.
400 Bad Request Die Anfrage ist fehlerhaft und konnte nicht verarbeitet werden.
401 Unauthorized Die Anfrage konnte nicht authorisiert werden.
402 Payment Required Die Lizenz ist abgelaufen und die Anfrage wurde blockiert.
404 Not Found Die gewünschte Resource ist nicht verfügbar.
500 Server Error Innerhalb der API ist ein Fehler aufgetreten. Wir wurden informiert!

Wichtig!

Bitte verlassen Sie sich nicht ausschließlich auf den zurückgelieferten HTTP-Status. Details können immer dem errorCode und der errorMessage entnommen werden.

Filter

Um die angefragten Daten, die über einen GET-Request abgerufen werden, zu filtern, haben wir zwei verschiedene Varianten implementiert.

Sortieren

Query

?order=amount
?order=amount_asc OR ?order=amount_desc

PHP

$address = new \Nova\Models\Request\Address();
$address->setFilter(array(
    'order' => 'zip_asc'
));

Bei der Anfrage kann bereits ein Filter für die Sortierung mitgegeben werden. Hierzu geben Sie über den URL-Parameter [order] das gewünschte Feld an, nachdem sortiert werden soll. Standardmäßig wird nach diesem aufsteigend sortiert.

Wenn die Richtung der Sortierung beeinflusst werden soll, ist dies durch anhängen der Sortierreihenfolge an den Feldnamen möglich: [attributename]_asc oder für absteigende Sortierung [attributename]_desc.

Filtern

Query

?created=<TIMESTAMP>
?created=<TIMESTAMP_FROM>-<TIMESTAMP_TO>

PHP

$department = new \Nova\Models\Request\Department();
$department->setFilter(array(
    'created' => '1349947042'
));

Um die Ergebnismenge einzuschränken, kann auf beliebige verfügbare Felder des angefragten Objekts gefiltert werden. Hierzu wird das Feld als Attribut angegeben und mit dem gewünschten Suchkriterium gefüllt. Für die Abfrage von Zeitstempeln gibt es eine erweiterte Notation, um auch Zeiträume abfragen zu können.

Benutzer

Fast jedes Element innerhalb von NOVA AVA ist einem Benutzer zugeordnet. Benutzer sind Abteilungen zugeordnet und besitzen bestimmte Rollen und damit verbundene Rechte.

User-Objekt

{
    "id": 12345,
    "username": "novabuilding",
    "email": "info@novabuilding.de",
    "password": "",
    "avatar": "<Image>",
    "firstname": "Sven",
    "lastname": "Walter",
    "displayname": "Sven Walter",
    "last_login": 1349947042,
    "last_pw_change": null,
    "force_pw_change": false,
    "language": "de",
    "source": "",
    "admin": true,
    "license": true,
    "active": true,
    "created": 1349947042
}

Attribute:

int id Eindeutiger Identifiktaionsschlüssel
string username Benutzername
string email E-Mail-Adresse
string password Verschlüsseltes Passwort
string avatar Base64 codiertes Bild
string firstname Vorname
string lastname Nachname
string displayname Anzeigename
int last_login Datum der letzten Anmeldung
int last_pw_change Datum der letzten Passwortänderung
bool force_pw_change Benutzer muss sein Kennwort ändern
string language Standardsprache des Benutzers
string source Quellsystem des Benutzers
bool admin Benutzer hat Administrator-Rechte
bool license Benutzer darf die Software-Lizenz bearbeiten
bool active Benutzer ist aktiviert
int created Erstelldatum

Neues User-Objekt erstellen

Request

$user = new Nova\Models\Request\User();
$user->setUsername("novabuilding")
     ->setEmail("info@novabuilding.de")
     ->setFirstname("Sven")
     ->setLastname("Walter")
     ->setPassword("12345");

$user = $service->create($user);

Response

{
    "data": {
        "id": 12345,
        "username": "novabuilding",
        "email": "info@novabuilding.de",
        "password": "",
        "avatar": "<Image>",
        "firstname": "Sven",
        "lastname": "Walter",
        "displayname": "Sven Walter",
        "last_login": null,
        "last_pw_change": null,
        "force_pw_change": false,
        "language": "de",
        "source": "",
        "admin": true,
        "license": true,
        "active": true,
        "created": 1349947042
    },
    "error": false
}

Über diese Funktion legen Sie einen neuen Benutzer in Ihrem NOVA AVA System an.

Folgende Attribute müssen angegeben werden:

string username Benutzername
string email E-Mail-Adresse
string password Passwort

User-Objekt abrufen

Request

$user = new Nova\Models\Request\User();
$user->setId(1);

$user = $service->getOne($user);

Response

{
    "data": {
        "id": 12345,
        "username": "novabuilding",
        "email": "info@novabuilding.de",
        "password": "",
        "avatar": "<Image>",
        "firstname": "Sven",
        "lastname": "Walter",
        "displayname": "Sven Walter",
        "last_login": 1349947042,
        "last_pw_change": null,
        "force_pw_change": false,
        "language": "de",
        "source": "",
        "admin": true,
        "license": true,
        "active": true,
        "created": 1349947042
    },
    "error": false
}

Um einen Benutzer aus NOVA AVA abzurufen, wird die [ID] des Benutzers als Parameter übergeben.

Parameter:

int id Eindeutiger Identifiktaionsschlüssel

User-Liste abrufen

Request

$user = new Nova\Models\Request\User();
$response = $service->getAll($user);

Response

{
    "page": 1,
    "pages": 1,
    "limit": 50,
    "total": 1,
    "items": [
        {
            "id": 12345,
            "username": "novabuilding",
            "email": "info@novabuilding.de",
            "password": "",
            "avatar": "<Image>",
            "firstname": "Sven",
            "lastname": "Walter",
            "displayname": "Sven Walter",
            "last_login": 1349947042,
            "last_pw_change": null,
            "force_pw_change": false,
            "language": "de",
            "source": "",
            "admin": true,
            "license": true,
            "active": true,
            "created": 1349947042
        }
    ],
    "error": false
}

Diese Funktion gibt ein JSON Objekt mit einer Liste von Benutzern zurück. Die Reihenfolge in der die Liste zurückgegeben wird, kann durch Filter beeinflusst werden.

Parameter für die Sortierung:

  • id
  • username (Standard)
  • email
  • firstname
  • lastname
  • last_login
  • last_pw_change
  • source
  • admin
  • active
  • created

Verfügbare Filter

Als Filter können alle vefügbaren Felder des User-Objektes genutzt werden.

  • id = <user_id>
  • username = <string>
  • email = <string>
  • last_login = <timestamp> | <timestamp_from>-<timestamp_to>
  • created = <timestamp> | <timestamp_from>-<timestamp_to>
  • ...

User-Objekt bearbeiten

Request

$user = new Nova\Models\Request\User();
$user->setId(12345)
     ->setEmail("support@novabuilding.de")
     ->setFirstname("Felix")
     ->setLastname("Grau");

$user = $service->update($user);

Response

{
    "data": {
        "id": 12345,
        "username": "novabuilding",
        "email": "support@novabuilding.de",
        "password": "",
        "avatar": "<Image>",
        "firstname": "Felix",
        "lastname": "Grau",
        "displayname": "Felix Grau",
        "last_login": 1349947042,
        "last_pw_change": null,
        "force_pw_change": false,
        "language": "de",
        "source": "",
        "admin": true,
        "license": true,
        "active": true,
        "created": 1349947042
    },
    "error": false
}

Über diese Funktion können die Informationen zu einem Benutzer bearbeitet und in NOVA AVA gespeichert werden.

Folgende Attribute müssen angegeben werden:

int id Eindeutiger Identifikationsschlüssel

User-Objekt löschen

Request

$user = new Nova\Models\Request\User();
$user->setId(12345);

$service->delete($user);

Response

{
    "data": null,
    "error": false
}

Diese Funktion entfernt einen Benutzer aus dem NOVA AVA System.

Folgende Attribute müssen angegeben werden:

int id Eindeutiger Identifikationsschlüssel


Wichtig!

Diese Funktion kann zu unvorhergesehenen Ergebnissen führen, da alle Zuordnungen verfügbarer Elemente zu dem gelöschten Benutzer verloren gehen.

Abteilungen

Um eine komplexere Organisationsstruktur in NOVA AVA abzubilden, kann das Programmsystem in Abteilungen unterteilt werden. Alle Daten sind abteilungsweise voneinander getrennt. Grundsätzlich kann man dieses Konzept auch als "leichte" Mandanten bezeichnen. Alle Daten sind grundsätzlich logisch voneinander getrennt, bestimmte Bereiche können für Benutzer jedoch Abteilungsübergreifend geschaltet werden.

Wichtig!

Abteilungen können derzeit nur abgerufen werden und können nicht erstellt oder bearbeitet werden.

Department-Objekt

{
    "id": 12345,
    "name": "Standard",
    "description": "",
    "created": 1349947042
}

Attribute:

int id Eindeutiger Identifiktaionsschlüssel
string name Bezeichnung
string description Beschreibung
int created Erstelldatum

Department-Objekt abrufen

Request

% curl https://api.avanova.de/v1/department/[ID]

Response

{
    "data": {
        "id": 12345,
        "name": "Standard",
        "description": "",
        "created": 1349947042
    },
    "error": false
}

PHP

$request = new Nova\Models\Request\Department();
$request->setId(12345);

$department = $service->getOne($request);

Um eine einzelne Abteilung aus NOVA AVA abzurufen, wird die [ID] der Abteilung als URL-Parameter übergeben.

Parameter:

int id Eindeutiger Identifiktaionsschlüssel

Department-Liste abrufen

Request

% curl https://api.avanova.de/v1/department

Response

{
    "page": 1,
    "pages": 1,
    "limit": 50,
    "total": 1,
    "items": [
        {
            "id": 12345,
            "name": "Standard",
            "description": "",
            "created": 1349947042
        }
    ],
    "error": false
}

PHP

$request = new Nova\Models\Request\Department();
$departmentList = $service->getAll($request);

Diese Funktion gibt ein Array von Abteilungen zurück. Die Reihenfolge und Anzahl der zurückgelieferten Liste, kann durch die folgenden Filter beeinflusst werden.


Parameter für die Sortierung:

  • id (Standard)
  • name
  • created

Verfügbare Filter:

  • id = <department_id>
  • name = <string>
  • description = <string>
  • created = <timestamp> | <timestamp_from>-<timestamp_to>

Adressen

In NOVA AVA können über ein Adressbuch Kontakte und Adressen verschiedenster Art gespeichert und verwaltet werden. Adressen sind abteilungsspezifisch können jedoch über die Schnittstelle auch abteilungsübergreifend abgerufen werden.

Address-Objekt

{
    "id": 12345,
    "department": "<Object>",
    "name1": "NOVA Building IT GmbH",
    "name2": "",
    "name3": "",
    "name4": "",
    "street": "In der Mordach 1a",
    "postbox": "",
    "zip": "64367",
    "city": "Mühltal",
    "country": "Deutschland",
    "phone": "",
    "fax": "",
    "email": "info@novabuilding.de",
    "contact": "Sven Walter",
    "iln": "",
    "vatId": "",
    "bank": "",
    "brNo": "",
    "acctNo": "",
    "iban": "",
    "bic": "",
    "vendorNo": "",
    "hrgNo": "",
    "hrgType": "",
    "trial": "",
    "compNo": "",
    "taxNo": "",
    "union": "",
    "attr1": "",
    "attr2": "",
    "attr3": "",
    "exemption": true,
    "exemptionDate": 1349947042,
    "labels": [
        "Auftraggeber",
        "Generalunternehmer"
    ]
}

Objects

- address.department returns department object

Attribute:

int id Eindeutiger Identifiktaionsschlüssel
object department Zugeordnetes Department Objekt
string name1 1. Adresszeile
string name2 2. Adresszeile
string name3 3. Adresszeile
string name4 4. Adresszeile
string street Straße inkl. Hausnummer
string postbox Postfach
string zip Postleitzahl
string city Ort
string country Land
string phone Telefonnummer
string fax Faxnummer
string email E-Mail-Adresse
string contact Kontaktperson / Ansprechpartner
string iln ILN-Nummer der Adresse
string vatId Umsatzsteuer-Ident
string bank Name der Bank
string brNo Bankleitzahl
string acctNo Kontonummer
string iban IBAN
string bic BIC
string vendorNo Kreditoren-Nummer
string hrgNo Registernummer
string hrgType Registerart
string trial Registergericht
string compNo Buchungskreis
string taxNo Steuernummer
string union Gewerk
string attr1 Freies Feld für eigene Informationen
string attr2 Freies Feld für eigene Informationen
string attr3 Freies Feld für eigene Informationen
bool exemption Liegt eine Freistellungsbescheinigung vor?
int exemptionDate Freistellungsbescheinigung gültig bis
array labels Zugeordnete Labels

Neues Address-Objekt erstellen

Request

$address = new Nova\Models\Request\Address();
$address->setName1("NOVA Building IT GmbH")
        ->setDepartment(1)
        ->setStreet("In der Mordach 1a");

$address = $service->create($address);

Response

{
    "data": {
        "id": 12345,
        "department": {
            "id": 1,
            "name": "Standard",
            "created": 1349947042
        },
        "name1": "NOVA Building IT GmbH",
        "street": "In der Mordach 1a",
        "labels": [ ]
    },
    "error": false
}

Objects

- address.department returns department object

Über diese Funktion kann eine neue Adresse im NOVA AVA Adressbuch angelegt werden.

Folgende Attribute müssen angegeben werden:

string name1 1. Adresszeile
object | int department Department-Objekt oder [ID] der Abteilung

Address-Objekt abrufen

Request

$address = new Nova\Models\Request\Address();
$address->setId(1);

$address = $service->getOne($address);

Response

{
    "data": {
        "id": 12345,
        "department": {
            "id": 1,
            "name": "Standard",
            "created": 1349947042
        },
        "name1": "NOVA Building IT GmbH",
        "street": "In der Mordach 1a",
        "zip": "64367",
        "city": "Mühltal",
        "country": "Deutschland",
        "email": "info@novabuilding.de",
        "contact": "Sven Walter",
        "exemption": true,
        "exemptionDate": 1349947042,
        "labels": [
            "Auftraggeber",
            "Generalunternehmer"
        ]
    },
    "error": false
}

Objects

- address.department returns department object

Um eine Adresse aus NOVA AVA abzurufen, wird die [ID] der Adresse als Parameter übergeben.

Parameter:

int id Eindeutiger Identifiktaionsschlüssel

Address-Liste abrufen

Request

$address = new Nova\Models\Request\Address();
$response = $service->getAll($address);

Response

{
    "page": 1,
    "pages": 1,
    "limit": 50,
    "total": 1,
    "items": [
        {
            "id": 12345,
            "department": {
                "id": 1,
                "name": "Standard",
                "created": 1349947042
            },
            "name1": "NOVA Building IT GmbH",
            "street": "In der Mordach 1a",
            "zip": "64367",
            "city": "Mühltal",
            "country": "Deutschland",
            "email": "info@novabuilding.de",
            "contact": "Sven Walter",
            "exemption": true,
            "exemptionDate": 1349947042,
            "labels": [
                "Auftraggeber",
                "Generalunternehmer"
            ]
        }
    ],
    "error": false
}

Objects

- address.department returns department object

Diese Funktion gibt ein JSON Objekt mit einer Liste von Adressen zurück. Die Reihenfolge in der die Liste zurückgegeben wird, kann durch Filter beeinflusst werden.

Parameter für die Sortierung:

  • id
  • name1 (Standard)
  • zip
  • city
  • country

Verfügbare Filter

Als Filter können alle vefügbaren Felder des Address-Objektes genutzt werden.

  • id = <department_id>
  • name1 = <string>
  • exemption = <bool>
  • exemptionDate = <timestamp> | <timestamp_from>-<timestamp_to>
  • ...

Address-Objekt bearbeiten

Request

$address = new Nova\Models\Request\Address();
$address->setId(12345)
        ->setName1("NOVA Building IT GmbH")
        ->setStreet("In der Mordach 1a");

$address = $service->update($address);

Response

{
    "data": {
        "id": 12345,
        "department": {
            "id": 1,
            "name": "Standard",
            "created": 1349947042
        },
        "name1": "NOVA Building IT GmbH",
        "street": "In der Mordach 1a",
        "labels": [ ]
    },
    "error": false
}

Objects

- address.department returns department object

Über diese Funktion können die Informationen zu einer Adresse bearbeitet und in NOVA AVA gespeichert werden.

Folgende Attribute müssen angegeben werden:

int id Eindeutiger Identifikationsschlüssel

Address-Objekt löschen

Request

$address = new Nova\Models\Request\Address();
$address->setId(12345);

$service->delete($address);

Response

{
    "data": null,
    "error": false
}

Diese Funktion entfernt eine Adresse aus dem NOVA AVA Adressbuch.

Folgende Attribute müssen angegeben werden:

int id Eindeutiger Identifikationsschlüssel

Kalender

In Kürze verfügbar ...

Notizen

In Kürze verfügbar ...

Projekte

In Kürze verfügbar ...

Leistungsverzeichnisse

In Kürze verfügbar ...

Dokumente

In Kürze verfügbar ...