Live-Demo buchen
Menü öffnenMenü schließen

Entwickler

brainX REST API

Datensätze, Metadaten und Verknüpfungen aus Ihren bestehenden Systemen lesen und schreiben. Jede brainX-Instanz stellt die API unter der eigenen Subdomain bereit.

OpenAPI-SpezifikationPostman-CollectionPostman herunterladen(öffnet in einem neuen Tab)
  • Version 1.2.0
  • REST · JSON
  • Bearer-Token (JWT)
  • 60 Anfragen / Minute
  • 17 Endpunkte

Einstieg

Überblick

Die brainX REST API liest und schreibt Datensätze, Metadaten und Verknüpfungen. Jede brainX-Instanz stellt sie unter der eigenen Subdomain bereit. Alle Pfade dieser Referenz hängen an die Basis-URL. Jede Aktion, die geschützt ist, braucht den Header Authorization.

Basis-URL https://ihr-system.brainx.app/api

Entitäten

Jedes Modul ist eine Entität mit eigener ID. IDs, Felder und Ansichten liefert /metadata/entities. Mehr dazu unter Grundbegriffe.

Format

Anfragen und Antworten nutzen den Medientyp application/vnd.brainformatik.crm-v1+json, auch Fehlerantworten. Nur 503 kommt als application/json.

Antworten

Jede Antwort enthält status und message. Die Daten stehen in data, Listen nennen in metadata zusätzlich die Gesamtzahl.

Header

Authorization: Bearer eyJhbGciOi...
Accept: application/vnd.brainformatik.crm-v1+json
Content-Type: application/vnd.brainformatik.crm-v1+json

Antwortstruktur

{
  "status": 200,
  "message": "OK",
  "metadata": { ... },
  "data": [ ... ]
}

Authentifizierung

Die API arbeitet mit Bearer-Token im Format JWT. Was die Schnittstelle lesen und schreiben darf, bestimmen die Rechte des angemeldeten Benutzers.

  1. Benutzer festlegen

    Die API meldet sich als Benutzer Ihres brainX-Systems an. Seine Rechte bestimmen, was die Schnittstelle lesen und schreiben darf.

  2. Token anfordern

    POST /auth mit Benutzername und Passwort liefert ein Access-Token (JWT, 15 Minuten gültig) und ein Refresh-Token (7 Tage gültig). Das Access-Token senden Sie bei jeder weiteren Anfrage im Header Authorization mit.

  3. Token erneuern

    POST /auth/refresh tauscht das Refresh-Token gegen ein neues Paar aus Access- und Refresh-Token. Das alte Refresh-Token wird dabei ersetzt.

  4. Abmelden

    DELETE /auth meldet den Benutzer wieder ab.

Zwei-Faktor-Authentifizierung

Ist für den Benutzer TOTP aktiv, gibt es zwei Wege. Entweder melden Sie sich mit einem App-Passwort aus „Meine Einstellungen“ an (Feld apiPassword, beim Medientyp v2 als SHA-512-Hash). Oder POST /auth antwortet mit 201 und einem Challenge-Token, das 60 Sekunden gilt. Damit und mit dem Code aus der Authenticator-App schließen Sie den Login über POST /auth/code ab. WebAuthn wird nicht unterstützt.

Cookie statt Token

Mit setCookie=1 setzt die API beim Login, beim Erneuern und beim Zwei-Faktor-Code ein httpOnly-Cookie zur Authentifizierung und gibt nur das Refresh-Token zurück.

Login

curl -X POST https://ihr-system.brainx.app/api/auth \
  -H 'Content-Type: application/vnd.brainformatik.crm-v1+json' \
  -d '{"user":"string","password":"string"}'

Antwort · 200

{
  "status": 200,
  "message": "OK",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiSm9obiBEb2UifQ.K1lVDx...",
    "refreshToken": "c7701a80c1eda9761484f0d64f458d7bc2..."
  }
}

Jede weitere Anfrage

Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

Grundbegriffe

Die API arbeitet mit den internen Namen und IDs der Module. Die Bezeichnungen aus der Oberfläche liefert sie zusätzlich in der Sprache des Benutzers.

Entität

Ein Modul wie Accounts (Organisationen), Contacts (Kontakte) oder Invoices (Rechnungen), jeweils mit numerischer ID. Deals heißen intern Potentials. In den Beispielen dieser Doku stehen 6 für Accounts, 4 für Contacts und 2 für Potentials. Die IDs Ihres Systems liefert GET /metadata/entities.

Hilfsentität

Liefert Werte, die Sie zum Anlegen anderer Datensätze brauchen, etwa Currencies, Groups oder InventoryTax. Hilfsentitäten sind nur lesbar.

Datensatz

Ein Eintrag einer Entität (Record), etwa eine Organisation oder eine Rechnung. Lesen, anlegen, ändern und löschen über die Records-Endpunkte.

Felder, Blöcke, Ansichten

Felder, Feldtypen, Pflichtfelder, Auswahlwerte und Blöcke einer Entität liefert GET /metadata/entities/{entityId}, sortiert wie im Layout-Editor. Für eine eigene Bearbeitungsansicht gibt es den Pfad mit /view/{viewId}.

Positionen

Module mit Positionen (isInventory) führen Produkte und Dienstleistungen im Feld lineItems, bei Deals sind Positionen optional. Beim Bearbeiten ersetzt die übergebene Liste alle bestehenden Positionen, die Reihenfolge muss stimmen.

Verknüpfungen

Verknüpfte Datensätze übergeben Sie in Referenzfeldern als ID. Welche Datensätze mit einem Datensatz verknüpft sind, zeigt GET /relations/{recordId}.

  • Checkbox
  • Currency
  • DateTime
  • Email
  • File
  • Image
  • LanguagePickList
  • ModuleFieldType
  • MultiPickList
  • Number
  • Password
  • Percentage
  • Phone
  • PickList
  • Reference
  • RoleReference
  • Skype
  • StateCode
  • TaxClass
  • Text
  • Textarea
  • Url
  • UsersGroupsReference

Entitäten abfragen

curl https://ihr-system.brainx.app/api/metadata/entities \
  -H 'Authorization: Bearer eyJhbGciOi...' \
  -H 'Accept: application/vnd.brainformatik.crm-v1+json'

Auszug aus der Antwort

"data": [
  {
    "id": 23,
    "name": "Invoice",
    "isEntity": true,
    "label": "Invoices"
  },
  {
    "id": 73,
    "name": "Currencies",
    "isEntity": false,
    "label": "Currencies"
  }
]

Rate Limit

Gemessen pro IP-Adresse in einem gleitenden Fenster. Über dem Limit antwortet die API mit 429, bis wieder Anfragen erlaubt sind. Wenn Sie wirklich viele Anfragen stellen müssen, warten Sie nach jeder Anfrage eine Sekunde.

Ein Aufruf liefert höchstens 200 Datensätze. Größere Mengen holen Sie seitenweise über offset und limit.

