REST-API

Eine Schnittstelle ist erst dann eine Zusage, wenn man vor dem Kauf nachlesen kann, was sie kann. Deshalb steht hier der tatsächliche Bestand: jede Ressource, jeder Endpunkt, jedes Feld — nicht als Beispiel, sondern als Liste.

Die Schnittstelle bildet nicht jeden Bereich der Software ab und wird laufend erweitert. Was sie heute kann, steht vollständig auf dieser Seite; was Sie darüber hinaus brauchen, klären wir im Gespräch.

Alle Ressourcen

Gruppiert nach Bereich. Jede Ressource hat eine eigene Seite mit ihren Endpunkten und Feldern.

Diese Liste zeigt den Gesamtumfang über alle Module hinweg. Welche Ressourcen Sie tatsächlich nutzen können, hängt davon ab, welche Module Sie einsetzen — ohne Zeiterfassung gibt es keine Zeitbuchungen abzurufen. Im Zweifel klären wir das vorab.

CRM

Faktura

Stammdaten und Verwaltung

Dateien

Objektsystem

Zeiterfassung

System

Inhalte

Authentifizierung

Jede Anfrage trägt ein API-Token, entweder als Authorization: Bearer <token> oder als Basic-Auth mit dem Benutzernamen api und dem Token als Passwort.

Entscheidend ist, woran das Token hängt: an einem Benutzer. Es erbt dessen Rechte, es gibt also keinen Weg an der Rechteverwaltung vorbei. Was ein Benutzer in der Oberfläche nicht sehen darf, liefert die API mit seinem Token auch nicht.

• Ablaufdatum — abgelaufene Token werden beim nächsten Zugriff automatisch deaktiviert.
• IP-Beschränkung — je Token eine Liste erlaubter Adressen, IPv4 und IPv6.
• Letzter Zugriff — wird protokolliert, ungenutzte Token fallen auf.
• Jederzeit deaktivierbar, ohne das Benutzerkonto anzufassen.

Filtern, sortieren, blättern

Listen-Endpunkte nehmen dieselben Parameter entgegen:

Jede Listen-Antwort enthält neben den Daten die Blätterlinks und die Gesamtzahl der Treffer — man muss also nicht raten, wie viele Seiten folgen.

Fehler

Fehlerantworten folgen RFC 7807 und benennen bei Validierungsfehlern das einzelne Feld samt Fehlercode und Klartext. Statt „Anfrage ungültig" steht dort, welches Feld welchen Wert nicht annimmt — das erspart beim Anbinden die Rätselei.

Zusätzlich trägt jede Antwort eine X-Request-Id. Bei einer Rückfrage an den Support genügt diese Kennung, um genau den einen Aufruf wiederzufinden.

OpenAPI-Spezifikation

Ihre Installation stellt die Spezifikation als openapi.json und openapi.yaml bereit — und zwar nicht als allgemeines Handbuch, sondern mit Ihren eigenen Feldern darin. Jedes Zusatzfeld, das Sie an Kunden, Ansprechpartnern, Belegen oder Wiedervorlagen angelegt haben, erscheint dort mit Bezeichnung, Typ und Feldnamen — genauso dokumentiert und genauso ansprechbar wie die Standardfelder.

Das erspart die übliche Rückfragerunde beim Anbinden. Wer ein System an Ihre Installation anschließt, muss nicht erfragen, wie das Feld heißt, das Sie sich vor zwei Jahren angelegt haben — er lädt eine Datei, in der es steht.

Damit lässt sich die Schnittstelle in Postman oder Insomnia importieren oder ein Client in der Sprache Ihrer Wahl generieren. Die Seiten hier zeigen die neutrale Fassung: alle Module, keine kundenspezifischen Felder.

Konfiguration als Blueprint

Neben den Daten lässt sich auch die Konfiguration über die Schnittstelle bewegen. Für Kampagnen, Objektarten, Wertelisten, Vorgangs-Schemas und Zeitarten gibt es je einen Blueprint-Endpunkt: Ein GET liefert die vollständige Einrichtung als ein JSON-Dokument, ein POST legt daraus eine neue an oder überträgt sie auf eine bestehende.

Zu jedem Blueprint gibt es zusätzlich das passende JSON-Schema. Man kann ein Dokument also prüfen, bevor man es einspielt — und maschinell erzeugen, statt es abzutippen.

Was das löst, kennt jeder, der mehr als eine Installation betreut: Ein Vorgangs-Schema, das mit seinen Status und Prozessschritten einmal durchdacht wurde, muss beim nächsten Mandanten nicht neu geklickt werden. Es wird exportiert, geprüft und eingespielt. Dasselbe gilt für eine Kampagne mit ihren Status oder eine Werteliste mit ihren Ausprägungen.

Anbinden ohne eigene Entwicklung

Eine Schnittstelle nach REST-Konventionen mit Token im Kopf ist genau das, was Automatisierungsplattformen erwarten. Wer kein Entwicklungsteam hat, verbindet ameax deshalb auch über ein solches Werkzeug mit anderen Systemen — ein Formular auf der Website legt einen Kunden an, ein neuer Auftrag im Shop erzeugt einen Beleg.

Was dafür nötig ist, steht auf dieser Seite: die Adresse, das Token, die Ressource und ihre Felder.