reybex API

Dieses Handbuch beschreibt alle Aspekte einer technischen Integration mit der reybex-API – vom ersten Request bis zum produktiven Betrieb. Es richtet sich an Partner und Integratoren, die Drittsysteme (Shop, ERP, PIM, Logistik, BI …) mit reybex verbinden.

1 Einstieg und erste Schritte

1.1 Was ist die reybex API?

Die reybex API ist eine REST-basierte HTTP-Schnittstelle, über die externe Systeme Daten in reybex lesen, anlegen, ändern und löschen können. Sie deckt die gesamte ERP-Funktionalität ab – Artikelstamm, Aufträge, Einkauf, Lager, Finanzen, CRM und mehr.

Alle Aufrufe gehen an einen zentralen Host – es gibt keine separaten URLs pro Partner. Die Mandantentrennung erfolgt über Authentifizierung und Session-Kontext (tenantId).

1.2 Welche Integrationsmöglichkeiten bietet reybex?

Integrationsmuster	Beschreibung
Fach-API	Spezialisierte Endpoints mit Geschäftslogik – z. B. `POST /api/material/` für Artikelanlage inkl. Validierung und Folgeprozessen
Generic Domain API	CRUD direkt auf Domänenmodellen über `/api/domains/{domain}` – schnell für Prototypen und Stammdaten
Connector-Endpoints	Massenimport für Konnektoren und Shops – z. B. `POST /api/material/connector`
Webhooks / Events	Agent-Events bei bestimmten Aktionen (z. B. `material.created`)

1.3 Für wen ist die API-Dokumentation gedacht?

Die Partner-Dokumentation richtet sich an:

Systemintegratoren, die Shop-, ERP- oder PIM-Systeme an reybex anbinden
Agentur-Entwickler, die im Auftrag eines reybex-Kunden Schnittstellen implementieren
technische Partner, die eigene Konnektoren oder Middleware-Lösungen bauen

Die Dokumentation setzt HTTP/REST-Grundkenntnisse, Erfahrung mit JSON und grundlegendes Verständnis von ERP-Prozessen (Artikel, Aufträge, Lager) voraus.

1.4 Welche Voraussetzungen muss ich als Integrator erfüllen?

Technisch: HTTP-Client (cURL, Postman, eigene Anwendung), JSON-Verarbeitung
Organisatorisch: reybex-Partnervertrag oder Beauftragung durch einen reybex-Kunden
Zugang: Integrations-User mit korrekter Mandant-Zuordnung und passenden Rechten – bereitgestellt durch das reybex-Team
Fachlich: Kenntnis der relevanten Geschäftsprozesse (welche Daten fließen wohin?)

1.5 Welche Schritte sind für den Start erforderlich?

Zugang klären – Integrations-User und Mandant vom reybex-Team erhalten
Staging-Umgebung einrichten lassen (siehe Umgebungen)
Authentifizierung einrichten – siehe Authentifizierung
Use Case einordnen – Fach-API, Generic API oder Connector? (siehe API-Typen)
Datenmodell verstehen – Domain-Struktur und Prüftabellen prüfen
Ersten Request senden – in der Staging-Umgebung testen
Produktiv gehen – Endpoint auf Produktion umstellen

1.6 Wo finde ich die technische Dokumentation und Beispiele?

Quelle	Adresse	Zweck
Partner-Dokumentation	Diese Seite und Integration	Kuratierte APIs mit Business-Kontext und Beispielen
API-Artefakte (Postman-kompatibel)	Collection JSON, Environments JSON, Metadaten	Import in Postman, Insomnia, Bruno oder interne Test-Runner
API-Referenzportal	api.reybex.com	Vollständige, interaktive API-Dokumentation aller Endpoints
Swagger UI	core-backend.reybex.com/swagger-ui	Generic Domain API – CRUD auf freigegebenen Domänenmodellen

1.7 Wie sieht der typische Ablauf eines Integrationsprojekts aus?

Typische Dauer: wenige Tage (einfache Stammdaten-Sync) bis mehrere Wochen (vollständiger Belegworkflow mit Konnektoren).

2 Umgebungen und Zugang

2.1 Welche Umgebungen stehen zur Verfügung?

Umgebung	API-Basis	Zweck
Staging (Partner)	`https://io-staging-partner.reybex.com/api`	Entwicklung und Test
Produktion	`https://core-backend.reybex.com/api`	Produktiver Betrieb

Beide Umgebungen verwenden dieselbe API-Struktur und dieselben Endpoints. Der einzige Unterschied ist die Basis-URL und der Datenbestand.

2.2 Wie erhalte ich eine Staging- bzw. Testumgebung?

Eine Staging-Umgebung wird durch reybex bereitgestellt. Kontaktieren Sie Ihren reybex-Ansprechpartner und nennen Sie:

den Zweck der Integration (z. B. „Shop-Anbindung Shopify", „ERP-Sync SAP")
den gewünschten Mandanten (Firma)
die benötigten Funktionsbereiche (Artikel, Aufträge, Kunden etc.)

Das reybex-Team richtet die Umgebung ein und stellt Ihnen Zugangsdaten bereit.

2.3 Wie wird eine neue Staging-Umgebung eingerichtet?

Nach Beantragung übernimmt das reybex-Team folgende Schritte:

Mandant in der Staging-Umgebung anlegen oder bereitstellen
Integrations-User mit passenden Rechten erstellen
Zugangsdaten (Benutzername, Passwort) an den Partner übergeben
Optional: Testdaten (Artikel, Kunden, Prüftabellen) importieren

Der Partner kann anschließend gegen https://io-staging-partner.reybex.com/api entwickeln.

2.4 Wie beantrage ich API-Zugangsdaten?

API-Zugangsdaten werden über Ihren reybex-Ansprechpartner beantragt. Sie erhalten:

Benutzername und Passwort für Basic Auth
Mandant-Zuordnung (welcher Tenant)
Hinweise zu den freigeschalteten Modulen und Rechten

Für Produktion erstellen Sie den API-User typischerweise selbst über die Transaktion SYS08 Benutzer – siehe Benutzer & Rollen.

2.5 Wie unterscheiden sich Test- und Produktionsumgebung?

Aspekt	Staging	Produktion
Daten	Testdaten, frei löschbar	Echte Geschäftsdaten
Stabilität	Kann bei Updates kurz offline sein	Hochverfügbar
Performance	Ggf. eingeschränkt	Volle Kapazität
Zugangsdaten	Separate Credentials	Eigene Produktions-Credentials

WARNING

Staging-Daten können bei Updates oder Neueinrichtung zurückgesetzt werden. Staging nicht als dauerhaften Datenspeicher verwenden.

2.6 Welche API-URLs und Basisadressen muss ich verwenden?

bash

# Staging (Entwicklung & Test)
export API_BASE="https://io-staging-partner.reybex.com/api"

# Produktion (Live-Betrieb)
export API_BASE="https://core-backend.reybex.com/api"

Alle Endpoint-Pfade in dieser Dokumentation sind relativ zur API-Basis angegeben. Beispiel: POST /api/material/ wird zu POST https://core-backend.reybex.com/api/material/.

Es gibt keine eigene Host-URL pro Partner – Mandant und Daten werden über Authentifizierung und Session-Kontext getrennt.

2.7 Wie werden Zugangsdaten sicher verwaltet?

Keine Credentials in Quellcode oder Repos – Umgebungsvariablen oder Secret-Manager verwenden
Separate Zugangsdaten für Staging und Produktion
Minimale Rechte – nur die Rollen zuweisen, die für die Integration benötigt werden
Regelmäßig rotieren – Passwörter bei Personalwechsel oder Verdacht auf Kompromittierung ändern
HTTPS ist Pflicht – alle API-URLs sind TLS-verschlüsselt

3 Authentifizierung und Berechtigungen

3.1 Wie authentifiziere ich meine API-Anfragen?

reybex verwendet Basic Auth. Der Token ist das Base64-kodierte benutzername:passwort:

bash

# Token erzeugen (einmalig)
export TOKEN=$(echo -n "mein-user:mein-passwort" | base64)

# Request mit Basic Auth
curl -s -G "$API_BASE/domains/material" \
  --header "authorization: Basic $TOKEN" \
  --data-urlencode "take=1"

Optional ist auch der Login-Endpoint verfügbar: POST /api/login.

bash

curl -s -X POST "$API_BASE/login" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "mein-user",
    "password": "mein-passwort"
  }'

Für Partner-Integrationen empfehlen wir weiterhin Basic Auth, weil der Ablauf stabil und durchgängig für alle Endpoints gleich ist.

Details: Authentifizierung.

3.2 Welche Zugangsdaten oder API-Keys benötige ich?

Benutzername und Passwort – bereitgestellt durch das reybex-Team oder in SYS08 angelegt
Der Token für den authorization-Header ist das Base64-kodierte benutzername:passwort
Es gibt keine separaten API-Keys – die Authentifizierung läuft über denselben User-Mechanismus wie die UI
Der User muss dem korrekten Mandanten (Tenant) zugeordnet sein

3.3 Welche Rollen und Berechtigungen sind erforderlich?

API-User haben aktuell keine granulare Endpoint-Beschränkung – ein authentifizierter API-User kann alle freigegebenen Endpoints nutzen. Granulare Endpoint-Berechtigungen sind geplant und werden in einem zukünftigen Release eingeführt.

Für die Transaktions-UI gelten rollenbasierte Berechtigungen (z. B. ROLE_CEO, ROLE_ADMIN) – siehe Transaktionen. Für reine API-Integrationen ist das aktuell nicht relevant.

3.4 Welche Berechtigungen benötigt ein Endpoint?

Aktuell benötigt ein API-User keine spezifische Rollenzuweisung pro Endpoint. Ein gültig authentifizierter User mit Mandant-Zuordnung kann alle API-Endpoints aufrufen.

Zukünftig

Endpoint-spezifische Berechtigungen werden in einem kommenden Release implementiert. Wir empfehlen bereits jetzt, API-User mit minimalen Rechten anzulegen und die Dokumentation zu beobachten.

3.5 Wie werden fehlende Berechtigungen erkannt und behoben?

HTTP-Status	Bedeutung	Maßnahme
401 Unauthorized	Ungültige oder fehlende Credentials	Benutzername/Passwort prüfen, Token erneuern
403 Forbidden	User authentifiziert, aber kein Zugriff	Mandant-Zuordnung und Rechte in SYS08 prüfen