60 Anfragen / Minute

Seitenweise abrufen

GET /entity/6/records?limit=200&offset=0
GET /entity/6/records?limit=200&offset=200
GET /entity/6/records?limit=200&offset=400

Antwort · 429

{
  "status": 429,
  "message": "Too many requests"
}

Fehlercodes

Fehler kommen einheitlich mit dem Statuscode im Feld status und einer Meldung in message. Seit Version 1.2.0 meldet die Prüfung beim Anlegen und Bearbeiten „Validation failed: …“ mit jedem betroffenen Feld und dem Grund.

  • 400 Bad Request

    Die Anfrage ist fehlerhaft. Was nicht stimmt, steht im Feld message, bei Prüffehlern als „Validation failed: …“ mit jedem betroffenen Feld.

  • 401 Unauthorized

    Meist stimmen Zugangsdaten oder Token nicht.

  • 403 Forbidden

    Meist fehlt dem Benutzer der Zugriff auf die angefragte Ressource.

  • 404 Not Found

    Meist existiert die angefragte Ressource nicht.

  • 429 Too Many Requests

    Der Aufruf überschreitet das Rate Limit.

  • 500 Internal Server Error

    Interner Serverfehler. Bitte wenden Sie sich an den Support.

  • 501 Not Implemented

    Die aufgerufene Operation wird derzeit nicht unterstützt.

  • 503 Service Unavailable

    Der Dienst ist gerade nicht verfügbar, meist während Wartungsarbeiten.

Antwort · 400

Content-Type: application/vnd.brainformatik.crm-v1+json

Fehlerantwort

{
  "status": 400,
  "message": "This is not a valid date."
}

Antwort · 401

Content-Type: application/vnd.brainformatik.crm-v1+json

Fehlerantwort

{
  "status": 401,
  "message": "Unauthorized."
}

Antwort · 403

Content-Type: application/vnd.brainformatik.crm-v1+json

Fehlerantwort

{
  "status": 403,
  "message": "Forbidden."
}

Antwort · 404

Content-Type: application/vnd.brainformatik.crm-v1+json

Fehlerantwort

{
  "status": 404,
  "message": "Not found."
}

Antwort · 429

Content-Type: application/vnd.brainformatik.crm-v1+json

Fehlerantwort

{
  "status": 429,
  "message": "Too many requests"
}

Antwort · 500

Content-Type: application/vnd.brainformatik.crm-v1+json

Fehlerantwort

{
  "status": 500,
  "message": "Internal server error."
}

Antwort · 501

Content-Type: application/vnd.brainformatik.crm-v1+json

Fehlerantwort

{
  "status": 501,
  "message": "This operation is not supported for this entity"
}

Antwort · 503

Content-Type: application/json

Fehlerantwort

{
  "status": 503,
  "message": "Service Unavailable"
}

Versionen

Die aktuelle Version der Schnittstelle ist 1.2.0. Die Version des Datenformats steckt im Medientyp, nicht in der URL: Anfragen und Antworten nutzen application/vnd.brainformatik.crm-v1+json. Der Login nimmt zusätzlich application/vnd.brainformatik.crm-v2+json an. Dann wird das App-Passwort als SHA-512-Hash übertragen.

Änderungen

1.2.0

Anlegen und Bearbeiten prüfen jetzt dieselben Regeln wie die Bearbeitungsansicht in brainX. Zur Pflichtfeldprüfung kommen bedingte Pflichtfelder, Datumsabhängigkeiten (ein Enddatum darf nicht vor seinem Startdatum liegen), Eindeutigkeitsregeln, Zahlengrenzen und modulspezifische Regeln. Schlägt die Prüfung fehl, antwortet die API mit 400 und der Meldung „Validation failed: …“, die jedes Feld mit Grund nennt. Anfragen, die bisher angenommen wurden, können deshalb jetzt abgelehnt werden.

1.1.0

Erweiterte Filter für Listenabfragen.

Jede Anfrage

Accept: application/vnd.brainformatik.crm-v1+json
Content-Type: application/vnd.brainformatik.crm-v1+json

Login mit gehashtem App-Passwort

Content-Type: application/vnd.brainformatik.crm-v2+json

Postman und OpenAPI

Für einen schnellen Start gibt es eine Postman-Collection mit 14 Anfragen. Sie setzt das Token nach dem Login automatisch an jede Anfrage. Sie legen nur eine Umgebung mit drei Variablen an:

Die OpenAPI-Spezifikation (OpenAPI 3.0.2) laden Sie direkt in Postman, Insomnia oder ein anderes Werkzeug. Als Server-Adresse ist https://{subdomain}.brainx.app/api hinterlegt, die Subdomain tragen Sie selbst ein.

Die Dateien hier entsprechen Version 1.2.0. Jedes brainX-System liefert die aktuelle Dokumentation selbst aus, passend zu seinem Stand und mit seiner Adresse: unter https://ihr-system.brainx.app/api/docs, die Postman-Collection unter /api/postman.json.

url

Die Adresse Ihres Systems ohne weiteren Pfad, z. B. https://sub-domain.brainx.app

userName

Der Benutzer, mit dem sich die Collection anmeldet

password

Das Passwort dieses Benutzers

Postman-CollectionOpenAPI-SpezifikationPostman herunterladen(öffnet in einem neuen Tab)

Umgebung in Postman

url        https://sub-domain.brainx.app
userName   <Benutzername>
password   <Passwort>

Setzt die Collection selbst

token          nach Login und Refresh
refresh_token  nach Login und Refresh

Ressource

Records

Alle Module in brainX sind Entitäten. Über die Records-Endpunkte lesen und schreiben Sie deren Datensätze: Organisationen, Kontakte, Verträge, Rechnungen und alle selbst angelegten Module inklusive benutzerdefinierter Felder.

6 Endpunkte

GET /entity/{entityId}/records

Datensätze einer Entität abrufen

Liefert eine Liste von Datensätzen einer Entität. Über die Query-Parameter steuern Sie Auswahl, Reihenfolge, Umfang und Filterung des Ergebnisses.

Authentifizierung: Bearer-Token (JWT)

Pfadparameter

entityId integer erforderlich

Die ID der Entität.

Beispiel: 6

Query-Parameter

offset integer

Anzahl der Datensätze, die vor der Liste übersprungen werden. Dient der Pagination.

limit integer

Anzahl der Datensätze. Ohne Angabe gilt der Standardwert der Listen in brainX, das harte Maximum liegt bei 200 Datensätzen.

Beispiel: limit=20

fields array of strings

Die gewünschten Felder, getrennt durch „|“. Ohne Auswahl liefert die API die Felder der Listenansicht „Alle“. Mit * kommen alle Felder, das kann langsam sein.

Beispiel: fields=accountname|industry|assigned_user_id

includeDeleted boolean

