FOX4Work API-Dokumentation: Hauptendpunkt

📍 Endpunkt (Endpoint)

Der Endpunkt /interface/Api.aspx ist der zentrale Empfangskanal für die gesamte eingehende API-Kommunikation mit FOX4Work. Er verwaltet die Verbindung, die Authentifizierung, die Validierung des Inhaltsformats und das Auslösen interner Geschäftsaktionen (USEREXIT).

Element Detail
Basis-URL [URL_Ihres_Servers]/interface/Api.aspx
Technologie ASP.NET Web Forms (Code-behind VB.NET)
Ziel Empfang, Authentifizierung und Verarbeitung eingehender Daten (IDocs, Geschäftsnachrichten usw.)

🛠 Lebenszyklus der Anfrage (Workflow)

Die Verarbeitung einer Anfrage folgt einem präzisen Lebenszyklus:

  1. Vorinitialisierung (Page_PreInit): Aufbau der Verbindung zur Management-Engine (über Initialise).

  2. Laden (Page_Load):

    • Löschen des HTTP-Antwortstroms (Response.Clear()).

    • Bestimmung des Inhaltsformats (Content-Type).

    • Authentifizierung.

    • Aufruf der Hauptverarbeitung (Message_to_send) bei erfolgreicher Authentifizierung.

  3. Verarbeitung (Message_to_send): Validierung der HTTP-Methode und des Formats des Anfragekörpers, anschließend Ausführung interner Geschäftsaktionen.

  4. Entladen (Page_Unload): Schließen der Verbindungen (Connection.CONNECTEUR_ARRET()).

🔒 Authentifizierungsmechanismen

Der Endpunkt unterstützt vier (4) verschiedene Authentifizierungsmechanismen, die in der folgenden Reihenfolge geprüft werden. Sobald Anmeldedaten gefunden werden, versucht der Code, den Benutzer zu authentifizieren.

1. Benutzerdefiniertes Zugriffs-Token (Header)

  • Typ: Token für spezifische Zwecke (wahrscheinlich für eine Anwendung oder einen Kundendienst).

  • Ort: HTTP-Header X-CS-Access-Token.

  • Format: Eine Zeichenfolge, die das Token darstellt.

  • Header-Beispiel: X-CS-Access-Token: ihr-geheimes-zugriffs-token

2. Abfrageparameter (Query String)

  • Typ: Einfache Übergabe von Anmeldedaten in der URL. Diese Methode wird für die Produktion aufgrund von Sicherheitsrisiken (Sichtbarkeit in Protokollen und Verläufen) nicht empfohlen.

  • Ort: URL, nach dem ?.

  • Format: user und password

  • URL-Beispiel: /interface/Api.aspx?user=meinbenutzer&password=meinpasswort

3. Basic Authentication (Header)

  • Typ: HTTP-Standard. Die Anmeldedaten (Benutzername:Passwort) sind Base64-kodiert.

  • Ort: HTTP-Header Authorization.

  • Format: Basic [Base64-kodiert(Benutzername:Passwort)]

  • Header-Beispiel: Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

4. Bearer Token (Header)

  • Typ: Typischerweise mit OAuth 2.0 verwendet.

  • Ort: HTTP-Header Authorization.

  • Format: Bearer [token]

  • Header-Beispiel: Authorization: Bearer mein-sicheres-bearer-token

⚠️ Sicherheitshinweis: Wenn keine der oben genannten Methoden Anmeldedaten liefert (Autorisation(0) ist leer), gibt der Server einen Code 401 Unauthorized mit der Meldung BasicAuthRequired zurück.

📥 Unterstützung von Inhaltsformaten

Der Endpunkt akzeptiert die Verarbeitung der Anfrage nur, wenn der Content-Type der Anfrage einem der zulässigen Formate entspricht.

Unterstützte Formate