json

{
  "error": "Unauthorized"
}

Bei 401/403: Zugangsdaten und Rechte prüfen – nicht den Business-Flow.

3.6 Gibt es zusätzliche Zugriffsbeschränkungen?

Mandantentrennung: Jeder API-Aufruf ist mandantenbezogen. Ein User sieht nur Daten seines Tenants.
IP-Beschränkungen: Standardmäßig keine – bei Bedarf über reybex konfigurierbar.
HTTPS-Pflicht: Unverschlüsselte Verbindungen werden abgelehnt.

4 API-Architektur und API-Typen

4.1 Welche API-Typen bietet reybex an?

reybex bietet drei API-Ebenen:

API-Typ	Basis-Pfad	Dokumentation
Fach-API (spezialisierte Endpoints)	`/api/material/`, `/api/salesHead/` usw.	api.reybex.com + Partner-Docs
Generic Domain API	`/api/domains/{domain}`	Swagger UI
Connector-Endpoints	`/api/{controller}/connector`	Partner-Docs

4.2 Was ist die generische API?

Die Generic Domain API bietet CRUD-Operationen auf freigegebenen Domänenmodellen:

Methode	Pfad	Beschreibung
GET	`/api/domains/showDomains`	Alle verfügbaren Domänen und Felder
GET	`/api/domains/{domain}`	Lesen mit Filtern, Sortierung, Pagination
GET	`/api/domains/{domain}/count`	Anzahl Treffer
POST	`/api/domains/{domain}`	Anlegen oder Aktualisieren
DELETE	`/api/domains/{domain}?id={id}`	Löschen / Soft-Delete

{domain} ist der urlToken der Domäne (z. B. material, customer, stockList).

4.3 Was ist die frontend-nahe API?

Die Fach-API bildet die Geschäftslogik ab, wie sie auch die reybex-UI nutzt:

Validierungen (Pflichtfelder, Referenzen, Berechtigungen)
Folgeprozesse (Nummernkreise, Indexierung, Events)
Workflow-Logik (Folgedokumente, Statuswechsel)

Beispiele: POST /api/material/ (Artikelanlage), POST /api/salesHead/ (Auftrag), POST /api/salesHead/referencingDocuments (Folgebeleg).

4.4 Worin unterscheiden sich die API-Typen?

Aspekt	Fach-API	Generic Domain API	Connector
Geschäftslogik	Voll (Validierung, Events, Workflow)	Minimal (direkt auf DB-Ebene)	Voll (Import-Logik)
Felderkennung	Endpoint-spezifisch	Domänen-Schema	Connector-Schema
Idempotenz	Teilweise (z. B. `sku`, `matCode`)	Nur bei `id`	Oft über `sku`/`matCode`
Swagger	Nur in api.reybex.com	In Swagger UI	In api.reybex.com
Batch-Fähigkeit	Endpoint-abhängig	Einzeln	Arrays (Massenimport)

4.5 Wann sollte ich welchen API-Typ verwenden?

Situation	Empfehlung
Shop-Import, Belegworkflow, Buchung	Fach-API (Integration)
Massenimport (Artikel, Bestände) für Konnektoren	Connector
Stammdaten lesen/schreiben, Lookup, Prototyp	Generic Domain API
Felder und Beziehungen erkunden	Generic API + Domain-Struktur

4.6 Welche Funktionen und Daten sind über welche API verfügbar?

Die Fach-API deckt alle Module ab – siehe Modulübersicht für die vollständige Liste. Die Generic Domain API gibt alle über GET /api/domains/showDomains aufgelisteten Domänen frei – typischerweise Stammdaten und Referenztabellen.

Nicht jede Domäne ist über die Generic API schreibbar; manche sind nur lesbar. Beleglogik (Aufträge, Rechnungen, Folgedokumente) ist nur über die Fach-API verfügbar.

4.7 Welche Geschäftslogik und Validierungen werden ausgeführt?

Fach-API:

Pflichtfeld-Validierung (z. B. matCode, name, Einheiten)
Referenz-Prüfung (existiert die matGroup? Gültige vatKey?)
Nummernkreise (automatische docNumber)
Folgeprozesse (Events, Indexierung, Lagerbestandsupdate)
Statuswechsel und Belegketten

Generic Domain API:

Typ-Validierung (Feldtyp stimmt)
Referenz-Existenz (Foreign-Key)
Keine Beleglogik, keine Nummernkreise, keine Events

Connector:

Import-Logik (Anlegen/Aktualisieren anhand matCode/sku)
Modi für Name, Preis, Bestand, Bilder (nameImportMode, priceImportMode etc.)
Array-Response mit Zeilenfehlern

4.8 Wie finde ich den passenden Endpoint für meinen Anwendungsfall?

Partner-Docs durchsuchen – Integration nach Modul, z. B. api.reybex.com
api.reybex.com – Endpoints nach Fachbereich durchsuchen (z. B. Material, Sales, Stock)
Swagger UI – GET /api/domains/showDomains für alle Generic-API-Domänen
Modulübersicht – Modulübersicht mit Links zu Business, Integration und Domain

5 Allgemeine API-Konventionen

5.1 Welche HTTP-Methoden werden unterstützt?

Methode	Verwendung
GET	Daten lesen, Suchen, Listen abrufen
POST	Anlegen, Aktualisieren, Aktionen ausführen
DELETE	Löschen (Soft- oder Hard-Delete je nach Domäne)

PUT und PATCH werden von reybex-APIs in der Regel nicht verwendet. Aktualisierungen erfolgen über POST mit id im Body.

http

Content-Type: application/json
authorization: Basic <base64(user:pass)>

Header	Wert	Pflicht
`Content-Type`	`application/json`	Ja (bei POST)
`authorization`	`Basic $TOKEN`	Ja
`Accept`	`application/json`	Empfohlen

5.3 Welche Formate werden für Requests und Responses verwendet?

Request-Body: JSON (application/json)
Response-Body: JSON
Zeichenkodierung: UTF-8

5.4 Wie werden Datum, Uhrzeit und Zeitzonen behandelt?

Datumsfelder verwenden das Format yyyy-mm-dd (ISO 8601). Je nach Feld mit oder ohne Uhrzeit:

Nur Datum:

json

{
  "validFrom": "2026-01-01",
  "validUntil": "2026-12-31",
  "orderDate": "2026-10-06"
}

Datum mit Uhrzeit (UTC):

json

{
  "createdDate": "2026-10-06T08:59:12.000Z",
  "lastModified": "2026-10-06T14:30:00.000Z"
}

Die Zeitzone ist UTC (Suffix Z). Zeitstempel in Responses enthalten immer die Uhrzeit.

5.5 Wie werden Zahlen, Dezimalstellen und Währungen übertragen?

Preise und Beträge: als JSON-Number mit Dezimalpunkt, z. B. 19.99
Mengen: als Integer oder Dezimal, z. B. 100 oder 2.5
Währung: als Referenz-Objekt, z. B. "currency": { "code": "EUR" }
Keine Tausender-Trennzeichen im JSON

json

{
  "salesPrice": 19.99,
  "quantity": 2.5,
  "currency": { "code": "EUR" }
}

5.6 Wie werden fehlende Felder, null und Standardwerte interpretiert?

Situation	Verhalten
Feld nicht im Request	Wird beim Anlegen mit Default belegt; beim Update nicht verändert
Feld explizit `null`	Wert wird auf null gesetzt (sofern das Feld nullable ist)
Leerer String `""`	Wird als leerer Wert gespeichert, nicht als null

Systemfelder (id, tenantId, createdDate) werden serverseitig gesetzt und sollten nicht im Request mitgeschickt werden (Ausnahme: id bei Update).

5.7 Wie funktionieren Filter, Sortierung und Pagination?

Für die Generic Domain API (/api/domains/{domain}):

Filter als Query-Parameter feldName=ausdruck:

Ausdruck	Bedeutung
`eq(Wert)`	Gleich (Default, `eq` kann entfallen)
`neq(Wert)`	Ungleich
`gt(Wert)` / `gte(Wert)`	Größer / größer gleich
`lt(Wert)` / `lte(Wert)`	Kleiner / kleiner gleich
`like(%Muster%)`	LIKE-Suche
`between(X,Y)`	Bereich inklusive
`isNull()` / `isNotNull()`	Null-Checks
`isEmpty()` / `isNotEmpty()`	Leer-Checks (Strings)

Referenzen über Punkt-Notation: material.matCode=eq(ART-001).

Pagination und Sortierung:

Parameter	Beschreibung	Default
`take`	Max. Anzahl Ergebnisse	100
`skip`	Offset (für Paging)	0
`sort`	Sortierung, z. B. `name` oder `desc(name)`	—

bash

curl -s -G "$API_BASE/domains/material" \
  --header "authorization: Basic $TOKEN" \
  --data-urlencode "sku=eq(PARTNER-SKU-001)" \
  --data-urlencode "take=50" \
  --data-urlencode "skip=0" \
  --data-urlencode "sort=name"

Fach-API-Endpoints haben teilweise eigene Filter-Syntax (z. B. filter=material.matCode~eq~ART-001 bei Stock-Endpoints). Details in der jeweiligen API-Seite.

5.8 `customFields`: JSON-Inhalt aktualisieren, lesen und filtern

In einigen Domänen gibt es das Feld customFields. Das Domain-Schema führt es als String; der Feldinhalt kann JSON sein. Im API-Request ist deshalb der gesamte JSON-Inhalt als String zu übergeben – nicht als verschachteltes JSON-Objekt. Die Anführungszeichen des inneren JSON müssen im äußeren JSON-String escaped werden.

Aktualisieren

Über die Generic Domain API wird ein bestehender Datensatz mit POST und seiner id aktualisiert. Dabei wird customFields als Ganzes ersetzt; ein JSON-Merge einzelner Eigenschaften findet nicht automatisch statt.

bash

curl -s -X POST "$API_BASE/domains/salesHead" \
  --header "authorization: Basic $TOKEN" \
  --header "Content-Type: application/json" \
  -d '{
    "id": 12345,
    "customFields": "{\"externalOrderId\":\"EXT-1042\",\"metadata\":{\"channel\":\"shop\"}}"
  }'

