Vertec REST API

Vertec liefert mit Version 6.8.0.17 ein generisches REST API zu Vertec als Webservice aus.

Er heisst REST und ist im Ordner Einstellungen > Schnittstellen > Webservices zu finden:

Der REST Webservice wird inaktiv ausgeliefert. Um ihn aktivieren und verwenden zu können, müssen dieselben Bedingungen erfüllt sein wie bei allen Webservices (Berechtigungen und API Token vorhanden).

Vertec via REST API Webservice ansprechen

Der Aufruf erfolgt über <ServerURL>/api/webservice/REST.

Auf die Vertec Objekte kann man via /objects zugreifen. Objekte können abgefragt (GET), geändert (PUT), erzeugt (POST) oder gelöscht (DELETE) werden.

Den aktuell angemeldeten Benutzer liefert folgender Endpunkt: /functions/currentuser. Dazu können optional die Query Parameter functions, result_members und bi_measures mitgegeben werden (siehe die Abschnitte Funktionen, Rückgabewerte und BI Daten (Kennzahlen)).

Objekte abfragen (GET)

Einzelne Objekte abfragen

• Via Interne ID: /objects/1665
• Via Eintrag ID: Für die Abfrage via Eintrag ID muss als zweiter Parameter der Klassenname (in Deutsch oder Englisch) angegeben werden, gefolgt von der Eintrag ID: /objects/Administrator/UserAdmin.

Globale Abfragen

Die Daten können auch global abgefragt werden. Direkt mit einer Member-Suche oder auch via OCL oder SQL.

Dafür wird eine Query abgesetzt direkt auf der Klasse, also z.B. auf /objects/Project. Die Query startet mit einem ?, gefolgt von den entsprechenden Query-Parametern. Mehrere Query-Parameter werden mit & angehängt.

• Abfrage von Members - Attribute (inkl. Zusatzfeldern) und Associations (inkl. Custom-Links): Mit dem Query-Parameter query_member wird das Member angegeben, mit query_value der gesuchte Wert. Für jedes abgefragte Member wird die Kombination von query_member und query_value nummeriert: query_member0 und query_value0, query_member1 und query_value1 etc. 

  Unterstützte Operatoren (als Präfix im Wert): =, <, >, <=, >= für integer, date, datetime, currency.

  • Abfrage eines Attributs. Als query_value wird je nach Datentyp des Members der gesuchte Wert eingegeben: /objects/Project?query_member0=code&query_value0=com% sucht nach Projekten, dessen Code mit com beginnt.
  • Abfrage einer Association. Als query_value wird die Interne ID des gesuchten Objekts angegeben:/objects/Project?query_member0=type&query_value0=179.
  • Es können nur persistente Members abgefragt werden. Member-Suchen sind immer global. Wird trotzdem eine ID mitgegeben für ein einzelnes Objekt, wird diese ignoriert. 

• Via SQL: Für SQL wird mit dem Query-Parameter sql eine globale SQL Abfrage abgesetzt: /objects/Project?sql=bold_id IN (SELECT project FROM openservice).

• Via OCL: Mit dem Query-Parameter ocl wird eine OCL Expression abgesetzt: /objects?ocl=user->select(active).
  • OCL-Expressions können im Gegensatz zu SQL-Expressions auch auf einem einzelnen Objekt abgesetzt werden: /objects/1665?ocl=openservices.

Rückgabewerte

Das Resultat enthält ein Objekt oder eine Liste von Objekten. Zurückgegeben werden standardmässig von jedem Resultatobjekt die Interne ID (objid), die Standardanzeige des Objekts (stringrepresentation), der Klassenname (classname) sowie, ob das Objekt gültig ist (isvalid) und der Grund (hintisvalid), wenn ein Objekt ungültig ist.

Um weitere Members auszugeben, kann mit dem Query-Parameter result_members eine kommagetrennte Liste der entsprechenden Members angegeben werden: /objects/1665?result_members=code,description,regarding. Die angegebenen Members werden für jedes Resultatobjekt ausgegeben.

Funktionen

Über den Parameter functions können Funktionen auf Objekten aufgerufen und kann für Projektbearbeiter, Projekte und Phasen verwendet werden. Der Parameter muss als Query-Parameter mitgegeben und kann kommagetrennt vergleichbar mit Query-Parameter result_members angegeben werden (siehe dazu letzten Abschnitt Rückgabewert). 