MIME-Typ (Content-Type) Beschreibung
application/xml Standard-XML
application/json Standard-JSON
application/soap+xml SOAP-Anfrage
text/xml Alias für XML
text/plain Rohdaten (Text)
text/csv Daten im CSV-Format

Umgang mit nicht autorisierten Inhalten

Wenn der Content-Type keinem der oben genannten Formate entspricht, gibt der Server einen Code 400 Bad Request mit der Meldung UnauthorizedContext zurück.

⚙️ Verarbeitung der Geschäftsaktion

Sobald die Authentifizierung und das Inhaltsformat validiert sind, übernimmt die Funktion Message_to_send, um interne Aktionen zu starten.

1. Erlaubte HTTP-Methoden

Der Code prüft, ob die Anfragemethode (REQUEST_METHOD) zulässig ist.

  • Erlaubte Methoden: GET, POST, PUT, PATCH, DELETE.

2. Lesen und Validieren des Anfragekörpers (Payload)

Der Körper der Anfrage wird in der Variablen Message gelesen. Die Funktion Verifie_structure_post führt eine grundlegende strukturelle Validierung basierend auf dem Content-Type durch:

Content-Type Validierungsbedingung
Enthält xml Der Körper muss < UND > enthalten.
Enthält json Der Körper muss { UND } enthalten.
Andere (text/plain, usw.) Validierung immer True (keine strukturelle Prüfung).

⚠️ Achtung: Wenn die Validierung fehlschlägt, gibt der Server einen Code 405 Method Not Allowed mit der Meldung Method Not Allowed zurück.

3. Auslösen interner Verarbeitungen (USEREXIT)

Zwei Arten von Aktionen können über die Query Strings ausgelöst werden:

  • A. Hauptverarbeitung (Interfaces): Wird immer ausgeführt, wenn die Struktur gültig ist. Startet die allgemeine Schnittstellenverarbeitung (Device.LogEvent.Evenement_locfile.Interfaces).

  • B. Spezifische Unteraktion (Jobcall): Wenn der Wert von jobcall (Ganzzahl/Enumeration) ungleich None (0) ist, wird eine sekundäre Aktion gestartet.

  • C. Aktionsfilter (action): Dieser Parameter (Zeichenfolge) wird an die internen Verarbeitungen übermittelt, um die auszuführenden Unteraktionen zu filtern.

4. Protokollierung (Logging)

Eine vollständige Spur der empfangenen Anfrage wird in der Tabelle ERP_I (wahrscheinlich ein ERP-Fehler-/Ereignisprotokoll) gespeichert. Die Daten werden auf 8000 Zeichen gekürzt.

↩️ Antwortformate und Fehlercodes

Die Antwort wird basierend auf dem ursprünglich in der Anfrage gesendeten Content-Type mithilfe der Funktion Message_retour formatiert.

Antwortstruktur (Beispiele)

Inhaltstyp Antwortformat
xml / soap+xml / text/xml <response><code>[Status]</code><message>[Text]</message></response>
json {„response“: {„code“: „[Status]“, „message“: „[Text]“}}
text/plain / text/csv <ApiError><code>[Status]</code><message>[Text]</message></ApiError> (Standardmäßig text/xml bei Fehlern)

Häufige Fehlercodes

HTTP-Status Interne Meldung Beschreibung Ursprung
200 OK OK oder Geschäftsnachricht Erfolg der Verarbeitung. Message_to_send
400 Bad Request UnauthorizedContext Nicht unterstützter Content-Type. Page_Load
401 Unauthorized BasicAuthRequired Keine Authentifizierungsinformationen angegeben. Page_Load
401 Unauthorized InvalidCredentials Authentifizierung fehlgeschlagen (Benutzer/Passwort falsch). Page_Load
405 Method Not Allowed Method Not Allowed Strukturelle Validierung des Anfragekörpers fehlgeschlagen. Message_to_send
500 Internal Error Invalid data Interner Serverfehler. Page_Load
Tags