Wenn nur eine Eigenschaft geändert werden soll, zuerst den aktuellen Wert lesen, den JSON-Text im aufrufenden System parsen und zusammenführen und anschließend den vollständigen neuen Wert speichern. Ob eine Domäne über die Generic API schreibbar ist, zeigt Swagger. Für Belege und andere Abläufe mit Geschäftslogik ist stattdessen die jeweilige Fach-API zu verwenden.

Lesen

Die Generic Domain API gibt customFields als String zurück. Diesen Wert im aufrufenden System als JSON parsen:

bash

curl -s -G "$API_BASE/domains/salesHead" \
  --header "authorization: Basic $TOKEN" \
  --data-urlencode "id=eq(12345)" \
  --data-urlencode "take=1"

Filtern

Die Generic Domain API bietet für String-Felder den Textfilter like(%Muster%). Damit lässt sich nach einer Zeichenfolge im gespeicherten JSON-Text suchen:

bash

curl -s -G "$API_BASE/domains/salesHead" \
  --header "authorization: Basic $TOKEN" \
  --data-urlencode 'customFields=like(%EXT-1042%)'

Das ist keine JSON-Abfrage: Es gibt keinen dokumentierten Filter auf JSON-Pfade oder einzelne JSON-Eigenschaften. Eine Textsuche kann je nach Formatierung, Leerzeichen oder ähnlichen Zeichenfolgen unvollständige oder zusätzliche Treffer liefern. Für verlässliche inhaltliche Filter die Datensätze über andere verfügbare Felder eingrenzen und customFields im aufrufenden System parsen und filtern.

5.9 Wie werden API-Versionen und Abwärtskompatibilität gehandhabt?

Die reybex API ist aktuell nicht versioniert (kein /v1/, /v2/ im Pfad). Änderungen sind rückwärtskompatibel:

Neue Felder können jederzeit hinzukommen → unbekannte Felder ignorieren
Bestehende Felder und Endpoints werden nicht entfernt oder umbenannt
Änderungen werden über Release Notes angekündigt

Best Practice

JSON-Parser so konfigurieren, dass unbekannte Felder ignoriert werden (ignoreUnknownProperties o. ä.). So bleibt die Integration stabil, wenn neue Felder hinzukommen.

6 Datenmodelle und Referenzen

6.1 Wie ist das reybex-Datenmodell aufgebaut?

reybex verwendet ein domänenbasiertes Modell. Jede fachliche Entität (Material, Customer, SalesHead, StockItem …) ist eine Domäne mit eigenen Feldern und Beziehungen.

6.2 Wo finde ich die Datenmodelle und Feldbeschreibungen?

Quelle	Was
Domain-Struktur	Alle Domänen mit Feldern und Beziehungen
`GET /api/domains/showDomains`	Programmatisch: alle Domänen, Felder, Typen
api.reybex.com	Request-/Response-Schemas der Fach-API
Modulübersicht	Links zu Business, Integration und Domain pro Modul

6.3 Wie sind Entitäten und Beziehungen strukturiert?

ToOne (Referenz auf eine Entität): "matGroup": { "id": 2001 }
ToMany (Liste von Unter-Entitäten): "items": [ { ... }, { ... } ]
Flat (Wertfeld): "salesPrice": 19.99

ToOne-Referenzen können per ID oder per Suchschlüssel aufgelöst werden (siehe Suchschlüssel).

6.4 Welche Bedeutung und Datentypen haben die einzelnen Felder?

Typ	JSON-Darstellung	Beispiel
String	`"text"`	`"name": "Tasche"`
Long / Integer	`123`	`"id": 100100`
BigDecimal	`19.99`	`"salesPrice": 19.99`
Boolean	`true` / `false`	`"isStocked": true`
Date	`"yyyy-mm-dd"`	`"orderDate": "2026-10-06"`
Timestamp	ISO 8601 mit Uhrzeit	`"createdDate": "2026-10-06T08:59:12.000Z"`
ToOne-Referenz	`{ "id": … }`	`"matGroup": { "id": 2001 }`
ToMany-Liste	`[ { … } ]`	`"items": [...]`

Feldbeschreibungen pro Domäne: Domain-Struktur oder GET /api/domains/showDomains.

6.5 Welche Felder sind Pflichtfelder, optional oder schreibgeschützt?

Kategorie	Beispiele	Hinweis
Pflicht (Anlage)	je Fachseite, z. B. Artikel: `name`, `vatKey`, `warehouseUnit`, `matGroup`, `matStatus`, `materialType`	Speichern bricht ohne diese Felder ab
Optional	`gtin`, `salesPrice`, `description`	Weglassen oder Standard der Fachseite
Schreibgeschützt	`id`, `tenantId`, `createdDate`, `lastModified`	Serverseitig gesetzt
Bedingt	Charge nur bei `isLotEnabled: true`	Kontextabhängig

Die konkreten Pflichtfelder stehen auf der Fachseite. matCode ist beim Artikel kein Pflichtfeld.

6.5.1 Auflösung, wenn ein Pflichtfeld fehlt

Jede Fachseite wiederholt diesen Block bei den Pflichtfeldern. Eine KI, die nur diese eine Seite bekommt, kann den Datensatz damit anlegen. Der erste Treffer gilt. Die API füllt Pflicht-Referenzen nicht von selbst.

Angabe – Wert aus dem Auftrag für dieses Feld.
Vorlage – dasselbe Feld aus dem gelesenen Vorlagen-Datensatz. id und die Nummernfelder der Seitentabelle nicht übernehmen. Ist eine Vorlage genannt, diese lesen. Ist keine genannt und die Liste enthält genau eine Vorlage, diese verwenden. Mehrere Vorlagen ohne Nennung: keine raten, mit Schritt 3 weiter.
Standard – fester Code oder Konfigurationsfeld aus der Seitentabelle. Code per Suchschlüssel laden. Existiert der Datensatz nicht, Schritt 4.
Domäne – hat die Domäne isDefault, zuerst isDefault=true. Sonst GET /api/domains/{domain}?take=1&sort=code. Den Treffer per Suchschlüssel in den Request setzen.
Stopp – die Domäne ist leer. Nicht anlegen und nicht raten. Den fehlenden Stammdatensatz nennen.

Skalare Standards der Fachseite (isStocked, Preise 0) nur senden, wenn die Seite sie als mitzusenden nennt. Sonst weglassen.

6.6 Welche Wertebereiche und Validierungsregeln gelten?

Eindeutigkeit: matCode und sku müssen pro Mandant eindeutig sein
Referenz-Existenz: Referenzierte Entitäten (z. B. matGroup, vatKey) müssen existieren
Wertebereich: Boolean-Felder nur true/false; Preise als positive Dezimalzahlen
Format: Datumsfelder im Format yyyy-mm-dd (ISO 8601)
Länge: Keine global definierten String-Limits; feldspezifisch (DB-Spalte)

Validierungsfehler resultieren in HTTP 500 mit BusinessException und einer Fehlermeldung im error-Feld.

6.7 Was ist eine interne ID, Referenz-ID oder externe ID?

Typ	Beschreibung	Beispiel
Interne ID (`id`)	Technischer Primärschlüssel (Long), serverseitig vergeben	`100100`
Referenz-ID	ID einer verknüpften Entität in einer ToOne-Beziehung	`"matGroup": { "id": 2001 }`
Externe ID	Partnerseitiger Schlüssel, z. B. `sku`, `marktplaceOrderId`	`"sku": "PARTNER-SKU-001"`

6.8 In welchem Gültigkeitsbereich ist eine ID eindeutig?

IDs sind mandantenweit eindeutig (Scope: tenantId). Dieselbe numerische ID kann in verschiedenen Mandanten unterschiedliche Datensätze referenzieren.

matCode und sku sind ebenfalls pro Mandant eindeutig.

6.9 Muss ich für Referenzen immer eine ID übergeben?

Nein. Bei ToOne-Referenzen im Request-Body können Sie statt der id einen Suchschlüssel verwenden. Das System löst die Referenz automatisch auf.

json

// Variante A – per ID (schneller, wenn bekannt)
{ "matGroup": { "id": 2001 } }

// Variante B – per Suchschlüssel (lesbarer, ohne ID-Kenntnis)
{ "matGroup": { "code": "HANDEL" } }

Bekannte id hat immer Vorrang vor Suchschlüsseln.

6.10 Welche alternativen Suchschlüssel gibt es?

Domain	Suchschlüssel (Priorität)
Material	`matCode`, dann `sku`
Customer (Kunde/Lieferant)	`customerNo`
Warehouse	`code`, dann `name`
StockPlace	`stockplaceCode`, dann `name` (jeweils mit `warehouse`)
Unit, VatKey, Currency, MatStatus, Paymcond …	`code`, dann `type`, dann `name`
MaterialType	`name`
Attribute	`name`

6.11 Wie finde ich eine Entität anhand alternativer Suchschlüssel?

Die Suchschlüssel-Logik funktioniert automatisch in ToOne-Referenzen im Request-Body. Sie müssen nichts Besonderes tun – einfach statt id den Suchschlüssel angeben:

json

{
  "material": { "matCode": "ART-001" },
  "warehouse": { "code": "HAUPT" },
  "vatKey": { "code": "19" }
}

Das System sucht in der Reihenfolge der definierten Suchschlüssel. Wird keine Entität gefunden:

json

{ "error": "No entity found for domain Material with key 'matCode' and value 'INVALID-CODE'" }

Einschränkung

Suchschlüssel funktionieren nur bei ToOne-Referenzen. In hasMany-Listen (z. B. items[]) wird keine bestehende Entität gesucht – dort wird immer ein neuer Datensatz angelegt. Verwenden Sie in Listen die id.

6.12 Welche fachlichen Abhängigkeiten bestehen zwischen Entitäten?

Typische Abhängigkeitsketten:

Entität	Voraussetzung
Material	MatGroup, MatStatus, MaterialType, VatKey, Unit
SalesHead (Auftrag)	Customer, SalesDocType, Currency, Paymcond
SalesItem	Material, Warehouse, VatKey
PurHead (Bestellung)	Customer (Lieferant), PurDocType, Currency
StockItem	Material, Warehouse, StockPlace
MaterialVariant	Material (Kopf mit `hasVariants: true`)
MaterialBom	Material (Kopf mit `isSet: true`), Komponente (Material), Unit