Das Beispiel ruft die Sollzeit und die Arbeitszeit des angemeldeten Bearbeiters auf mit den Zeit- und Datumsangaben in Minuten sowie im Monat Januar 2026.

/objects?ocl=user&result_members=loginname,abbreviation&functions=getStdHours,getWorkingHours&date_from=2026-01-01&date_till=2026-01-31

Hier ein Beispiel für einen Request mit functions und result_members:

/objects?ocl=user&result_members=loginname,abbreviation&functions=getStdHours,getWorkingHours&date_from=2026-01-01&date_till=2026-01-31

Result:

[
    {
        "objid": 506,
        "stringrepresentation": "Administrator",
        "classname": "User",
        "isvalid" true,
        "hintisvalid": "",
        "loginname": "Administrator",
        "abbreviation": "",
        "getStdHours": 11220,
        "getWorkingHours": 60
    },
    … // weitere User
]

Nachfolgend sind noch alle Werte aufgelistet, die über functions aufgerufen werden können. Viele dieser Werte sind dieselben und funktionieren gleich wie die OCL Operatoren für Bearbeiter. Diese sind entsprechend verlinkt.

BI-Daten (Kennzahlen)

Die API kann direkt BI-Kennzahlen für ein Objekt liefern. 

Die Parameter sind

• bi_measures=MinutesExt,MinutesInt,... (interne BI-Namen) 
• bi_date_from=2026-02-01
• bi_date_till=2026-02-28
• optional bi_currency=CHF (Währungscode)
• optional projection_dimension=Project (z.B. eine zweite Dimension wie Kunde & Phase)

Daten ändern (PUT)

Mit einem PUT-Aufruf wird ein bestehendes Vertec Objekt angepasst. Die zu ändernden Felder werden im JSON-Body übergeben. Die Objekt-ID kommt aus der URL und der Body enthält die neuen Werte für die gewünschten Members.

• PUT /objects/Administrator/UserAdmin oder /objects/1665  
• Body: JSON-Objekt mit zu ändernden Feldern  

{
  "abbreviation": "AD",  
  "level": 500,    
}

Für jedes Feld prüft die API, ob es ein gültiges, persistentes Feld der Klasse ist.

Datentypen werden validiert und konvertiert (z.B. Datum im ISO-Format, Booleans, Ganzzahlen, Währungen). 

Bei Associations:

•   Single-Link: ein Integer (objid)  
•   Multi-Link: ein Integer oder eine Liste von Integers (objids)  

Im Erfolgsfall wird wie bei einer GET-Abfrage ein Resultat zurückgegeben, das das aktualisierte Objekt enthält.

Objekte erzeugen (POST)

Mit einem POST-Aufruf wird ein neues Vertec Objekt angelegt. Die Klasse des Objekts wird über die URL festgelegt und die Werte der Felder werden im JSON-Body übergeben. Im Unterschied zu PUT geht es hier nicht um das Aktualisieren eines bestehenden, sondern um das Erzeugen eines neuen Objektes.

• POST /objects/Project erzeugt ein neues Projekt

Der JSON Body sieht aus wie bei PUT und schreibt die entsprechenden Members auf dem neu erstellten Objekt. ​Tritt dabei ein Fehler auf (z.B. ungültiger Wert oder fehlendes Recht), wird das neu erzeugte Objekt wieder gelöscht und eine Fehlermeldung zurückgegeben.

Im Erfolgsfall entspricht die Antwort der Ausgabe eines GET-Aufrufs für das neu angelegte Objekt.

Objekte löschen (DELETE)

Über einen DELETE-Aufruf wird ein bestehendes Vertec Objekt endgültig gelöscht. Die zu löschende Instanz wird dabei über die objid oder die entryID in der URL identifiziert.

• DELETE /objects/1665 oder /objects/Administrator/UserAdmin

Es wird das angegebene Objekt gesucht und anschließend gelöscht.

Bei fehlenden Rechten wird HTTP-Status 403 Forbidden zurückgegeben und bei anderen Fehlern der HTTP-Status 400 Bad Request.

Im Erfolgsfall wird kein Objekt als JSON-Antwort zurückgeliefert, sondern nur ein entsprechender HTTP-Status zurückgegeben.

Dokumente schreiben

Über die API können zu folgenden Vertec Objekten auch Dateien (z.B. PDFs oder Bilder) gespeichert werden. Die Binärdaten der Datei werden dabei Base64-kodiert im JSON-Body eines PUT- oder POST-Aufrufs übertragen. 

- Aktivitäten  
- Spesen  
- Kreditoren

