FOX4Work API Documentatie: Hoofd Eindpunt

📍 Eindpunt Details

Het /interface/Api.aspx eindpunt fungeert als het centrale ontvangstkanaal voor alle inkomende API-communicatie naar FOX4Work. Het beheert de verbinding, authenticatie, validatie van het contentformaat, en activeert interne bedrijfsprocessen (USEREXIT).

Element Detail
Basis URL [URL_van_uw_server]/interface/Api.aspx
Technologie ASP.NET Web Forms (VB.NET Code-behind)
Doel Ontvangst, authenticatie en verwerking van inkomende gegevens (IDocs, zakelijke berichten, enz.)

🛠 Aanvraag Levenscyclus (Workflow)

De verwerking van een aanvraag volgt een precieze levenscyclus:

  1. Pre-initialisatie (Page_PreInit): Legt de verbinding met de beheerengine vast (via Initialise).

  2. Laden (Page_Load):

    • Maakt de HTTP-antwoordstroom leeg (Response.Clear()).

    • Bepaalt het contentformaat (Content-Type).

    • Voert Authenticatie uit.

    • Roept de hoofdfunctie voor verwerking op (Message_to_send) bij succesvolle authenticatie.

  3. Verwerking (Message_to_send): Valideert de HTTP-methode en het formaat van de aanvraagbody, en voert vervolgens interne bedrijfsprocessen uit.

  4. Ontladen(Page_Unload): Sluit verbindingen (Connection.CONNECTEUR_ARRET()).

🔒 Authenticatiemechanismen

Het eindpunt ondersteunt vier (4) verschillende authenticatiemechanismen, die in de volgende volgorde worden gecontroleerd. Zodra een set inloggegevens wordt gevonden, probeert de code de gebruiker te authenticeren.

1. Aangepaste Toegangstoken (Header)

  • Type: Token voor specifiek gebruik (waarschijnlijk voor een applicatie of klantenservice).

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

  • Formaat: Een tekenreeks die de token vertegenwoordigt.

  • Header Voorbeeld: X-CS-Access-Token: uw-geheime-toegangstoken

2. Query String Parameters

  • Type: Eenvoudig doorgeven van inloggegevens in de URL. Afgeraden methode voor productie vanwege beveiligingsrisico’s (zichtbaarheid in logboeken en geschiedenis).

  • Locatie: URL, na de ?.

  • Formaat: user en password

  • URL Voorbeeld: /interface/Api.aspx?user=mijngebruiker&password=mijnwachtwoord

3. Basis Authenticatie (Header)

  • Type: HTTP Standaard. Inloggegevens (gebruikersnaam:wachtwoord) zijn Base64 gecodeerd.

  • Locatie: HTTP Header Authorization.

  • Formaat: Basic [Base64-gecodeerd(gebruikersnaam:wachtwoord)]

  • Header Voorbeeld: Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

4. Bearer Token (Header)

  • Type: Meestal gebruikt met OAuth 2.0.

  • Locatie: HTTP Header Authorization.

  • Formaat: Bearer [token]

  • Header Voorbeeld: Authorization: Bearer mijn-beveiligde-bearer-token

    ⚠️ Beveiligingsopmerking: Als geen van de bovenstaande methoden inloggegevens verstrekt (Autorisatie(0) is leeg), retourneert de server een 401 Unauthorized code met de boodschap BasicAuthRequired.

📥 Ondersteunde Content Formaten

Het eindpunt zal alleen doorgaan met de verwerking van de aanvraag als de Content-Type van de aanvraag overeenkomt met een van de geautoriseerde formaten.

Ondersteunde Formaten

MIME Type (Content-Type) Beschrijving
application/xml Standaard XML
application/json Standaard JSON
application/soap+xml SOAP Aanvraag
text/xml Alias voor XML
text/plain Ruwe Tekst Gegevens
text/csv CSV Gegevensformaat

Afhandeling van Niet-Geautoriseerde Content

  • Als de Content-Type niet overeenkomt met een van de bovenstaande formaten, retourneert de server een 400 Bad Request code met de boodschapUnauthorizedContext.

⚙️ Verwerking van Zakelijke Acties

Zodra de authenticatie en het contentformaat zijn gevalideerd, neemt de functie Message_to_send het over om interne acties te activeren.

1. Geautoriseerde HTTP Methoden

  • De code controleert of de aanvraagmethode (REQUEST_METHOD) is geautoriseerd.

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

2. Lezen en Valideren van de Aanvraagbody (Payload)

De body van de aanvraag wordt ingelezen in de variabele Message.

De functie Verifie_structure_post voert een eenvoudige structurele validatie uit op basis van de Content-Type:

Content-Type Validatievoorwaarde
Bevat xml De body moet < EN > bevatten.
Bevat json De body moet { EN } bevatten.
Overige (text/plain, enz.) Validatie is altijd True (Geen structurele controle).

⚠️ Waarschuwing: Als de validatie mislukt, retourneert de server een 405 Method Not Allowed code met de boodschap Method Not Allowed.

3. Activering van Interne Processen (USEREXIT)

Twee soorten acties kunnen worden geactiveerd via de Query Strings:

A. Hoofdproces (Interfaces)

  • Activatie: Wordt altijd uitgevoerd als de structuur geldig is.

  • Rol: Start de algemene interfaceverwerking (Device.LogEvent.Evenement_locfile.Interfaces).

B. Specifieke Sub-Actie (Jobcall)

  • Parameter: jobcall (geheel getal/opsomming).

  • Rol: Als de waarde van de jobcall verschilt van None (0), wordt een secundaire actie gestart.

C. Actiefilter (action)

  • Parameter: action (tekenreeks).

  • Rol: Deze parameter wordt doorgegeven aan de interne processen om te filteren welke sub-acties moeten worden uitgevoerd (maakt het mogelijk om slechts een subset van beschikbare API-aanroepen uit te voeren).

4. Logging

  • Een volledige trace van de ontvangen aanvraag wordt gelogd in de ERP_I tabel (waarschijnlijk een ERP fouten/gebeurtenissen log). Gegevens worden afgekapt tot 8000 tekens.

↩️ Antwoord Formaten en Foutcodes

Het antwoord wordt geformatteerd op basis van de oorspronkelijk verzonden Content-Type in de aanvraag, met behulp van de functie Message_retour.

Antwoord Structuur (Voorbeelden)

Content Type Antwoord Formaat
xml / soap+xml / text/xml <response><code>[Status]</code><message>[Tekst]</message></response>
json {“response”: {“code”: “[Status]”,”message”: “[Tekst]”}}
text/plain / text/csv (standaard text/xml bij fout) <ApiError><code>[Status]</code><message>[Tekst]</message></ApiError>

Gebruikelijke Foutcodes

HTTP Status Interne Boodschap Beschrijving Oorsprong
200 OK OK of Zakelijke Boodschap Succesvolle verwerking. Message_to_send
400 Bad Request UnauthorizedContext Niet-ondersteunde Content-Type. Page_Load
401 Unauthorized BasicAuthRequired Geen authenticatie-informatie verstrekt. Page_Load
401 Unauthorized InvalidCredentials Authenticatie mislukt (onjuiste gebruiker/wachtwoord). Page_Load
405 Method Not Allowed Method Not Allowed Structurele validatie van de aanvraagbody mislukt. Message_to_send
500 Internal Server Error Invalid data Onbehandelde fout (Exceptie) in het Try…Catch blok. Page_Load
Tags