Empfohlene Reihenfolge: Prüftabellen → Stammdaten (Material, Kontakte) → Belege → Lager/Buchungen.

7 Endpoint-Referenz und API-Nutzung

7.1 Wo finde ich die vollständige Endpoint-Übersicht?

Quelle	Inhalt
api.reybex.com	Alle Fach-API-Endpoints mit Methoden, Pfaden und Schemas
Swagger UI	Generic Domain API – alle CRUD-Operationen
Partner-Docs – Integration	Kuratierte Partner-Endpoints mit Business-Kontext

7.2 Wie sind Endpoints nach Modulen und Fachbereichen organisiert?

Endpoints sind nach fachlichen Modulen gruppiert:

Modul	Beispiel-Endpoints
Basis / Stammdaten (BAS)	`/api/material/`, `/api/materialImport/`, `/api/customer/` – Artikelstamm, Kunden und Lieferanten, Prüftabellen
Business Process Management (BPM)	`/api/bpmDefinitionHead/`, `/api/bpmHead/` – Business Process Management
CRM (CRM)	`/api/crmAction/`, `/api/crmOpportunity/` – CRM
Dropshipping (DPS)	`/api/dropshippingCustomer/`, `/api/dropshippingVendor/` – Dropshipping
EDI (EDI)	`/api/commProtocoll/`, `/api/commMessage/` – EDI
Einkauf (PUR)	`/api/purHead/`, `/api/purPrice/` – Einkauf-Verwaltung
Entwicklung (DEV)	`/api/runnableServiceEvent/`, `/api/widget/` – Entwicklung
Finanzen (FIN)	`/api/account/`, `/api/finHead/`, `/api/invoiceTr/` – Finanzen
Kalender (CAL)	`/api/calendar/workDay`, `/api/calendar/holiday` – Kalender
Kasse (CAS)	`/api/cashRegister/`, `/api/fiskaly/` – Kassenverwaltung
Lager / Inventur (INV)	`/api/stock/`, `/api/stockHead/`, `/api/incomingGoods/` – Lager und Inventur
Online Marktplätze (OMP)	`/api/marketplace/`, `/api/wsClient/` – Online Marktplätze
Produktion (PRD)	`/api/bomHead/`, `/api/prodOrder/` – Produktion
Projektmanagement (PRM)	`/api/project/`, `/api/task/` – Projektmanagement
Qualität (QLT)	`/api/qualityPlan/`, `/api/qualityHead/` – Qualität
System (SYS)	`/api/user/`, `/api/company/`, `/api/emailWorkflow/` – System
Versand / Pick & Pack (SMP)	`/api/shippment/`, `/api/sendPacks/`, `/api/shippingClient/` – Versand / Pick & Pack
Vertrieb (SAL)	`/api/salesHead/`, `/api/returnHead/`, `/api/contract/` – Auftragsverwaltung
Webshop Connector (WCO)	`/api/mobileGenericTransfer/`, `/api/mobileStockTaking/` – Webshop Connector

Vollständige Modul-Liste: Modulübersicht.

7.3 Wie lese ich die Dokumentation eines Endpoints?

In api.reybex.com finden Sie pro Endpoint:

HTTP-Methode und Pfad (z. B. POST /api/material/)
Request-Body-Schema mit Feldern und Typen
Response-Schema und Beispiel-Responses
Query-Parameter (bei GET-Endpoints)
Try-it-out zum interaktiven Testen (nach Login)

In den Partner-Docs ergänzen wir Business-Kontext, Hinweise und Copy-Paste-Beispiele.

7.4 Welche Parameter und Felder müssen übergeben werden?

Das hängt vom Endpoint ab. Grundregel:

Anlage (POST ohne id): Alle Pflichtfelder (z. B. matCode, name, Referenzen)
Update (POST mit id): Nur die zu ändernden Felder plus id
Lesen (GET): Filter als Query-Parameter, mindestens take

Pflichtfelder pro Endpoint: api.reybex.com oder die jeweilige Partner-API-Seite.

7.5 Welche Response erhalte ich bei erfolgreicher Ausführung?

Endpoint-Typ	Erfolgs-Response
POST (Anlegen)	`{ "id": 123456789 }` oder vollständiges Objekt
POST (Aktualisieren)	`{ "id": 123456789 }` oder vollständiges Objekt
GET (Lesen)	Array `[ { ... } ]` oder Einzelobjekt `{ ... }`
DELETE	HTTP 200 (leer oder Bestätigung)

Connector-Endpoints geben ein response-Array zurück – leeres Array bedeutet keine Zeilenfehler.

7.6 Welche Fehler und Statuscodes können auftreten?

HTTP-Status	Bedeutung
200	Erfolg
400	Ungültiger Request (fehlende Felder, falsches Format)
401	Nicht authentifiziert
403	Keine Berechtigung
404	Endpoint oder Ressource nicht gefunden
500	Serverfehler oder BusinessException
503	Server vorübergehend nicht erreichbar (Wartung, Neustart)

Bei HTTP 503 enthält der Response-Header Duration die voraussichtliche Dauer der Nichterreichbarkeit in Sekunden. Der Client sollte den Request nach Ablauf dieser Zeit erneut versuchen.

Fehlerformat:

json

{ "error": "Beschreibung des Fehlers" }

Detaillierte Fehlerbehandlung: Fehlerbehandlung.

7.7 Wie kann ich Daten lesen, erstellen, ändern oder löschen?

Lesen:

bash

curl -s -G "$API_BASE/domains/material" \
  --header "authorization: Basic $TOKEN" \
  --data-urlencode "matCode=eq(ART-001)" \
  --data-urlencode "take=1"

Erstellen (POST ohne id):

bash

curl -s -X POST "$API_BASE/material/" \
  --header "authorization: Basic $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "matCode": "NEU-001", "name": "Neuer Artikel", ... }'

Aktualisieren (POST mit id):

bash

curl -s -X POST "$API_BASE/material/" \
  --header "authorization: Basic $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "id": 100100, "salesPrice": 14.9 }'

Löschen:

bash

curl -s -X DELETE "$API_BASE/domains/material?id=100100" \
  --header "authorization: Basic $TOKEN"

7.8 Gibt es Codebeispiele, cURL-Beispiele oder Postman-Sammlungen?

Fach-API-Beispiele: pro Modul in den Partner-Docs, z. B. api.reybex.com
Interaktiv testen: api.reybex.com (Try it out) und Swagger UI
Postman-Collection: Keine offizielle Sammlung. Die cURL-Beispiele lassen sich direkt in Postman importieren.

7.9 Welche Best Practices gelten für die Verwendung der Endpoints?

Fach-API bevorzugen – für produktive Integrationen immer spezialisierte Endpoints nutzen
Generic API für Prototypen – schnell testen, dann auf Fach-API umstellen
Suchschlüssel nutzen – lesbarer und unabhängig von mandantenspezifischen IDs
Responses prüfen – nie „Fire and Forget"; Fehler im response-Array bei Connectoren beachten
Minimal senden – nur benötigte Felder im Update, nicht das gesamte Objekt

8 Erste API-Anfrage und Integrationsbeispiele

8.1 Wie sende ich meinen ersten API-Request?

bash

# Variablen setzen
export API_BASE="https://io-staging-partner.reybex.com/api"
export TOKEN=$(echo -n "mein-api-user:mein-passwort" | base64)

# Erster Test: Domänen auflisten
curl -s "$API_BASE/domains/showDomains" \
  --header "authorization: Basic $TOKEN" | python3 -m json.tool | head -50

Wenn die Antwort eine JSON-Liste mit Domänen enthält, ist die Authentifizierung korrekt.

8.2 Wie teste ich einen Endpoint mit cURL oder Postman?

cURL:

bash

curl -s -G "$API_BASE/domains/material" \
  --header "authorization: Basic $TOKEN" \
  --data-urlencode "take=3" | python3 -m json.tool

Postman:

Neue Request-Kollektion anlegen
Headers-Tab → authorization: Basic <Token> eintragen
GET https://io-staging-partner.reybex.com/api/domains/material?take=3
Send → Response prüfen

Swagger UI:

Swagger UI öffnen
Authorize-Button → Basic Auth eintragen
Endpoint auswählen → Try it out → Execute

8.3 Wie lese ich einen vorhandenen Datensatz aus?

Per ID:

bash

curl -s "$API_BASE/material/100100" \
  --header "authorization: Basic $TOKEN"

Per Suchkriterium (Generic API):

bash

curl -s -G "$API_BASE/domains/material" \
  --header "authorization: Basic $TOKEN" \
  --data-urlencode "matCode=eq(ART-001)" \
  --data-urlencode "take=1"

Kein Treffer: [] (leeres Array).

8.4 Wie erstelle ich einen neuen Datensatz?

bash

curl -s -X POST "$API_BASE/material/" \
  --header "authorization: Basic $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "matCode": "TEST-001",
    "sku": "TEST-001",
    "name": "Testartikel",
    "salesPrice": 9.99,
    "priceUnit": 1,
    "isStocked": true,
    "matGroup": { "code": "HANDEL" },
    "matStatus": { "code": "AKTIV" },
    "materialType": { "name": "Handelsware" },
    "vatKey": { "code": "19" },
    "warehouseUnit": { "code": "ST" },
    "salUnit": { "code": "ST" },
    "purUnit": { "code": "ST" }
  }'

Erfolg: { "id": 123456789 }.

8.5 Wie aktualisiere ich einen bestehenden Datensatz?

POST mit id:

bash

curl -s -X POST "$API_BASE/material/" \
  --header "authorization: Basic $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 123456789,
    "salesPrice": 12.99,
    "name": "Testartikel (aktualisiert)"
  }'

Nur geänderte Felder mitsenden – nicht das gesamte Objekt.

8.6 Wie übergebe ich Referenzen und verknüpfte Entitäten?

ToOne-Referenzen als Objekt mit id oder Suchschlüssel:

json

{
  "matGroup": { "code": "HANDEL" },
  "vatKey": { "code": "19" },
  "warehouse": { "code": "HAUPT" }
}

ToMany (z. B. Belegpositionen) als Array – hier id verwenden:

json

{
  "items": [
    {
      "itemNumber": 1,
      "material": { "matCode": "ART-001" },
      "quantity": 2,
      "price": 24.99,
      "warehouse": { "code": "HAUPT" }
    }
  ]
}