Liefert auch gelöschte Datensätze, solange sie im Papierkorb liegen. Endgültig entfernte Datensätze lassen sich nicht abrufen.

Beispiel: includeDeleted=true

includeFileContent boolean

Liefert die Inhalte von Dateifeldern mit. Je nach Dateigröße und limit kann das sehr langsam werden.

Beispiel: includeFileContent=true

order object

Sortiert nach den angegebenen Feldern, beliebig viele Felder sind möglich.

Beispiel: order[fieldName]=ASC

Format in der URL: order[fieldName]=ASC&order[otherField]=DESC

filter object

Filtert nach Feldwerten.

Beispiel: filter[fieldName]=someValue

  • Mehrere Werte trennen Sie mit „|“, sie werden mit ODER verknüpft:

    filter[fieldName]=someValue|someOtherValue

  • Datensätze nach ihrer ID filtern:

    filter[id]=123|456|789

  • Universeller Filter auf den Datensatznamen, ohne das Hauptfeld des Moduls zu kennen:

    filter[recordName]=Name1|Name2

  • Filterwerte sind Rohwerte im selben Format wie in der Antwort. Ausnahme sind Referenzfelder: Dort geht auch Text statt Objekt oder ID.

  • Beginnt der Wert mit „!“, bedeutet das „ungleich“. Mit „|“ getrennte Werte werden dann mit UND verknüpft.

  • Mit > und < als erstem Zeichen suchen Sie größere oder kleinere Werte:

    filter[fieldName]=>someValue|<someOtherValue

  • Text filtert als LIKE-Suche, ein Teiltreffer genügt. Ein zusätzliches Gleichheitszeichen erzwingt exakte Treffer:

    filter[fieldName]==someExactValue

  • Kombiniert mit „ungleich“:

    filter[fieldName]=!=notSomeExactValue

  • Ist der Vergleichswert bei Referenzfeldern numerisch, gilt er als ID statt als Name.

  • Referenzfelder lassen sich auch über die Datensatznummer filtern.

  • Bei Datumsfeldern mit Uhrzeit ignorieren „gleich“ und „ungleich“ die Sekunden.

  • Telefonnummern lassen sich mit einem Regex-Filter vergleichen, der nur die Ziffern und ihre Reihenfolge berücksichtigt.

  • Aktiviert wird er über den exakten Filter mit ==.

  • Dafür alle Ziffern angeben, eine Suche nur nach der Vorwahl ist nicht möglich.

  • Schreibweisen wie +49… oder 0049… werden dabei nicht automatisch umgewandelt.

  • Ein Feld mehrfach filtern: [] anhängen. Jeder Filter für dieses Feld braucht dann die Klammern, sonst wird er falsch überschrieben:

    filter[fieldName][]=someValue&filter[fieldName][]=someOtherValue
filter0 object

Für komplexere Filter lassen sich mehrere Filtergruppen bilden, die Ziffer bestimmt die Gruppe. Felder innerhalb einer Gruppe werden immer mit UND verknüpft, die Gruppen untereinander mit filterOr per ODER.

Beispiel: filter0[fieldName]=someValue

Format in der URL: filter0[firstname]=John&filter0[lastname]=Doe

filterOr boolean

Verknüpft die Filterfelder oder Filtergruppen mit ODER statt UND. Gibt es mindestens zwei Gruppen, betrifft das nur die Verknüpfung der Gruppen, nicht die Felder darin.

Antwortfelder · 200

status integer

Statuscode der Antwort.

message string

Meldung zur Antwort.

metadata object

Metainformationen zum Ergebnis.

metadata.total integer

Gesamtzahl der Datensätze für die Abfrage.

metadata.actual integer

Anzahl der Datensätze im Array data. Ändern lässt sie sich über den Query-Parameter limit.

metadata.editable array of integers

IDs der Datensätze im Ergebnis, die der Benutzer bearbeiten darf.

metadata.deletable array of integers

IDs der Datensätze im Ergebnis, die der Benutzer löschen darf.

metadata.deleted array of integers

IDs der Datensätze im Ergebnis, die gelöscht sind und im Papierkorb liegen.

data array of objects

Jeder Datensatz enthält neben der ID alle angefragten Felder, die Auswahl steuert der Query-Parameter fields. Besonderheiten je Feldtyp:

  • Reference: Objekt mit ID und Name, damit keine weitere Abfrage nötig ist. Dazu kommen der Entitätsname und die Angabe, ob der Benutzer den Datensatz sehen darf.

  • UsersGroupsReference: wie Reference.

  • Date: Wert im Format ISO 8601.

  • File: Dateifelder liefert die Liste aus Performancegründen nicht.

data[].id integer

Die ID des Datensatzes.

POST /entity/{entityId}/records

Datensatz anlegen

Legt einen neuen Datensatz in einer Entität an.

Authentifizierung: Bearer-Token (JWT)

Pfadparameter

entityId integer erforderlich

Die ID der Entität.

Beispiel: 6

Request-Body

application/vnd.brainformatik.crm-v1+json

erforderlich

Die Daten des neuen Datensatzes. Enthält das Objekt Felder oder Werte, die der Benutzer nicht setzen darf, antwortet die API mit einem Fehler. Das gilt auch, wenn ein Pflichtfeld fehlt.

Der Datensatz wird mit denselben Regeln geprüft wie in der Bearbeitungsansicht von brainX: bedingte Pflichtfelder, Datumsabhängigkeiten, Eindeutigkeit und modulspezifische Regeln. Schlägt eine Regel fehl, antwortet die API mit 400 und der Meldung „Validation failed“, die jedes betroffene Feld mit Grund nennt.

Werte übergeben Sie im selben Format, in dem die API sie liefert. Ausnahmen gelten für diese Feldtypen:

  • Reference: die ID des verknüpften Datensatzes.

  • UsersGroupsReference: wie Reference. assigned_user_id darf auch eine Gruppe aus der Hilfsentität Groups sein, alle anderen UsersGroupsReference-Felder nur Benutzer.

  • Das Feld für die Datensatznummer erzeugt brainX automatisch.

<feldname> je nach Feldtyp

Jedes Feld der Entität, zum Beispiel accountname oder assigned_user_id bei Accounts. Welche Felder es gibt und welche Pflicht sind, liefert GET /metadata/entities/{entityId}.

lineItems array of objects

Positionen des Datensatzes. Pflicht bei Modulen mit Positionen, bei Deals optional.

Achtung: lineItems in der richtigen Reihenfolge übergeben, sonst ist das Verhalten undefiniert.

entityId integer erforderlich

ID des Produkts oder der Dienstleistung dieser Position.

Beispiel: 1

productName string erforderlich

Name der Position. Er darf vom Namen des Produkts oder der Dienstleistung abweichen.

Beispiel: "Some product"

listPrice number (double) erforderlich

Einzelpreis der Position, bis zu 3 Nachkommastellen. Intern speichert brainX einen hochgenauen Dezimalwert, dokumentieren lässt sich hier nur double.