Im JSON-Body eines PUT- oder POST-Aufrufs wird das entsprechende Dokumentfeld mit einem Base64-kodierten String gefüllt. Die API dekodiert diesen Base64-String und speichert die Datei intern in einem eigenen Dokumentobjekt.

Spezialfall bei Aktivität: Bei Aktivitäten ist zusätzlich das Feld documentfullname erforderlich. Dieses Feld enthält den Dateinamen inklusive Dateiendung, damit Vertec den Namen des abgelegten Dokuments kennt. 

Beispiel: Dokument an Aktivitätanhängen

• PUT /objects/Activity/12345  
• JSON-Body:

{
  "document": BASE64DATEN
  "documentfullname": "Besuchsbericht.pdf"
}

In diesem Beispiel wird bei der Aktivität mit der objid 12345 ein Dokument mit dem Dateinamen Besuchsbericht.pdf gespeichert. Die API ruft dazu intern die passende Dokument-Funktion der Klasse Aktivität auf und legt ein DocumentData-Objekt mit den übergebenen Binärdaten an. 

Beispiel: Dokument an eine Rechnung anhängen

• PUT /objects/Expenses/9876 
• JSON-Body:

{
  "document": BASE64DATEN
}

Hier wird für die Rechnung mit der internen ID 9876 ein Dokument gespeichert, indem das Feld document mit dem Base64-kodierten Inhalt gefüllt wird. 

Logging des API-Zugriffs

Die Webserviceklasse VertecREST verfügt über eine Methode onrequest(self), die bei jedem WebRequest aufgerufen wird. In der Basisimplementierung hat diese Methode keine Funktion. Sie können diese Methode in einer abgeleiteten Klasse überschreiben, um für jeden Request eine definierte Funktion, beispielweise Logging, auszuführen. Tauschen Sie dann die Klassenreferenz im Webservice (vtcrest.VertecREST) gegen Ihre neue Klassenreferenz aus. Nachfolgend ein Beispiel für onrequest(self) Implementierung:

Der Scripteintrag:

from vtcrest import VertecREST

class REST(VertecREST):

    def onrequest(self):
        method = self.http_method
        path = "/".join(self.path_parameters)
        query = self.querystring
        self.log("Received request: {} {}?{}".format(method, path, query))

Der REST Webservice-Eintrag:

Fehlerverhalten

Die API antwortet üblicherweise mit den folgenden Fehlercodes:

400 Bad Request
Dieser Statuscode wird für alle fachlichen und technischen Fehler verwendet, die durch falsche Eingaben oder ungültige Anfragen entstehen. Typische Ursachen sind: 

• Ungültige Klassen- oder Feldnamen (z.B. „Attribut 'xyz' nicht gefunden für Klasse Project“)  
• Falsche Datentypen (z.B. „Value 'abc' für member 'startdate' konnte nicht zu 'date' konvertiert werden“)  
• Ungültige Objekt-IDs (z.B. „No Vertec object was found with objid=999999“)  
• Fehlende oder falsche Pflichtparameter (z.B. „'customer' is required as parameter“)  
• Syntaxfehler in OCL/SQL-Ausdrücken  
• Ungültige Base64-Daten bei Dokumenten  
• Logikfehler (z.B. „Association 'customer' must be a multi-link, but is a single-link“) 

403 Forbidden
Dieser Statuscode signalisiert fehlende Berechtigungen für die angeforderte Operation. Häufige Ursachen sind:

• Fehlende Leseberechtigung für Objekte/Felder („Read access denied while reading member 'salary'“)  
• Fehlende Schreib-/Löschberechtigung („Write access denied when writing value '1000' for member 'budget'“)  
• SQL-Query-Rechte fehlen („getwithsql failed - no SQL query right“)  
• OCL-Ausführungsrechte fehlen  
• BI-Datenzugriff nicht erlaubt  
• Zugriff auf WrapperLinkTypes untersagt 

Die Fehlermeldungen enthalten meist:  

•   betroffene Klasse und interne ID
•   betroffenes Feld/Parameter  
•   erwarteter Datentyp/Wert  
•   Original-Fehlertext aus Vertec (z.B. von `evalocl`, `bigetdata`, `getwithsql`) 

Bei korrekten Anfragen wird immer HTTP 200 OK zurückgegeben (auch bei DELETE).  
 

Die für die Nutzung des REST APIs notwendigen Definitionen sind im Vertec Python Modul "vtcrest" implementiert.