8.7 Wie prüfe ich, ob eine Änderung erfolgreich gespeichert wurde?

Response prüfen: HTTP 200 mit { "id": … } = Erfolg
Nachlesen: GET /api/material/{id} oder Generic API mit Filter
Connector: response-Array prüfen – leeres Array = keine Fehler

bash

# Nach Anlage: Datensatz verifizieren
curl -s "$API_BASE/material/123456789" \
  --header "authorization: Basic $TOKEN" | python3 -m json.tool

8.8 Wie vermeide ich doppelte Datensätze und Aufträge?

Mechanismus	Beschreibung
`matCode` / `sku`	Material: eindeutig pro Mandant; bei Dopplung Fehler
`marktplaceOrderId`	Aufträge: Marktplatz-Bestellnummer als externe Referenz
`docNumber`	Belege: externe Belegnummer als Duplikat-Check
`id` bei POST	Mit `id` → Update statt Neuanlage
Connector	Matched auf `matCode`/`sku` → Update wenn vorhanden

Vor dem Anlegen prüfen:

bash

curl -s -G "$API_BASE/domains/material" \
  --header "authorization: Basic $TOKEN" \
  --data-urlencode "matCode=eq(TEST-001)" \
  --data-urlencode "take=1"

8.9 Wie setze ich einen vollständigen Integrationsprozess um?

Typische Kette Shop → reybex:

Prüftabellen sichern – Artikelgruppen, Einheiten, MwSt per Generic API lesen und IDs/Codes cachen
Artikel synchronisieren – POST /api/material/ pro Artikel oder Connector für Massenimport
Bestände setzen – POST /api/material/materialStocks
Aufträge importieren – POST /api/salesHead/ mit Positionen, siehe Auftragsverwaltung
Folgedokumente – Lieferschein, Rechnung über POST /api/salesHead/referencingDocuments
Status zurückliefern – Beleg-IDs und Tracking an Shop

Ausführliche Beispiele: Kunden und Lieferanten, CRM, Auftragsverwaltung, Kassenverwaltung, Einkauf-Verwaltung, Lager und Inventur, Artikelstamm-Verwaltung.

9 Limits, Performance und Best Practices

9.1 Welche API-Limits und Rate-Limits gelten?

Jede Quelle (API-User / Integration) ist auf maximal 30 Requests innerhalb von 10 Sekunden begrenzt. Dieses Limit gilt über alle Endpoints hinweg.

Verhalten bei Überschreitung:

Requests, die das Rate-Limit überschreiten, werden nicht abgelehnt. Stattdessen werden sie automatisch an zusätzliche interne Server weitergeleitet und über eine interne Pipeline (Queue) asynchron verarbeitet.

Auswirkung:

Situation	Verhalten
Innerhalb des Limits (≤ 30 / 10 s)	Sofortige Verarbeitung mit niedriger Latenz
Über dem Limit (> 30 / 10 s)	Verarbeitung mit Verzögerung, erhöhte Antwortzeiten

Die fachliche Korrektheit bleibt in jedem Fall gewährleistet. Eine Echtzeit-Verarbeitung ist bei Überschreitung jedoch nicht mehr garantiert.

Empfehlung

Requests moderat senden und innerhalb des Limits bleiben. Massenimports über Batch-Endpoints (z. B. POST /api/material/materialStocks mit materials[]) abwickeln, statt viele Einzel-POSTs parallel zu senden.

9.2 Gibt es Einschränkungen bei parallelen Requests?

Es gibt kein serverseitiges Limit für parallele Verbindungen. Für stabile Integrationen empfehlen wir:

Massenimport: Connector-Endpoints mit Arrays statt paralleler Einzel-POSTs
Reads: Moderate Parallelität (z. B. 5–10 parallele GETs)
Writes: Sequenziell oder mit geringer Parallelität, um Konflikte zu vermeiden

9.3 Welche Größen- und Mengenbeschränkungen gelten?

Es gibt keine festen Größenlimits für Request-Bodies. Praktische Empfehlungen:

Aspekt	Empfehlung
Connector-Array	Max. 500–1.000 Items pro Request
Pagination (`take`)	Default 100; bei Bedarf höher setzen
Bild-URLs im Connector	Bilder per URL statt Base64

9.4 Wie verarbeite ich große Datenmengen effizient?

Pagination nutzen – take und skip für seitenweises Lesen
Connector für Massenimport – ein Request mit Array statt n Einzel-Requests
Delta-Sync – nur geänderte Datensätze senden (z. B. per lastModified-Filter)
Parallelität anpassen – nicht zu viele, nicht zu wenige gleichzeitige Requests

bash

# Paginiertes Lesen
for OFFSET in 0 100 200 300; do
  curl -s -G "$API_BASE/domains/material" \
    --header "authorization: Basic $TOKEN" \
    --data-urlencode "take=100" \
    --data-urlencode "skip=$OFFSET"
done

9.5 Wie funktionieren Batch- und Bulk-Operationen?

Connector-Endpoints akzeptieren Arrays:

json

{
  "materials": {
    "item": [
      { "matCode": "ART-001", "name": "Artikel 1", "salesPrice": 9.99 },
      { "matCode": "ART-002", "name": "Artikel 2", "salesPrice": 14.99 },
      { "matCode": "ART-003", "name": "Artikel 3", "salesPrice": 19.99 }
    ]
  },
  "nameImportMode": 1,
  "priceImportMode": 1,
  "stockImportMode": 0
}

Bestände als Array: POST /api/material/materialStocks mit materials[].

Translations: POST /api/materialTranslation/batchUpdate mit batchUpdate[].

Die Generic Domain API bietet keine Batch-Operationen – dort Einzelaufrufe pro Datensatz.

9.6 Welche Timeouts muss ich berücksichtigen?

Es gibt keine serverseitigen Timeouts. Clientseitig empfehlen wir:

Typ	Empfehlung
Connect-Timeout	10 s
Read-Timeout	120 s (Connector-Imports können dauern)
Gesamtdauer	Abhängig von Payload-Größe; bei großen Imports ggf. 300 s

Bei clientseitigem Timeout: Nicht blind erneut senden – erst prüfen, ob der Request verarbeitet wurde (siehe Wiederanlauf).

9.7 Wie vermeide ich unnötige API-Aufrufe?

IDs cachen – Prüftabellen-IDs (Gruppen, Einheiten, MwSt) einmal lesen und lokal speichern
Suchschlüssel nutzen – statt erst die ID per GET zu ermitteln
Delta-Sync – nur geänderte Datensätze senden
Pagination – nicht alles auf einmal lesen; count vorab abfragen
Batch-Endpoints nutzen – ein Array-Request statt n Einzel-POSTs

9.8 Wie implementiere ich eine effiziente Datensynchronisierung?

Zeitstempel-basiert: lastModified-Filter in reybex, updated_at im Quellsystem
Idempotent: matCode/sku als natürlicher Schlüssel – bei Übereinstimmung wird aktualisiert statt doppelt angelegt
Fehler nicht blockieren: Einzelfehler loggen, Rest des Batches verarbeiten

9.9 Welche allgemeinen Best Practices werden empfohlen?

Staging zuerst – nie direkt gegen Produktion entwickeln
Fach-API > Generic API – für produktive Integrationen
Connector für Masse – nicht 10.000 Einzel-POSTs
Responses prüfen – jede Response auf Fehler untersuchen
Logging – alle Requests und Responses (mindestens Fehler) protokollieren
Unbekannte Felder ignorieren – JSON-Parser tolerant konfigurieren
Credentials sichern – Umgebungsvariablen, keine Hardcoding
Retry mit Backoff – bei Netzwerkfehlern exponentiell warten
Monitoring – laufende Sync-Prozesse überwachen
Dokumentation lesen – Release Notes verfolgen

10 Fehlerbehandlung und Wiederanlauf

10.1 Welche HTTP-Statuscodes und fachlichen Fehlercodes gibt es?

HTTP-Status	Kategorie	Typische Ursache
200	Erfolg	Request erfolgreich verarbeitet
400	Client-Fehler	Ungültiges JSON, fehlende Felder
401	Auth-Fehler	Ungültige oder fehlende Credentials
403	Berechtigung	Kein Zugriff auf Mandant oder Funktion
404	Nicht gefunden	Endpoint oder Ressource existiert nicht
500	Server-Fehler	BusinessException oder interner Fehler
503	Nicht erreichbar	Server vorübergehend nicht verfügbar (Wartung, Neustart)

Bei HTTP 503 enthält der Response-Header Duration die voraussichtliche Dauer der Nichterreichbarkeit in Sekunden. Der Client sollte diese Zeit abwarten und den Request danach erneut senden.

Fachliche Fehlercodes im engeren Sinne (z. B. numerische Codes) gibt es nicht. Fehler werden als Klartext im error-Feld zurückgegeben.

10.2 Wie ist eine Fehlermeldung aufgebaut?

json

{ "error": "Beschreibung des Fehlers" }

Beispiele:

json

{ "error": "No entity found for domain Material with key 'matCode' and value 'INVALID-CODE'" }

json

{ "error": "Multiple entities found for domain Warehouse with key 'code' and value 'WH1'" }

Connector-Endpoints liefern ein response-Array mit Zeilenfehlern:

json

{
  "response": [
    { "matCode": "ART-001", "sku": "ART-001", "message": "Duplicate matCode" }
  ]
}

Leeres response-Array = keine Fehler.

10.3 Wie unterscheide ich technische und fachliche Fehler?

Typ	HTTP-Status	Beispiel	Maßnahme
Technisch	401, 403, 404, Netzwerkfehler	Timeout, DNS-Fehler, Auth abgelaufen	Retry nach Behebung
Fachlich	400, 500 mit `error`	Doppelte `matCode`, fehlende Pflichtfelder	Request korrigieren

Technische Fehler können durch Retry gelöst werden. Fachliche Fehler erfordern eine Korrektur des Requests.

10.4 Was mache ich bei ungültigen Requests oder fehlenden Pflichtfeldern?

Fehlermeldung lesen – error-Feld enthält den Grund
Pflichtfelder prüfen – Schema in api.reybex.com nachschlagen
Referenzen prüfen – existieren die referenzierten Entitäten (MatGroup, VatKey, …)?
Format prüfen – Datum als yyyy-mm-dd, Zahlen als Dezimal
Request korrigieren und erneut senden