Beispiel: 223.95

quantity number (float) erforderlich

Menge der Position, bis zu 3 Nachkommastellen.

Beispiel: 25.552

comment string

Zusätzliche Beschreibung der Position.

Beispiel: "This is a product for various purposes."

grossItem boolean

Bei true ist die Position eine Bruttoposition: listPrice gilt dann als Bruttopreis, discountAmount als Bruttowert. Der Wert sollte zur Einstellung des Produkts oder der Dienstleistung aus entityId passen.

Beispiel: false

discountPercent number (float)

Rabatt in Prozent. Je Position gilt entweder discountPercent oder discountAmount, sind beide gesetzt, gewinnt discountPercent.

Beispiel: 5

discountAmount number (double)

Rabatt als Betrag, bei grossItem = true als Bruttowert. Je Position gilt entweder discountPercent oder discountAmount, sind beide gesetzt, gewinnt discountPercent.

Beispiel: 100

taxClass integer

ID der Steuerklasse der Position. 0 bedeutet keine Steuerklasse und ist der Standard.

Beispiel: 412

productBlockName string

Produktblock der Position, ohne Angabe gilt der Standardblock. Werte: „ArticleList1“ für den Standardblock oder „article_list_1“, wobei die Ziffer je nach Zahl der Produktblöcke im System wechselt.

Beispiel: "article_list_2"

optionalLineItem boolean

Bei true ist die Position optional. Nur im Modul Potentials (Deals).

Beispiel: false

alternativeLineItem boolean

Bei true ist die Position eine Alternative. Nur im Modul Potentials (Deals).

Beispiel: false

alternativeParentNumber integer

Kennung einer Hauptposition für Alternativen. Jede Position, deren alternativeParentIdentifier diese Zahl trägt, wird Alternative zu dieser Position.

alternativeParentIdentifier integer

Gilt für alle Alternativen einer Hauptposition und trägt dieselbe Zahl wie deren alternativeParentNumber.

cf_* je nach Feld

Benutzerdefiniertes Feld der Position. Ersetzen Sie den Schlüssel durch den Feldnamen, z. B. cf_1725.

Beispiel: "custom field value"

BEISPIEL AUS DER POSTMAN-COLLECTION: DEAL MIT POSITIONEN, POST /entity/2/records

{
  "potentialname": "Über neuen Service",
  "assigned_user_id": 1,
  "closingdate": "2021-07-31T00:00:00+0000",
  "related_to": 1016,
  "sales_stage": "Value Proposition",
  "record_currency_id": 405,
  "lineItems": [
    {
      "entityId": 1516,
      "productName": "Product for Invoice",
      "listPrice": 2500,
      "quantity": 3,
      "comment": "This is some random comment!",
      "discountPercent": 10,
      "taxClass": 412,
      "productBlockName": "ArticleList1"
    },
    {
      "entityId": 1515,
      "productName": "Service for Invoice",
      "listPrice": 210,
      "quantity": 2,
      "comment": "This is another random comment!",
      "discountAmount": 10,
      "taxClass": 413,
      "optionalLineItem": true,
      "productBlockName": "ArticleList1"
    },
    {
      "entityId": 1509,
      "productName": "The main product",
      "listPrice": 2500,
      "quantity": 3,
      "comment": "This is some random comment!",
      "discountPercent": 10,
      "taxClass": 412,
      "alternativeParentNumber": 1,
      "productBlockName": "article_list_2"
    },
    {
      "entityId": 1509,
      "productName": "The main product",
      "listPrice": 2500,
      "quantity": 3,
      "comment": "This is some random comment!",
      "discountPercent": 10,
      "taxClass": 412,
      "alternativeParentIdentifier": 1
    }
  ]
}

Antwortfelder · 201

status integer

Statuscode der Antwort.

message string

Meldung zur Antwort.

metadata object

Metainformationen zum Ergebnis.

metadata.editable boolean

Ob der Benutzer den Datensatz bearbeiten darf.

metadata.deletable boolean

Ob der Benutzer den Datensatz löschen darf.

data object

Alle Felder, die der Metadata-Endpunkt für die Entität beschreibt. Besonderheiten je Feldtyp:

  • Reference: Objekt mit ID und Name, damit keine weitere Abfrage nötig ist.

  • UsersGroupsReference: wie Reference.

  • Date: Wert im Format ISO 8601.

  • File: Objekt mit name und Base64-kodiertem content. Ein solches Feld hat derzeit nur die Entität Documents.

data.id integer

Die ID des Datensatzes.

data.someFile.name string

Originaler Dateiname eines Dateifelds.

data.someFile.content string

Inhalt der Datei, Base64-kodiert.

GET /entity/{entityId}/records/{recordId}

Einzelnen Datensatz abrufen

Liefert alle Daten eines Datensatzes. Details zu den Datenfeldern liefert der passende Metadata-Endpunkt.

Authentifizierung: Bearer-Token (JWT)

Pfadparameter

entityId integer erforderlich

Die ID der Entität.

Beispiel: 6

recordId integer erforderlich

Die ID des Datensatzes.

Query-Parameter

includeFileContent boolean

Bei false liefert die API die Inhalte von Dateifeldern nicht mit. Das spart bei größeren Dateien Antwortzeit, wenn sie nicht direkt gebraucht werden.

Beispiel: includeFileContent=false

Antwortfelder · 200

status integer

Statuscode der Antwort.

message string

Meldung zur Antwort.

metadata object

Metainformationen zum Ergebnis.

metadata.editable boolean

Ob der Benutzer den Datensatz bearbeiten darf.

metadata.deletable boolean

Ob der Benutzer den Datensatz löschen darf.

metadata.deleted boolean

Ob der Datensatz gerade im Papierkorb liegt.

data object

Alle Felder, die der Metadata-Endpunkt für die Entität beschreibt. Besonderheiten je Feldtyp:

  • Reference: Objekt mit ID und Name, damit keine weitere Abfrage nötig ist. Dazu kommen der Entitätsname, eine Datensatznummer und die Angabe, ob der Benutzer den Datensatz sehen darf.

  • UsersGroupsReference: wie Reference.

  • Date: Wert im Format ISO 8601.

  • File: Objekt mit name und content. Ein solches Feld hat derzeit nur die Entität Documents.

data.id integer

Die ID des Datensatzes.

data.someFile.name string

Originaler Dateiname eines Dateifelds.

data.someFile.content string

Inhalt der Datei, Base64-kodiert.

data.lineItems array of objects

Bei Entitäten mit Positionen eines der Felder, mit den Details der Positionen.

data.lineItems[].entityId integer

ID des Produkts oder der Dienstleistung.

data.lineItems[].lineItemId integer

ID der Position. Fehlt sie beim Bearbeiten, gilt die Position als neu.

data.lineItems[].lineItemType string

Art von entityId: Products oder Services.

