Zum Hauptinhalt springen

ZeyOS REST API Reference

Greifen Sie auf alle ZeyOS-Daten zu und verbinden Sie Drittanwendungen über eine leistungsstarke, standardkonforme REST-API.

Verbindungsgrundlagen

Jede REST-Anfrage richtet sich an eine ZeyOS-Instanz und verwendet dasselbe Authentifizierungs- und Abfragemodell.

REST-Basis-URLhttps://cloud.zeyos.com/{INSTANCE}/api/v1/{INSTANCE} durch den Namen der Kundeninstanz ersetzen, zum Beispiel demo.
Authentifizierungs-APIhttps://cloud.zeyos.com/{INSTANCE}/auth/v1/Die Authentifizierungs-API erstellt und verwaltet Bearer-Token.
Request-HeaderAuthorization: Bearer <token>Den Bearer-Token bei jeder REST-API-Anfrage mitsenden.

Authentifizierungsablauf

  1. Token abrufenEinen Bearer-Token über die Authentifizierungs-API erstellen oder innerhalb browserbasierter ZeyOS-Apps das aktuelle Session-Cookie verwenden.
  2. Ressourcen-Endpunkt aufrufenListen- und Suchendpunkte verwenden POST mit einem JSON-Request-Body. Ressourcen-URLs enden mit dem Entitätsnamen, etwa /accounts/ oder /contacts/.
  3. Statuscodes auswertenJeden HTTP-Statuscode größer oder gleich 400 als Fehler behandeln. Erfolgreiche Listenabfragen liefern JSON-Daten.
Minimale Anfragecurl
curl -sS -X POST \
  -H "Authorization: Bearer $ZEYOS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"fields":["ID","lastname","firstname"],"limit":3}' \
  "https://cloud.zeyos.com/$ZEYOS_INSTANCE/api/v1/contacts/"

Einstieg

AuthentifizierungBearer-Token via OAuth 2.0 abrufen oder per Session-Cookie authentifizieren.Auth-API-Referenz Endpunkte durchsuchenAlle Entitäten erkunden — Accounts, Kontakte, Aufgaben und mehr.Endpunkte ansehen OpenAPI-SpezifikationMaschinenlesbare Spec für Postman, Insomnia oder KI-Agenten herunterladen.api.json herunterladen

Modell des Query-Bodys

Die meisten Listenendpunkte akzeptieren denselben JSON-Body. Typisch sind zuerst Felder und Filter, danach Sortierung, Paginierung oder Expansion.

query.jsonPOST
{
  "fields": {
    "Id": "ID",
    "Name": "lastname",
    "Nickname": "extdata.nickname",
    "City": "contact.city",
    "Country": "contact.country",
    "SalesAgent": "assigneduser.name"
  },
  "filters": {
    "visibility": 0,
    "contact.country": {"IN": ["DE", "AT", "GB"]},
    "2": [
      "OR",
      {"lastmodified": {">": 1524472045}},
      {"contact.lastmodified": {">": 1524472045}}
    ]
  },
  "sort": ["+lastname", "-contact.country"],
  "limit": 3,
  "offset": 0,
  "expand": ["extdata"]
}
fieldsarray | objectLegt die zurückgegebenen Spalten fest. Ein Objekt ermöglicht Aliase in der Antwort.
filtersobject | arrayKombiniert Feldbedingungen mit AND-, OR- und NOT-Gruppen.
querystringWendet einen Suchbegriff auf durchsuchbare Textfelder wie name an.
sortarraySortiert nach einer oder mehreren Spalten. + bedeutet aufsteigend, - absteigend.
countnumberLiefert die Anzahl der Datensätze, die zu den aktuellen Filtern passen, bevor paginiert wird.
limit / offsetnumberBlättert durch große Ergebnismengen, nachdem count die Gesamtzahl ermittelt hat.
expandarrayBindet JSON-Felder oder Binärdatei-Referenzen direkt in die Antwort ein.

Schlüsselkonzepte

Alle Endpunkte teilen dasselbe Abfragemodell. Einmal lernen, überall anwenden.

Feldauswahl & JoinsFelder als Array oder Objekt mit Aliasen wählen. Erstgradig verwandte Entitäten und extdata-Felder einbeziehen.
Komposite FilterBedingungen mit AND / OR / NOT kombinieren. Unterstützt Gleichheit, Bereich, IN, Regex und LIKE.
Sortierung & PaginierungNach mehreren Spalten mit + / - sortieren. Mit count, limit und offset durch Ergebnisse blättern.
Binär- & JSON-ExpansionJSON- und Binärinhalte mit dem expand-Parameter direkt in Abfrageergebnisse einbetten.

Praktische Details

AliaseWenn fields ein Objekt ist, werden die Schlüssel zu Antwortfeldern und die Werte zeigen auf Datenbankfelder."Name": "lastname"
BeziehungsfelderErstgradige Beziehungen können nach Prüfung der Schema-Referenz per Punktnotation ausgewählt oder gefiltert werden."assigneduser.name"
Eigene FelderWerte aus dem Formular-Builder liegen in extdata und können wie normale Felder abgefragt werden."extdata.nickname"
Zählungcount vor der Paginierung senden, wenn die Gesamtzahl der Seiten berechnet werden soll.{"count": 1, "filters": {"visibility": 0}}
Binär-Expansionexpand für Datei-Referenzen verwenden, wenn der referenzierte Inhalt in derselben Antwort benötigt wird."expand": ["binfile"]
FehlerFehlerantworten verwenden HTTP-Statuscodes ab 400 und liefern eine Klartextmeldung.status >= 400

Filteroperatoren

Vergleich=!=<><<=>>=IN!IN
Textsuche~~*!~!~*~~~~*!~~!~~*
Logische GruppenANDORNOT

Rückgabewerte

200 / 201ErfolgAntwort ist ein JSON-Objekt oder -Array.
400+FehlerAntwort ist eine Klartextfehlermeldung.

Verwandte Dokumentation

Schema-ReferenzFeldnamen und Entitätsbeziehungen.SDK-DokumentationClient-SDK für JavaScript / TypeScript.