10.5 Was mache ich bei fehlenden Berechtigungen?

Bei HTTP 401 oder 403:

Zugangsdaten prüfen (Benutzername, Passwort, Token abgelaufen?)
Mandant-Zuordnung in SYS08 prüfen
Ggf. neuen Token anfordern
Bei anhaltendem 403: reybex-Support kontaktieren

10.6 Wie verhalte ich mich bei Timeouts oder Verbindungsabbrüchen?

Da reybex keine serverseitigen Timeouts hat, sind Timeouts in der Regel clientseitig oder netzwerkbedingt:

Nicht blind erneut senden – der Request kann serverseitig bereits verarbeitet sein
Prüfen: War der Request ein POST (Anlage)? Dann erst per GET prüfen, ob der Datensatz existiert
Retry mit Vorsicht: Idempotente Requests (GET, Connector mit matCode-Matching) können sicher wiederholt werden
Logging: Timeout-Ereignis protokollieren

10.7 Was mache ich, wenn der Server nicht erreichbar ist?

Netzwerk prüfen – DNS, Firewall, Proxy
Status prüfen – ggf. reybex-Statusseite oder Support kontaktieren
Retry mit Exponential Backoff: z. B. 5 s → 10 s → 30 s → 60 s → 120 s
Requests queuen – lokal puffern und nach Wiederverfügbarkeit absenden

10.8 Wann darf ich einen Request erneut senden?

Request-Typ	Sicher wiederholbar?	Hinweis
GET	Ja, immer	Lesen hat keine Seiteneffekte
POST Connector	Ja	Matched auf `matCode`/`sku` → kein Duplikat
POST Fach-API (Anlage)	Mit Vorsicht	Erst prüfen, ob Datensatz existiert
POST Fach-API (Update)	Ja	Update mit `id` ist idempotent
DELETE	Ja	Erneutes Löschen ergibt Fehler, kein Schaden

10.9 Wie verhindere ich doppelte Verarbeitung bei Wiederholungen?

Natürliche Schlüssel nutzen: matCode, sku, marktplaceOrderId, customerNo
Vor Anlage prüfen: GET mit Filter auf den natürlichen Schlüssel
Connector nutzen: Matched automatisch auf matCode/sku
id mitschicken: POST mit id = Update, kein Duplikat
Verarbeitungs-Log führen: Lokale Tabelle mit Zeitstempel der letzten erfolgreichen Verarbeitung pro Datensatz

10.10 Wie protokolliere und analysiere ich fehlgeschlagene Requests?

Empfohlenes Logging pro Request:

Feld	Beispiel
Zeitstempel	`2026-10-09T12:00:00Z`
HTTP-Methode + URL	`POST /api/material/`
Request-Body (Auszug)	`{ "matCode": "ART-001", ... }`
HTTP-Status	`500`
Response-Body	`{ "error": "Duplicate matCode" }`
Dauer	`1.2s`

Sensible Daten (Passwörter, Tokens) nicht ins Log schreiben.

10.11 Wie kann ich fehlgeschlagene Vorgänge erneut verarbeiten?

Fehler-Queue aufbauen – fehlgeschlagene Requests mit Zeitstempel und Fehlergrund speichern
Klassifizieren: Fachlicher Fehler (manuell korrigieren) vs. technischer Fehler (automatisch retryen)
Retry-Job: Technische Fehler periodisch erneut versuchen (z. B. alle 5 Minuten)
Max. Retries: Nach n Versuchen manuell eskalieren
Dashboard/Alert: Fehlgeschlagene Requests überwachen und bei Häufung alarmieren

11 Test und Abnahme

11.1 Wie teste ich meine Integration in der Staging-Umgebung?

API-Basis auf Staging setzen: https://io-staging-partner.reybex.com/api
Alle Szenarien durchspielen: Anlegen, Lesen, Aktualisieren, Löschen
Fehlerfälle testen: Ungültige Daten, fehlende Referenzen, doppelte Schlüssel
Daten in reybex-UI verifizieren: Im Staging-Mandanten prüfen, ob die Daten korrekt ankommen
Performance testen: Massenimports mit realistischen Datenmengen

11.2 Welche Testdaten und Testfälle stehen zur Verfügung?

reybex stellt in der Staging-Umgebung Standard-Prüftabellen bereit (Artikelgruppen, Einheiten, MwSt-Schlüssel). Artikelstamm und Belege legen Sie selbst an.

Empfohlene Testfälle:

Testfall	Was prüfen
Artikel anlegen	Pflichtfelder, Referenzen, Response
Artikel mit Varianten	Kopf + Varianten, Bestand pro Variante
Auftrag erstellen	Positionen, Kunde, Preise
Folgedokument	Lieferschein aus Auftrag
Fehlerfall: doppelte `matCode`	Fehlermeldung korrekt?
Fehlerfall: fehlende Referenz	`error`-Feld verständlich?
Massenimport (Connector)	100+ Artikel, Response-Array prüfen

11.3 Wie teste ich Fehlerfälle und Grenzfälle?

Fehlende Pflichtfelder: Request ohne matCode oder name senden → Fehler erwarten
Ungültige Referenz: Nicht existierende matGroup-ID → Fehler erwarten
Doppelte Schlüssel: Zweimal denselben matCode anlegen → Fehler erwarten
Leerer Body: {} senden → Fehler erwarten
Sehr große Payloads: Connector mit 1.000+ Items → Verarbeitungszeit und Response prüfen
Ungültige Auth: Falsches Passwort → 401 erwarten

11.4 Wie prüfe ich die Korrektheit und Vollständigkeit der Daten?

Nach dem Schreiben lesen: Datensatz per GET zurücklesen und mit gesendeten Daten vergleichen
In der UI prüfen: Staging-Mandant in der reybex-UI öffnen und Daten visuell kontrollieren
Referenzen prüfen: Stimmen verknüpfte Entitäten (Gruppe, Einheit, MwSt)?
Bestandskorrektheit: Nach materialStocks den Bestand per Stock-API verifizieren
Belegkette: Auftrag → Lieferschein → Rechnung in der UI nachvollziehen

11.5 Welche technischen und fachlichen Abnahmekriterien gelten?

Es gibt keine formalen Abnahmekriterien seitens reybex. Empfohlene Checkliste:

[ ] Alle relevanten Szenarien in Staging erfolgreich getestet
[ ] Fehlerbehandlung implementiert (Retry, Logging, Alerting)
[ ] Duplikatvermeidung sichergestellt
[ ] Performance bei realistischen Datenmengen akzeptabel
[ ] Credentials sicher verwaltet (keine Hardcoding)
[ ] Monitoring vorbereitet

11.6 Welche Voraussetzungen müssen vor dem Go-live erfüllt sein?

Staging-Tests abgeschlossen – alle Szenarien erfolgreich
Produktions-User erstellt – in SYS08 mit korrekter Mandant-Zuordnung
Endpoint auf Produktion umgestellt – core-backend.reybex.com/api
Monitoring aktiv – Fehler-Logging und Alerting eingerichtet
Rollback-Plan – wie wird bei Problemen zurückgerollt?

12 Produktivsetzung und Betrieb

12.1 Wie erhalte ich Produktionszugangsdaten?

Erstellen Sie den API-User direkt in der Produktion über die Transaktion SYS08 Benutzer:

In reybex einloggen (Produktionsumgebung)
SYS08 öffnen → neuen Benutzer anlegen
Benutzername und Passwort setzen
Mandant-Zuordnung prüfen

Alternativ: über Ihren reybex-Ansprechpartner.

12.2 Welche Konfigurationen müssen für Produktion angepasst werden?

Einstellung	Staging	Produktion
API-Basis	`io-staging-partner.reybex.com/api`	`core-backend.reybex.com/api`
Zugangsdaten	Staging-User	Produktions-User
Retry-Intervalle	Kurz (Entwicklung)	Produktionsgerecht (Backoff)

Endpoint-Pfade und JSON-Strukturen sind identisch – nur URL und Credentials ändern.

12.3 Wie führe ich einen initialen Datenabgleich durch?

Prüftabellen lesen – Gruppen, Einheiten, MwSt, Lager per Generic API
Stammdaten importieren – Artikel über Connector (POST /api/material/connector)
Bestände setzen – POST /api/material/materialStocks (ggf. resetStockData: true für Vollabgleich)
Kunden synchronisieren – per Generic API oder Fach-API
Offene Belege – ggf. bestehende Aufträge importieren
Verifizieren – Stichproben in der UI prüfen

12.4 Wie überwache ich die Integration im laufenden Betrieb?

Fehler-Rate: Anteil fehlgeschlagener Requests überwachen
Latenz: Antwortzeiten messen und bei Anstieg warnen
Queue-Länge: Fehler-Queue / Retry-Queue überwachen
Daten-Vollständigkeit: Regelmäßig Stichproben: Stimmen Bestände, Preise, Aufträge?
Alerts: Bei gehäuften 500ern oder Auth-Fehlern benachrichtigen

12.5 Welche Logs und Informationen sind für die Fehlersuche erforderlich?

Bei einer Supportanfrage (siehe Support) sind folgende Informationen hilfreich:

Zeitpunkt des fehlerhaften Requests (UTC)
HTTP-Methode und URL (vollständig)
Request-Body (ohne Credentials)
Response-Body (vollständig, inkl. error)
HTTP-Status-Code
Mandant (Firmenname oder Tenant-ID)

12.6 Wie erkenne ich Synchronisierungsprobleme?

Symptom	Mögliche Ursache	Maßnahme
Daten fehlen in reybex	Request fehlgeschlagen, nicht gesendet	Fehler-Log prüfen
Daten veraltet	Delta-Sync überspringt Datensätze	Sync-Zeitstempel prüfen
Doppelte Datensätze	Fehlende Duplikatprüfung	`matCode`/`sku`-Check implementieren
Bestand falsch	`resetStockData` falsch gesetzt	Sync-Logik prüfen
Belege unvollständig	Positionen fehlen, Referenzen ungültig	Request-Body prüfen

12.7 Wie gehe ich bei Ausfällen und Datenabweichungen vor?

Analyse: Fehler-Log auf Muster prüfen (alle Requests betroffen? Nur ein Endpoint?)
Abgrenzung: Netzwerk vs. Auth vs. fachlicher Fehler
Sofortmaßnahme: Sync pausieren, Queue puffern
Behebung: Ursache beseitigen (Credentials erneuern, Bug fixen, Daten korrigieren)
Nachsync: Fehlgeschlagene Requests aus der Queue erneut verarbeiten
Verifizierung: Stichproben in der UI