data.lineItems[].productName string

Name der Position.

data.lineItems[].listPrice number (double)

Einzelpreis der Position, bis zu 3 Nachkommastellen. Bei Bruttopositionen ist das der berechnete Nettopreis.

data.lineItems[].grossListPrice number (double)

Bruttoeinzelpreis, bis zu 3 Nachkommastellen. Nur bei Bruttopositionen. Beim Bearbeiten dieser Position als listPrice übergeben.

data.lineItems[].quantity number (float)

Menge der Position, bis zu 3 Nachkommastellen.

data.lineItems[].totalPrice number (double)

listPrice mal quantity. Nur zur Anzeige, wird automatisch berechnet und lässt sich nicht ändern.

data.lineItems[].afterDiscountPrice number (double)

Nettopreis nach Rabatt, vor Steuern. Nur zur Anzeige, wird automatisch berechnet.

data.lineItems[].taxPercent number (float)

Steuersatz der Position zur Anzeige, revisionssicher gespeichert. Damit beim Bearbeiten der richtige Satz gilt, setzen Sie lineItemId bei bestehenden Positionen korrekt.

data.lineItems[].taxValue number (double)

Steuerbetrag der Position, bei Gruppensteuer 0. Nur zur Anzeige, wird automatisch berechnet.

data.lineItems[].netPrice number (double)

Nettopreis der Position, nachdem alles angewendet wurde. Bei individueller Steuer entspricht er dem Bruttowert, bei Gruppensteuer enthält er keine Steuern. Nur zur Anzeige, wird automatisch berechnet.

data.lineItems[].comment string

Zusätzliche Beschreibung der Position.

data.lineItems[].grossItem boolean

Bei true ist die Position eine Bruttoposition: listPrice gilt als Bruttopreis, discountAmount als Bruttowert.

data.lineItems[].discountPercent number (float)

Rabatt in Prozent. Je Position gilt entweder discountPercent oder discountAmount, sind beide gesetzt, gewinnt discountPercent.

data.lineItems[].discountAmount number (double)

Rabatt als Betrag, bei Bruttopositionen der berechnete Nettowert. Je Position gilt entweder discountPercent oder discountAmount.

data.lineItems[].discountGrossAmount number (double)

Nur bei Bruttopositionen: der angegebene Rabattbetrag. Beim Bearbeiten dieser Position verwenden.

data.lineItems[].totalWeightPosition number (double)

Gewicht eines Stücks mal Menge.

data.lineItems[].surcharge number (float)

Aufschlag in Prozent. Beim Bearbeiten die Grundlage der Berechnung.

data.lineItems[].surchargeTotal number (float)

Betrag des Aufschlags. Beim Bearbeiten ignoriert, brainX berechnet ihn aus surcharge.

data.lineItems[].taxClass integer

ID der Steuerklasse der Position. 0 bedeutet keine Steuerklasse und ist der Standard.

data.lineItems[].optionalLineItem boolean

Bei true ist die Position optional. Nur im Modul Potentials (Deals).

data.lineItems[].alternativeLineItem boolean

Bei true ist die Position eine Alternative. Nur im Modul Potentials (Deals).

data.lineItems[].alternativeParentId integer

lineItemId der Hauptposition, wenn diese Position eine Alternative ist. 0 steht für eine normale Position.

data.lineItems[].cf_* je nach Feld

Benutzerdefiniertes Feld der Position. Der Schlüssel ist der Feldname, z. B. cf_1725.

PATCH /entity/{entityId}/records/{recordId}

Datensatz bearbeiten

Ändert einen bestehenden Datensatz einer Entität. Geändert werden nur die übergebenen Felder.

Authentifizierung: Bearer-Token (JWT)

Pfadparameter

entityId integer erforderlich

Die ID der Entität.

Beispiel: 6

recordId integer erforderlich

Die ID des Datensatzes.

Request-Body

application/vnd.brainformatik.crm-v1+json

erforderlich

Die zu ändernden Daten. Enthält das Objekt Felder oder Werte, die der Benutzer nicht ändern darf, antwortet die API mit einem Fehler. Pflichtfelder, die im Objekt stehen, brauchen einen Wert.

Die übergebenen Felder werden mit denselben Regeln geprüft wie in der Bearbeitungsansicht von brainX: bedingte Pflichtfelder, Datumsabhängigkeiten, Eindeutigkeit und modulspezifische Regeln. Abhängigkeiten prüft die API gegen die gespeicherten Werte des Datensatzes. Schlägt eine Regel fehl, antwortet sie mit 400 und der Meldung „Validation failed“, die jedes betroffene Feld mit Grund nennt.

Werte übergeben Sie im selben Format, in dem die API sie liefert. Ausnahmen gelten für diese Feldtypen:

  • Reference: die ID des verknüpften Datensatzes.

  • UsersGroupsReference: wie Reference. assigned_user_id darf auch eine Gruppe aus der Hilfsentität Groups sein, alle anderen UsersGroupsReference-Felder nur Benutzer.

  • Das Feld für die Datensatznummer ist nicht änderbar.

<feldname> je nach Feldtyp

Jedes Feld der Entität, zum Beispiel accountname oder assigned_user_id bei Accounts. Welche Felder es gibt und welche Pflicht sind, liefert GET /metadata/entities/{entityId}.

lineItems array of objects

Optional beim Bearbeiten, nur bei Modulen mit Positionen. Ist lineItems gesetzt, muss die Liste alle Positionen enthalten: Steht nur eine Position darin, entfernt brainX alle übrigen.

Achtung: lineItems in der richtigen Reihenfolge übergeben, sonst ist das Verhalten undefiniert.

entityId integer erforderlich

ID des Produkts oder der Dienstleistung dieser Position.

Beispiel: 1

productName string erforderlich

Name der Position. Er darf vom Namen des Produkts oder der Dienstleistung abweichen.

Beispiel: "Some product"

listPrice number (double) erforderlich

Einzelpreis der Position, bis zu 3 Nachkommastellen. Intern speichert brainX einen hochgenauen Dezimalwert, dokumentieren lässt sich hier nur double.

Beispiel: 223.95

quantity number (float) erforderlich

Menge der Position, bis zu 3 Nachkommastellen.

Beispiel: 25.552

lineItemId integer

ID einer bestehenden Position, wie sie GET liefert. Fehlt sie beim Bearbeiten, gilt die Position als neu.

Beispiel: 2

comment string

Zusätzliche Beschreibung der Position.

Beispiel: "This is a product for various purposes."

grossItem boolean

Bei true ist die Position eine Bruttoposition: listPrice gilt dann als Bruttopreis, discountAmount als Bruttowert. Der Wert sollte zur Einstellung des Produkts oder der Dienstleistung aus entityId passen.

Beispiel: false

discountPercent number (float)

Rabatt in Prozent. Je Position gilt entweder discountPercent oder discountAmount, sind beide gesetzt, gewinnt discountPercent.