12.8 Wie stelle ich einen zuverlässigen Wiederanlauf sicher?

Idempotente Requests – Connector matched auf matCode/sku, Updates per id
Sync-Checkpoint – Zeitstempel der letzten erfolgreichen Verarbeitung persistent speichern
Queue-basiert – nicht verarbeitete Requests in Queue, Retry-Job verarbeitet sie
Monitoring – Queue-Länge und Fehler-Rate überwachen
Automatischer Neustart – Sync-Prozess nach Crash automatisch wieder aufnehmen

13 Wartung, Änderungen und Support

13.1 Wie werden API-Änderungen angekündigt?

API-Änderungen werden über Release Notes veröffentlicht. Es gibt keine separaten E-Mail-Benachrichtigungen für API-Änderungen.

13.2 Wie werden neue API-Versionen veröffentlicht?

Die reybex API ist nicht versioniert. Es gibt keine /v1/- oder /v2/-Pfade. Alle Änderungen sind rückwärtskompatibel:

Neue Felder und Endpoints können hinzukommen
Bestehende Felder und Endpoints bleiben erhalten
Verhalten bestehender Endpoints wird nicht verändert

13.3 Wie erkenne ich veraltete oder abgekündigte Endpoints?

Da die API rückwärtskompatibel ist, werden Endpoints nicht abgekündigt. Sollte dies in Ausnahmen nötig sein, wird es über Release Notes kommuniziert.

13.4 Wie werden Breaking Changes dokumentiert?

Breaking Changes werden vermieden. Die Strategie ist rückwärtskompatible Erweiterung. Sollte ein Breaking Change unvermeidbar sein, wird er über Release Notes angekündigt und eine Migrationsfrist eingeräumt.

13.5 Wie migriere ich auf eine neue API-Version?

Entfällt – die API ist nicht versioniert. Bei Erweiterungen (neue Felder, neue Endpoints): Unbekannte Felder in Responses ignorieren – damit ist die Integration automatisch kompatibel.

13.6 Welche Aufgaben übernimmt reybex?

Bereitstellung und Betrieb der API-Infrastruktur
Staging-Umgebung einrichten
API-Dokumentation pflegen
Release Notes bei Änderungen veröffentlichen
Technischen Support über Ticketsystem

13.7 Welche Aufgaben und Pflichten hat der Integrator?

Implementierung und Test der Integration
Fehlerbehandlung und Retry-Logik
Sichere Verwaltung der Zugangsdaten
Monitoring im laufenden Betrieb
Anpassung bei API-Erweiterungen (unbekannte Felder tolerieren)
Release Notes verfolgen
Support-Tickets mit vollständigen Informationen erstellen

13.8 Wie und wo erhalte ich technischen Support?

Technischer Support ist über das reybex-Ticketsystem erreichbar. Erstellen Sie ein Ticket mit den Informationen aus Fehlersuche-Logs.

13.9 Welche Informationen muss eine Supportanfrage enthalten?

Eine gute Supportanfrage enthält:

Mandant (Firmenname)
Zeitpunkt des Problems (Datum, Uhrzeit, Zeitzone)
Endpoint (HTTP-Methode + vollständige URL)
Request-Body (anonymisiert, ohne Credentials)
Response (vollständig, inkl. HTTP-Status und Body)
Erwartetes Verhalten vs. tatsächliches Verhalten
Reproduzierbarkeit (immer / sporadisch / einmalig)
Eigene Analyse (was wurde bereits geprüft?)

14 Referenzen und FAQ

14.1 Glossar wichtiger Begriffe

Begriff	Bedeutung
Mandant / Tenant	Logisch getrennte Firma in reybex; alle Daten sind mandantenbezogen
Domäne / Domain	Fachliches Datenobjekt (z. B. Material, Customer, SalesHead)
urlToken	camelCase-Name der Domäne in der Generic API (z. B. `material`, `stockList`)
Fach-API	Spezialisierte Endpoints mit Geschäftslogik
Generic Domain API	Generisches CRUD über `/api/domains/{domain}`
Connector	Massenimport-Endpoint für Konnektoren
Prüftabellen	Stammdaten-Tabellen (Einheiten, MwSt, Artikelgruppen, …)
Suchschlüssel / Search Key	Alternatives Feld zur ID-Auflösung (z. B. `matCode`, `code`)
ToOne	Referenz auf eine einzelne Entität
ToMany / hasMany	Liste von Unter-Entitäten
matCode	Interne Artikelnummer in reybex
sku	Externe/partnerseitige SKU
SalesHead	Verkaufsbelegkopf (Angebot, Auftrag, Lieferschein, Rechnung)
PurHead	Einkaufsbelegkopf (Bestellung, Wareneingang)
Soft-Delete	Logisches Löschen (`isDelete: true`), Datensatz bleibt erhalten

14.2 Übersicht der API-URLs und Umgebungen

Umgebung	URL
Staging	`https://io-staging-partner.reybex.com/api`
Produktion	`https://core-backend.reybex.com/api`
API-Referenz	api.reybex.com
Swagger UI	core-backend.reybex.com/swagger-ui

14.3 Übersicht der HTTP-Statuscodes und Fehlercodes

HTTP-Status	Bedeutung	Typische Ursache
200	Erfolg	Alles OK
400	Bad Request	Ungültiges JSON, fehlende Felder, falsches Format
401	Unauthorized	Ungültige Credentials
403	Forbidden	Kein Zugriff (Mandant, Rechte)
404	Not Found	Endpoint existiert nicht
500	Internal Server Error	BusinessException oder Serverfehler
503	Service Unavailable	Server vorübergehend nicht erreichbar; Header `Duration` enthält Wartezeit in Sekunden

14.4 Übersicht der Entitäten und Referenzfelder

Domain	urlToken	Suchschlüssel	Typische Referenzen
Material	`material`	`matCode`, `sku`	matGroup, matStatus, materialType, vatKey, Units
Customer	`customer`	`customerNo`	—
Warehouse	`warehouse`	`code`, `name`	—
StockPlace	`stockPlace`	`stockplaceCode`, `name`	warehouse
Unit	`unit`	`code`, `type`, `name`	—
VatKey	`vatKey`	`code`, `type`, `name`	—
Currency	`currency`	`code`, `type`, `name`	—
MatGroup	`matGroup`	`code`, `type`, `name`	—
MatStatus	`matStatus`	`code`, `type`, `name`	—
MaterialType	`materialType`	`name`	—
SalesHead	`salesHead`	—	customer, docType, currency, paymcond
SalesItem	`salesItem`	—	material, warehouse, vatKey
PurHead	`purHead`	—	vendor, docType, currency
MaterialVariant	`materialVariant`	—	material
MaterialBom	`materialBom`	—	material, component, unit

Vollständige Liste: GET /api/domains/showDomains oder Domain-Struktur.

14.5 Häufig gestellte Fragen

Kann ich denselben User für Staging und Produktion verwenden? Nein – Staging und Produktion haben getrennte User-Datenbanken. Sie benötigen separate Zugangsdaten.

Warum bekomme ich ein leeres Array [] zurück? Kein Treffer für die angegebenen Filter. Prüfen Sie: Stimmt der Mandant? Sind Daten vorhanden? Ist der Filterwert korrekt?

Warum schlägt mein POST mit HTTP 500 fehl? Meistens eine BusinessException: fehlende Pflichtfelder, ungültige Referenz-IDs, doppelter matCode. Die Fehlermeldung im error-Feld gibt Aufschluss.

Kann ich alle Artikel auf einmal lesen? Ja, per Pagination: take=1000&skip=0, dann skip=1000 usw. Vorher GET /api/domains/material/count für die Gesamtanzahl.

Wie finde ich heraus, welche Prüftabellen-Werte in meinem Mandanten existieren? Per Generic API: GET /api/domains/matGroup?take=100, GET /api/domains/unit?take=100 usw. Oder über die Check-Tables-Domain (GET /api/domains/checkTable).

Muss ich tenantId im Request mitsenden? Nein – tenantId wird aus der Session/Auth gesetzt. Nicht manuell mitschicken.

Was ist der Unterschied zwischen /api/material/connector und POST /api/material/? Der Connector ist für Massenimport durch Konnektoren (Array-Input, Import-Modi). POST /api/material/ ist die Fach-API für Einzelartikel mit voller Kontrolle über alle Felder und Schalter.

Wie bekomme ich Änderungen an reybex-Daten in mein System? Per Polling: Regelmäßig mit lastModified-Filter lesen. Webhooks/Events sind für bestimmte Domänen verfügbar – Details bei Ihrem reybex-Ansprechpartner.

14.6 Beispiel-Requests und Beispiel-Responses

Ausführliche, aufeinander aufbauende Shell-Beispiele (Artikel → Variante → Preis → Beleg):

→ api.reybex.com

Fach-API-Beispiele pro Artikeltyp (Einzelartikel, Varianten, Sets, Charge, PIM):

→ api.reybex.com

14.7 Versionshistorie und Änderungsprotokoll

Die reybex API hat keine expliziten Versionsnummern. Änderungen werden über die reybex Release Notes veröffentlicht.

14.8 Weiterführende Dokumentation und Support-Kontakte

Ressource	Link
Partner-Dokumentation – Integration	/integration/
API-Referenzportal	api.reybex.com
Swagger UI (Generic API)	core-backend.reybex.com/swagger-ui
Domain-Struktur	/domain/
Modulübersicht	/moduluebersicht
Authentifizierung	/integration/api#authentifizierung
Benutzer & Rollen	/business/sys/benutzer-rollen
Support	reybex-Ticketsystem

reybex API ​

1 Einstieg und erste Schritte ​

1.1 Was ist die reybex API? ​

1.2 Welche Integrationsmöglichkeiten bietet reybex? ​

1.3 Für wen ist die API-Dokumentation gedacht? ​

1.4 Welche Voraussetzungen muss ich als Integrator erfüllen? ​

1.5 Welche Schritte sind für den Start erforderlich? ​

1.6 Wo finde ich die technische Dokumentation und Beispiele? ​

1.7 Wie sieht der typische Ablauf eines Integrationsprojekts aus? ​