Beispiel: 5

discountAmount number (double)

Rabatt als Betrag, bei grossItem = true als Bruttowert. Je Position gilt entweder discountPercent oder discountAmount, sind beide gesetzt, gewinnt discountPercent.

Beispiel: 100

taxClass integer

ID der Steuerklasse der Position. 0 bedeutet keine Steuerklasse und ist der Standard.

Beispiel: 412

productBlockName string

Produktblock der Position, ohne Angabe gilt der Standardblock. Werte: „ArticleList1“ für den Standardblock oder „article_list_1“, wobei die Ziffer je nach Zahl der Produktblöcke im System wechselt.

Beispiel: "article_list_2"

optionalLineItem boolean

Bei true ist die Position optional. Nur im Modul Potentials (Deals).

Beispiel: false

alternativeLineItem boolean

Bei true ist die Position eine Alternative. Nur im Modul Potentials (Deals).

Beispiel: false

alternativeParentNumber integer

Kennung einer Hauptposition für Alternativen. Jede Position, deren alternativeParentIdentifier diese Zahl trägt, wird Alternative zu dieser Position.

alternativeParentIdentifier integer

Gilt für alle Alternativen einer Hauptposition und trägt dieselbe Zahl wie deren alternativeParentNumber.

alternativeParentId integer

lineItemId der Hauptposition. Ist sie gesetzt, wird diese Position zur Alternative. Existiert die Hauptposition noch nicht, nutzen Sie alternativeParentIdentifier. Der Wert 0 macht aus der Alternative wieder eine normale Position.

cf_* je nach Feld

Benutzerdefiniertes Feld der Position. Ersetzen Sie den Schlüssel durch den Feldnamen, z. B. cf_1725.

Beispiel: "custom field value"

Antwortfelder · 200

status integer

Statuscode der Antwort.

message string

Meldung zur Antwort.

metadata object

Metainformationen zum Ergebnis.

metadata.editable boolean

Ob der Benutzer den Datensatz bearbeiten darf.

metadata.deletable boolean

Ob der Benutzer den Datensatz löschen darf.

data object

Alle Felder, die der Metadata-Endpunkt für die Entität beschreibt. Besonderheiten je Feldtyp:

  • Reference: Objekt mit ID und Name, damit keine weitere Abfrage nötig ist.

  • UsersGroupsReference: wie Reference.

  • Date: Wert im Format ISO 8601.

  • File: Objekt mit name und Base64-kodiertem content. Ein solches Feld hat derzeit nur die Entität Documents. Die alte Datei wird ersetzt.

data.id integer

Die ID des Datensatzes.

data.someFile.name string

Originaler Dateiname eines Dateifelds.

data.someFile.content string

Inhalt der Datei, Base64-kodiert.

DELETE /entity/{entityId}/records/{recordId}

Datensatz löschen

Markiert einen Datensatz als gelöscht. In brainX lässt er sich aus dem Papierkorb wiederherstellen.

Authentifizierung: Bearer-Token (JWT)

Pfadparameter

entityId integer erforderlich

Die ID der Entität.

Beispiel: 6

recordId integer erforderlich

Die ID des Datensatzes.

Antwortfelder · 200

status integer

Statuscode der Antwort.

message string

Meldung zur Antwort.

GET /entity/{entityId}/records/{recordId}/changes

Letzte Feldänderungen abrufen

Liefert je Feld die letzte Änderung des Datensatzes auf Basis der Änderungsverfolgung. Wurde ein Feld nie geändert, entspricht der Eintrag dem Anlagezeitpunkt.

Authentifizierung: Bearer-Token (JWT)

Pfadparameter

entityId integer erforderlich

Die ID der Entität.

Beispiel: 6

recordId integer erforderlich

Die ID des Datensatzes.

Antwortfelder · 200

status integer

Statuscode der Antwort.

message string

Meldung zur Antwort.

data object

Feldnamen mit dem Datum ihrer letzten Änderung laut Änderungsverfolgung, je Feld ein Eintrag.

data.fieldName1 object

Details zum Feld mit dem Namen fieldName1.

data.fieldName1.id integer

Die ID des Felds.

data.fieldName1.lastChanged string

Datum der letzten Änderung des Felds, im Format ISO 8601.

Ressource

Auth

Anmelden, abmelden, Token erneuern und Zwei-Faktor-Code einlösen. Login und Zwei-Faktor-Code laufen ohne Token, alle anderen Aufrufe brauchen ein gültiges Access-Token.

4 Endpunkte

POST /auth

Login

Alle anderen Aufrufe brauchen eine gültige Authentifizierung, die Sie mit diesem Aufruf erhalten. Ist die Zwei-Faktor-Authentifizierung aktiv, nutzen Sie ein App-Passwort oder den üblichen Ablauf mit Challenge-Token (nur TOTP, nicht WebAuthn).

Authentifizierung: ohne Token

Query-Parameter

setCookie integer

Bei „1“ setzt die API ein httpOnly-Cookie zur Authentifizierung und gibt nur das refreshToken zurück.

Request-Body

application/vnd.brainformatik.crm-v1+json oder application/vnd.brainformatik.crm-v2+json

erforderlich

Die Anmeldedaten des Benutzers. Beim Medientyp v2 wird das App-Passwort als SHA-512-Hash übertragen.

user string erforderlich

Der Benutzername, der angemeldet wird.

password string

Das Passwort des Benutzers. Ist die Zwei-Faktor-Authentifizierung aktiv, können Sie stattdessen ein App-Passwort verwenden, das Sie unter „Meine Einstellungen“ anlegen. Ohne apiPassword und mit aktivem TOTP antwortet die API mit 201 und einem Challenge-Token für POST /auth/code.

apiPassword string

Bei aktiver Zwei-Faktor-Authentifizierung statt des Passworts. Beim Medientyp v2 als SHA-512-Hash des App-Passworts.

Antwortfelder · 200

status integer

Statuscode der Antwort.

message string

Meldung zur Antwort.

data object

Objekt mit den Tokens.

data.accessToken string

JWT-Access-Token für den Header Authorization bei jeder Anfrage. 15 Minuten gültig.

data.refreshToken string

Refresh-Token, mit dem Sie ein abgelaufenes Access-Token erneuern. 7 Tage gültig.

Antwortfelder · 201

status integer

Statuscode der Antwort.

message string

Meldung zur Antwort.

data object

Objekt mit dem Challenge-Token.

data.challengeToken string

Challenge-Token für POST /auth/code, 60 Sekunden gültig.

DELETE /auth

Logout

Meldet den Benutzer ab.

Authentifizierung: Bearer-Token (JWT)

Dieser Endpunkt erwartet keine Parameter.

POST /auth/refresh

Access-Token erneuern

Erneuert das Access-Token und erzeugt dabei ein neues Refresh-Token. Für die nächste Erneuerung gilt dieses neue Refresh-Token, das alte wird ersetzt.

Authentifizierung: Bearer-Token (JWT)

Query-Parameter

setCookie integer

Bei „1“ setzt die API ein httpOnly-Cookie zur Authentifizierung und gibt nur das refreshToken zurück.

Request-Body

application/vnd.brainformatik.crm-v1+json

erforderlich

Das Refresh-Token, mit dem erneuert wird.

refreshToken string erforderlich

Das Refresh-Token.

Beispiel: "c7701a80c1eda9761484f0d64f458d7bc2..."

Antwortfelder · 200

status integer

Statuscode der Antwort.

message string

Meldung zur Antwort.

data object

Objekt mit den Tokens.

data.accessToken string

JWT-Access-Token für den Header Authorization bei jeder Anfrage. 15 Minuten gültig.

data.refreshToken string

Refresh-Token, mit dem Sie ein abgelaufenes Access-Token erneuern. 7 Tage gültig.

POST /auth/code

Zwei-Faktor-Code einlösen

Schließt einen offenen Login ab, mit dem Challenge-Token aus der Antwort von POST /auth und dem Zwei-Faktor-Code.

Authentifizierung: ohne Token

Query-Parameter

setCookie integer

Bei „1“ setzt die API ein httpOnly-Cookie zur Authentifizierung und gibt nur das refreshToken zurück.

Request-Body

application/vnd.brainformatik.crm-v1+json

erforderlich

Die Daten, mit denen der Login abgeschlossen wird.

challengeToken string erforderlich

Das Challenge-Token aus der Antwort von POST /auth (Status 201), wenn für den Benutzer 2FA mit TOTP aktiv ist. Es gilt 60 Sekunden.

Beispiel: "c7701a80c1eda9761484f0d64f458d7bc2..."

code string erforderlich

Der Zwei-Faktor-Code aus der Authenticator-App, als Text.

Beispiel: "643345"

Antwortfelder · 200

status integer

Statuscode der Antwort.

message string

Meldung zur Antwort.

data object

Objekt mit den Tokens.

data.accessToken string

JWT-Access-Token für den Header Authorization bei jeder Anfrage. 15 Minuten gültig.

data.refreshToken string

Refresh-Token, mit dem Sie ein abgelaufenes Access-Token erneuern. 7 Tage gültig.

Ressource

Metadata

Entitäten, Blöcke, Felder und Ansichten, so wie sie im Layout-Editor definiert sind. Hier stehen die IDs und Feldnamen, die Sie für die Records-Endpunkte brauchen.

3 Endpunkte

GET /metadata/entities

Metadaten aller Entitäten abrufen

Detaillierte Informationen zu den Entitäten, etwa Übersetzungen und Berechtigungen. Die Liste enthält auch Hilfsentitäten, die zum Anlegen bestimmter Datensätze nötig sind, zum Beispiel Währungen (Currencies) für Rechnungen.

Authentifizierung: Bearer-Token (JWT)

Dieser Endpunkt erwartet keine Parameter.

Antwortfelder · 200

status integer

Statuscode der Antwort.

message string

Meldung zur Antwort.

data array of objects

Je Entität ein Eintrag.

data[].id integer

Die ID der Entität.

data[].name string

Interner Name der Entität. Nur zur Identifikation, nicht zur Anzeige.

data[].icon string

Name des Font-Awesome-Icons, das brainX für die Entität nutzt.

data[].isEntity boolean

Ob es eine echte Entität oder eine Hilfsentität ist.

data[].isInventory boolean

Ob die Entität Positionen hat. Bei Deals sind sie optional.

data[].create boolean

Ob der Benutzer Datensätze dieser Entität anlegen darf.

data[].update boolean

Ob der Benutzer Datensätze dieser Entität bearbeiten darf.

data[].delete boolean

Ob der Benutzer Datensätze dieser Entität löschen darf.

data[].readonly boolean

Bei true lassen sich die Datensätze über die API nur lesen, nicht ändern oder löschen.

data[].label string

Modulname in der Sprache des Benutzers, zur Anzeige. Hilfsentitäten haben keine Übersetzung, dort steht der Name.

data[].singular string

Modulname im Singular in der Sprache des Benutzers. Fehlt bei Hilfsentitäten.

data[].views array of objects

Verfügbare Ansichten des Moduls. Hilfsentitäten haben keine.

data[].views[].id integer

ID der Ansicht.

data[].views[].name string

Anzeigename der Ansicht.

data[].views[].default boolean

Ob es die Standardansicht des Benutzers ist.

data[].nameFields array of strings

Felder, die den Titel eines Datensatzes bilden. Meist eines, selten zwei, z. B. firstname und lastname bei Contacts.

GET /metadata/entities/{entityId}

Metadaten einer Entität abrufen

Detaillierte Informationen zu Blöcken und Feldern des Moduls. Blöcke und Felder sind so sortiert, wie sie im Layout-Editor definiert sind.

Authentifizierung: Bearer-Token (JWT)

Pfadparameter

entityId integer erforderlich

Die ID der Entität.

Query-Parameter

country string

Ländercode nach ISO 3166-1 alpha-2. Ist er gesetzt, listen Felder vom Typ StateCode die Regionalcodes dieses Landes als Werte. Ohne ihn liefern StateCode-Felder keine Werte.

Beispiel: country=DE

Antwortfelder · 200

status integer

Statuscode der Antwort.

message string

Meldung zur Antwort.

data.fields array of objects

Die Felder der Entität.

data.fields[].name string

Feldname, mit dem Sie Werte lesen und beim Anlegen oder Bearbeiten setzen.

data.fields[].label string

Feldbezeichnung in der Sprache des Benutzers, zur Anzeige.

data.fields[].length integer

Länge des Felds. 0 bedeutet, dass das Feld keine bestimmte Länge braucht.

data.fields[].type string

Feldtyp, einer der Werte unter Grundbegriffe › Feldtypen.

data.fields[].block integer

ID des Blocks. Die Bezeichnung steht unter blocks.

data.fields[].required boolean

Bei true ist das Feld beim Anlegen und Bearbeiten Pflicht.

data.fields[].editable boolean

Bei true lässt sich das Feld beim Anlegen und Bearbeiten setzen.

data.fields[].refEntities array of strings

Interne Modulnamen, auf die das Feld verweisen kann. Nur bei Feldern vom Typ Reference.

data.fields[].values array of objects

Mögliche Werte des Felds. Liefert eine Auswahlliste keine Werte, kommen sie eventuell aus einer Hilfsentität wie InventoryTax oder Currencies. Felder vom Typ StateCode liefern Werte nur mit dem Query-Parameter country, weil die vollständige Liste nach ISO 3166-2 Tausende Einträge hat.

data.fields[].values[].value string | integer

Der Wert, wie er im Datensatz steht. Mit ihm speichern Sie auch beim Anlegen und Bearbeiten.

data.fields[].values[].label string