2 Umgebungen und Zugang ​

2.1 Welche Umgebungen stehen zur Verfügung? ​

2.2 Wie erhalte ich eine Staging- bzw. Testumgebung? ​

2.3 Wie wird eine neue Staging-Umgebung eingerichtet? ​

2.4 Wie beantrage ich API-Zugangsdaten? ​

2.5 Wie unterscheiden sich Test- und Produktionsumgebung? ​

2.6 Welche API-URLs und Basisadressen muss ich verwenden? ​

2.7 Wie werden Zugangsdaten sicher verwaltet? ​

3 Authentifizierung und Berechtigungen ​

3.1 Wie authentifiziere ich meine API-Anfragen? ​

3.2 Welche Zugangsdaten oder API-Keys benötige ich? ​

3.3 Welche Rollen und Berechtigungen sind erforderlich? ​

3.4 Welche Berechtigungen benötigt ein Endpoint? ​

3.5 Wie werden fehlende Berechtigungen erkannt und behoben? ​

3.6 Gibt es zusätzliche Zugriffsbeschränkungen? ​

4 API-Architektur und API-Typen ​

4.1 Welche API-Typen bietet reybex an? ​

4.2 Was ist die generische API? ​

4.3 Was ist die frontend-nahe API? ​

4.4 Worin unterscheiden sich die API-Typen? ​

4.5 Wann sollte ich welchen API-Typ verwenden? ​

4.6 Welche Funktionen und Daten sind über welche API verfügbar? ​

4.7 Welche Geschäftslogik und Validierungen werden ausgeführt? ​

4.8 Wie finde ich den passenden Endpoint für meinen Anwendungsfall? ​

5 Allgemeine API-Konventionen ​

5.1 Welche HTTP-Methoden werden unterstützt? ​

5.2 Welche Header und Content-Types sind erforderlich? ​

5.3 Welche Formate werden für Requests und Responses verwendet? ​

5.4 Wie werden Datum, Uhrzeit und Zeitzonen behandelt? ​

5.5 Wie werden Zahlen, Dezimalstellen und Währungen übertragen? ​

5.6 Wie werden fehlende Felder, null und Standardwerte interpretiert? ​

5.7 Wie funktionieren Filter, Sortierung und Pagination? ​

5.8 customFields: JSON-Inhalt aktualisieren, lesen und filtern ​

Aktualisieren ​

Lesen ​

Filtern ​

5.9 Wie werden API-Versionen und Abwärtskompatibilität gehandhabt? ​

6 Datenmodelle und Referenzen ​

6.1 Wie ist das reybex-Datenmodell aufgebaut? ​

6.2 Wo finde ich die Datenmodelle und Feldbeschreibungen? ​

6.3 Wie sind Entitäten und Beziehungen strukturiert? ​

6.4 Welche Bedeutung und Datentypen haben die einzelnen Felder? ​

6.5 Welche Felder sind Pflichtfelder, optional oder schreibgeschützt? ​

6.5.1 Auflösung, wenn ein Pflichtfeld fehlt ​

6.6 Welche Wertebereiche und Validierungsregeln gelten? ​

6.7 Was ist eine interne ID, Referenz-ID oder externe ID? ​

6.8 In welchem Gültigkeitsbereich ist eine ID eindeutig? ​

6.9 Muss ich für Referenzen immer eine ID übergeben? ​

6.10 Welche alternativen Suchschlüssel gibt es? ​

6.11 Wie finde ich eine Entität anhand alternativer Suchschlüssel? ​

6.12 Welche fachlichen Abhängigkeiten bestehen zwischen Entitäten? ​

7 Endpoint-Referenz und API-Nutzung ​

7.1 Wo finde ich die vollständige Endpoint-Übersicht? ​

7.2 Wie sind Endpoints nach Modulen und Fachbereichen organisiert? ​

7.3 Wie lese ich die Dokumentation eines Endpoints? ​

7.4 Welche Parameter und Felder müssen übergeben werden? ​

7.5 Welche Response erhalte ich bei erfolgreicher Ausführung? ​

7.6 Welche Fehler und Statuscodes können auftreten? ​

7.7 Wie kann ich Daten lesen, erstellen, ändern oder löschen? ​

7.8 Gibt es Codebeispiele, cURL-Beispiele oder Postman-Sammlungen? ​

7.9 Welche Best Practices gelten für die Verwendung der Endpoints? ​

8 Erste API-Anfrage und Integrationsbeispiele ​

8.1 Wie sende ich meinen ersten API-Request? ​

8.2 Wie teste ich einen Endpoint mit cURL oder Postman? ​

8.3 Wie lese ich einen vorhandenen Datensatz aus? ​

8.4 Wie erstelle ich einen neuen Datensatz? ​

8.5 Wie aktualisiere ich einen bestehenden Datensatz? ​

8.6 Wie übergebe ich Referenzen und verknüpfte Entitäten? ​

8.7 Wie prüfe ich, ob eine Änderung erfolgreich gespeichert wurde? ​

8.8 Wie vermeide ich doppelte Datensätze und Aufträge? ​

8.9 Wie setze ich einen vollständigen Integrationsprozess um? ​

reybex API

1 Einstieg und erste Schritte

1.1 Was ist die reybex API?

1.2 Welche Integrationsmöglichkeiten bietet reybex?

1.3 Für wen ist die API-Dokumentation gedacht?

1.4 Welche Voraussetzungen muss ich als Integrator erfüllen?

1.5 Welche Schritte sind für den Start erforderlich?

1.6 Wo finde ich die technische Dokumentation und Beispiele?

1.7 Wie sieht der typische Ablauf eines Integrationsprojekts aus?

2 Umgebungen und Zugang

2.1 Welche Umgebungen stehen zur Verfügung?

2.2 Wie erhalte ich eine Staging- bzw. Testumgebung?

2.3 Wie wird eine neue Staging-Umgebung eingerichtet?

2.4 Wie beantrage ich API-Zugangsdaten?

2.5 Wie unterscheiden sich Test- und Produktionsumgebung?

2.6 Welche API-URLs und Basisadressen muss ich verwenden?

2.7 Wie werden Zugangsdaten sicher verwaltet?

3 Authentifizierung und Berechtigungen

3.1 Wie authentifiziere ich meine API-Anfragen?

3.2 Welche Zugangsdaten oder API-Keys benötige ich?

3.3 Welche Rollen und Berechtigungen sind erforderlich?

3.4 Welche Berechtigungen benötigt ein Endpoint?

3.5 Wie werden fehlende Berechtigungen erkannt und behoben?

3.6 Gibt es zusätzliche Zugriffsbeschränkungen?

4 API-Architektur und API-Typen

4.1 Welche API-Typen bietet reybex an?

4.2 Was ist die generische API?

4.3 Was ist die frontend-nahe API?

4.4 Worin unterscheiden sich die API-Typen?

4.5 Wann sollte ich welchen API-Typ verwenden?

4.6 Welche Funktionen und Daten sind über welche API verfügbar?

4.7 Welche Geschäftslogik und Validierungen werden ausgeführt?

4.8 Wie finde ich den passenden Endpoint für meinen Anwendungsfall?

5 Allgemeine API-Konventionen

5.1 Welche HTTP-Methoden werden unterstützt?

5.2 Welche Header und Content-Types sind erforderlich?

5.3 Welche Formate werden für Requests und Responses verwendet?

5.4 Wie werden Datum, Uhrzeit und Zeitzonen behandelt?

5.5 Wie werden Zahlen, Dezimalstellen und Währungen übertragen?

5.6 Wie werden fehlende Felder, null und Standardwerte interpretiert?

5.7 Wie funktionieren Filter, Sortierung und Pagination?

5.8 `customFields`: JSON-Inhalt aktualisieren, lesen und filtern

Aktualisieren

Lesen

Filtern

5.9 Wie werden API-Versionen und Abwärtskompatibilität gehandhabt?

6 Datenmodelle und Referenzen

6.1 Wie ist das reybex-Datenmodell aufgebaut?

6.2 Wo finde ich die Datenmodelle und Feldbeschreibungen?

6.3 Wie sind Entitäten und Beziehungen strukturiert?

6.4 Welche Bedeutung und Datentypen haben die einzelnen Felder?

6.5 Welche Felder sind Pflichtfelder, optional oder schreibgeschützt?

6.5.1 Auflösung, wenn ein Pflichtfeld fehlt

6.6 Welche Wertebereiche und Validierungsregeln gelten?

6.7 Was ist eine interne ID, Referenz-ID oder externe ID?

6.8 In welchem Gültigkeitsbereich ist eine ID eindeutig?

6.9 Muss ich für Referenzen immer eine ID übergeben?

6.10 Welche alternativen Suchschlüssel gibt es?

6.11 Wie finde ich eine Entität anhand alternativer Suchschlüssel?

6.12 Welche fachlichen Abhängigkeiten bestehen zwischen Entitäten?

7 Endpoint-Referenz und API-Nutzung

7.1 Wo finde ich die vollständige Endpoint-Übersicht?

7.2 Wie sind Endpoints nach Modulen und Fachbereichen organisiert?

7.3 Wie lese ich die Dokumentation eines Endpoints?

7.4 Welche Parameter und Felder müssen übergeben werden?

7.5 Welche Response erhalte ich bei erfolgreicher Ausführung?

7.6 Welche Fehler und Statuscodes können auftreten?

7.7 Wie kann ich Daten lesen, erstellen, ändern oder löschen?

7.8 Gibt es Codebeispiele, cURL-Beispiele oder Postman-Sammlungen?

7.9 Welche Best Practices gelten für die Verwendung der Endpoints?

8 Erste API-Anfrage und Integrationsbeispiele

8.1 Wie sende ich meinen ersten API-Request?

8.2 Wie teste ich einen Endpoint mit cURL oder Postman?

8.3 Wie lese ich einen vorhandenen Datensatz aus?

8.4 Wie erstelle ich einen neuen Datensatz?

8.5 Wie aktualisiere ich einen bestehenden Datensatz?

8.6 Wie übergebe ich Referenzen und verknüpfte Entitäten?

8.7 Wie prüfe ich, ob eine Änderung erfolgreich gespeichert wurde?

8.8 Wie vermeide ich doppelte Datensätze und Aufträge?

8.9 Wie setze ich einen vollständigen Integrationsprozess um?