Übersetzte Bezeichnung zur Anzeige, meist in Auswahlfeldern.

data.fields[].values[].color object

Optional. Nur vorhanden, wenn in der Feldkonfiguration der Modulverwaltung (Layout-Einstellungen) für mindestens einen Wert des Felds eine Farbe definiert ist.

data.fields[].values[].color.background string

Hex-Farbe für den Hintergrund.

data.fields[].values[].color.text string

Hex-Farbe für den Text.

data.fields[].format string

Formatangabe für die Anzeige nach den Einstellungen des Benutzers, z. B. bei Datumsfeldern. Datumswerte selbst kommen immer im Format ISO 8601.

data.fields[].richText boolean

Nur bei Typ Textarea: Bei true darf das Feld HTML enthalten.

data.blocks array of objects

Die Blöcke der Entität.

data.blocks[].id integer

ID des Blocks. Sie steht auch in fields und ordnet die Felder den Blöcken zu.

data.blocks[].label string

Blockbezeichnung in der Sprache des Benutzers.

data.userDefinedFields array of objects

Benutzerdefinierte Felder der Positionen bei Modulen mit Positionen.

data.userDefinedFields[].name string

Feldname des benutzerdefinierten Felds.

data.userDefinedFields[].label string

Übersetzter Feldname.

data.userDefinedFields[].length integer

Maximale Länge des Felds.

data.userDefinedFields[].type string

Feldtyp.

data.userDefinedFields[].block integer

ID des Blocks.

data.userDefinedFields[].required boolean

Ob das Feld Pflicht ist.

data.userDefinedFields[].editable boolean

Ob sich das Feld bearbeiten lässt.

GET /metadata/entities/{entityId}/view/{viewId}

Metadaten einer Entität mit eigener Bearbeitungsansicht abrufen

Detaillierte Informationen zu Blöcken und Feldern des Moduls in einer bestimmten Ansicht. Blöcke und Felder sind so sortiert, wie sie im Layout-Editor definiert sind.

Authentifizierung: Bearer-Token (JWT)

Pfadparameter

entityId integer erforderlich

Die ID der Entität.

viewId integer erforderlich

Die ID der Ansicht. Vorhandene Ansichten stehen im Ergebnis von /metadata/entities.

Query-Parameter

country string

Ländercode nach ISO 3166-1 alpha-2. Ist er gesetzt, listen Felder vom Typ StateCode die Regionalcodes dieses Landes als Werte. Ohne ihn liefern StateCode-Felder keine Werte.

Beispiel: country=DE

Ressource

Relations

Verknüpfungen eines Datensatzes lesen und neue Verknüpfungen anlegen. Die API liefert nur Datensätze und Entitäten, die der Benutzer sehen darf.

2 Endpunkte

GET /relations/{recordId}

Verknüpfungen eines Datensatzes abrufen

Liefert die Entitäten und Datensätze, die mit dem angegebenen Datensatz verknüpft sind. Zurück kommt nur, was der Benutzer sehen darf. Details zu den Datensätzen holen Sie über die Records-Liste mit einem Filter auf id. Die URL dafür sollte nicht länger als 2.000 Zeichen sein, das reicht auch für 200 Datensätze mit IDs ab 1.000.000.

Authentifizierung: Bearer-Token (JWT)

Pfadparameter

recordId integer erforderlich

Die ID des Datensatzes.

Antwortfelder · 200

[] array of objects

Verknüpfte Entitäten und ihre Datensätze, je Entität ein Eintrag.

[].entityId integer

Die ID der verknüpften Entität. Mit ihr holen Sie die verknüpften Datensätze über die Records-Liste.

[].entityName string

Interner Name der Entität.

[].label string

Übersetzte Bezeichnung der Verknüpfung, zur Anzeige.

[].count integer

Anzahl der verknüpften Datensätze.

[].idList array of integers

IDs der verknüpften Datensätze. Zusammen mit entityId und einem Filter auf id in der Records-Liste nutzen.

[].add boolean

Bei true legen Sie per POST eine neue Verknüpfung an. Sonst muss ein neuer Datensatz angelegt werden, weil die Verknüpfung meist über ein Feld im verknüpften Modul entsteht.

POST /relations/{recordId}

Verknüpfung anlegen

Verknüpft Datensätze mit dem angegebenen Datensatz. Der Benutzer braucht Zugriff auf alle beteiligten Datensätze, und die Entität muss neue Verknüpfungen zulassen. Ob sie das tut, zeigt das Feld add in der Antwort von GET /relations/{recordId}.

Authentifizierung: Bearer-Token (JWT)

Pfadparameter

recordId integer erforderlich

Die ID des Datensatzes, für den die Verknüpfung angelegt wird.

Request-Body

application/vnd.brainformatik.crm-v1+json

erforderlich

Die Datensätze, die mit dem angegebenen Datensatz verknüpft werden.

records array of integers

Liste der Datensätze, die als Verknüpfung hinzukommen.

Antwortfelder · 200

status integer

Statuscode der Antwort.

message string

Meldung zur Antwort.

Ressource

Users

Der angemeldete Benutzer und die Mandanten, auf die er Zugriff hat.

2 Endpunkte

GET /users/current

Angemeldeten Benutzer abrufen

Liefert Details zum angemeldeten Benutzer.

Authentifizierung: Bearer-Token (JWT)

Dieser Endpunkt erwartet keine Parameter.

Antwortfelder · 200

status integer

Statuscode der Antwort.

message string

Meldung zur Antwort.

data object

Ein Teil der Felder, die der Metadata-Endpunkt für die Entität Users beschreibt. Besonderheiten je Feldtyp:

  • Reference: Objekt mit ID und Name, damit keine weitere Abfrage nötig ist.

  • UsersGroupsReference: wie Reference.

  • Date: Wert im Format ISO 8601.

  • Image: Objekt mit name und content, z. B. das Benutzerbild.

data.id integer

Die ID des Benutzers.

data.imagename object

Das Bild des Benutzers.

data.imagename.name string

Originaler Dateiname.

data.imagename.content string

Inhalt der Datei, Base64-kodiert.

GET /users/companies

Zugängliche Mandanten abrufen

Liefert alle Mandanten, auf die der Benutzer Zugriff hat. Welche das sind, legt ein berechtigter Benutzer in den Benutzereinstellungen über das Feld für erlaubte Rollen fest.

Authentifizierung: Bearer-Token (JWT)

Dieser Endpunkt erwartet keine Parameter.

Antwortfelder · 200

status integer

Statuscode der Antwort.

message string

Meldung zur Antwort.

data array of objects

Mandanten, auf die der Benutzer Zugriff hat.

data[].id integer

Die ID des Mandanten.

data[].name string

Der Name des Mandanten.

Anbindung geplant?

Wir sehen uns Ihr Zielsystem an und sagen, welche Endpunkte Sie brauchen.

Technischen Termin buchenFertige Integrationen