Image Added

profacto bietet einen token-gesicherten Zugriff auf ausgewählte Tabellen, Felder und Felder Funktionen mit sehr flexibler Architektur.  Bei Wünschen für zusätzliche Tabellen, API-Sets, bestimmte Funktionen oder als externer Entwickler sprich mit einem größeren Projekt, um größere Zusammenhänge und Prozesse mit profacto digital zu integrieren: sprich uns gerne an. 

...

Sobald man das Limit der Lizenzen erreicht, wird der Aufruf umgeleitet. Man erhält je nach Aufruf der eigentlichen Zielseite eine Webseite mit weiteren Infos

oder eine JSON-Response:

{"error":"licenses_exceeded","url":"http://mumpitz:8080/4DAction/api_license_redirect?response=HTML","errorMsg":"Lizenzen für API oder OTA erschöpft, weitere Infos unter http://mumpitz:8080/4DAction/api_license_redirect?response=HTML","clients":3,"otaAvailable":3,"apiAvailable":5,"AddOnAPICalls":2,"otainUse":0,"apiInUse":1,"otatokenslots":[],"apitokenslots":[{"timestamp":5649041,"iptoken":"192.168.2.1038E39C4BA44C643BBAA78DE0B80DBE3D4"}]}

OTA-Integration

Die Over the Air-Integration mit einem CAD ist gesondert dokumentiert: CAD ERP Integration

API - Wieso, weshalb, warum?

Access Protocol Interface - oder einfach formuliert, eine Softwareschnittstelle mit einem einheitlichen Zugriffsprotokoll für alle. 

Im Gegensatz zu einfachen Datenimporten aus zB per Excel vorbereiteten .csv-Dateien, einem manuellen Export in .csv-Datein oder dem Zugriff per ODBC bietet das profacto API einen umfassend lesenden Zugriff, der keinen profacto Client voraussetzt und keinen profacto-Client (Stand 23.09.2019) oder eine ähnliche Lizenz benötigt. Zudem erlaubt der API-Zugriff, daß die Datenintegrität  innerhalb  der Anwendung gesichert ist.

Dafür aber einen durch einen selbst erzeugten Token einen gesicherten Zugriff von außen auf bestimmte Bereiche von profacto erlaubt, die man für bestimmte Aufgaben nunmal benötigt.

Der ODBC-Zugriff erlaubt hier ein zuviel an Zugriffsrechten und hat keine Option Inhalte zu schreiben oder ändern.  Zudem ist er beschränkt auf profacto Server-Installationen auf Windows und braucht zusätzliche Treiber-Updates.

...

{
"error":"licenses_exceeded",
"url":"http://meinServer:8080/4DAction/api_license_redirect?response=HTML",
"errorMsg":"Lizenzen für API oder OTA erschöpft, weitere Infos unter http://meinserver:8080/4DAction/api_license_redirect?response=HTML",
"clients":3,
"otaAvailable":3,
"apiAvailable":5,
"AddOnAPICalls":2,
"otainUse":0,
"apiInUse":1,
"otatokenslots":[],
"apitokenslots":[
{
"timestamp":5649041,
"iptoken":"192.168.2.1038E39C4BA44C643BBAA78DE0B80DBE3D4"
}]
}

OTA-Integration

Die Over the Air-Integration mit einem CAD ist aufgrund der Entwicklungsbasis jenseits von profacto, als offenem Standard für ERP und CAD, gesondert dokumentiert: CAD ERP Integration

API - Wieso, weshalb, warum?

Access Protocol Interface - oder einfach formuliert, eine Softwareschnittstelle mit einem einheitlichen Zugriffsprotokoll für alle. 

Im Gegensatz zu einfachen Datenimporten aus zB per Excel vorbereiteten .csv-Dateien, einem manuellen Export in .csv-Datein oder dem Zugriff per ODBC bietet das profacto API einen umfassend lesenden Zugriff, der keinen profacto Client voraussetzt und keinen profacto-Client (Stand 23.09.2019) oder eine ähnliche Lizenz benötigt. Zudem erlaubt der API-Zugriff, daß die Datenintegrität  innerhalb  der Anwendung gesichert ist.

Dafür aber einen durch einen selbst erzeugten Token einen gesicherten Zugriff von außen auf bestimmte Bereiche von profacto erlaubt, die man für bestimmte Aufgaben nunmal benötigt.

Der ODBC-Zugriff erlaubt hier ein zuviel an Zugriffsrechten und hat keine Option Inhalte zu schreiben oder ändern. Zudem ist er beschränkt auf profacto Server-Installationen auf Windows und braucht zusätzliche Treiber-Updates, die wir auch mit profacto 2021 nicht mehr als Teil des Produkts ausliefern.

CSV-Dateien müssen manuell erzeugt werden und erfordern eine Übertragung von Dateien, somit einen Speicherort. profacto API erfolgt über HTTP-Aufrufe und liefert Daten im JSON-Format, welches sich insbesondere für Webseiten und Drittsoftware sehr einfach verarbeiten lässt.

Man kann die Daten mittels eines Standard-Browsers abrufen und sofort sehen. Man muß sich nicht allein im Firmennetzwerk bewegen.   Zugleich setzt die API ein tieferes technisches Verständnis von HTTP/REST-Zugriffen voraus und dient  in  dient in erster Linie der Kommunikation von Anwendung zu Anwendung. 

Dazu bieten wir aber auch die Option die API im Hintergund zu nutzen, um Webinhalte (zB Zeiterfassung, Lagerbestellung) bereitzustellen, also einen unmittelbaren Zugriff ermöglichen auf quasi jedem modernen mobilen Gerät mit einem Standardbrowser.

Architektur

Im Kern setzt das API auf einem aufgaben- oder rollenbasierten Spektrum an Zugriffen, wie zB die Zeiterfassung oder die CAD-Integration (die künftig als Sonder-API im Bereich der Integration beschrieben wird).

Folgende APIs sind bereits für alle kostenpflichtigen profacto-Versionen zugänglich:

• Integration
• Zeiterfassung
• Produktion
• Kontakte
• Kunden
• Aktivitäten
• Lieferanten
• Projekte
• Artikel
• Personal
• Lager
• Bestellung
• Dateien
• API Pinger (Testzugriff)Administration
• API Pinger (rein technischer Zugriff zu Testzwecken von Entwicklern)

Nur für die Standard-Version von profacto sind diese APIs verfügbar:

• Produktion sowie ProduktionSchreiben
• Kontakte sowie KontakteSchreiben
• Kunden sowie KundenSchreiben
• Aktivitäten sowie AktivitätenSchreiben
• Lieferanten sowie LieferantenSchreiben
• Projekte sowie ProjekteSchreiben
• Artikel sowie ArtikelSchreiben
• Personal sowie PersonalSchreiben
• Lager
• Bestellung sowie BestellungSchreiben
• Dateien
• Buchhaltung
• Kalkulation
• Konstanten

Diese APIs befinden sich weiterhin im Aufbau, der sich nach aktuellen Anforderungen richtet.

Dazu gehört, daß man bestimmten Mitarbeitern (ein Personal-Datensatz ist Voraussetzung) ein Token gibt, mit dem der Zugriff gewährt, aber eben auch zeitlich limitiert oder entzogen werden kann. 

Zugriff

In den Voreinstellungen, profacto Administration . Seit profacto 2024.1 differenzieren wir dort, wo eine entsprechende Funktion zur Verfügfung steht, zwischen Lesetoken und Schreibtoken. Dies erlaubt es, Mitarbeitern Leserechte auf bestimmte Tabellen zu gewähren, nicht aber das Recht, diese Daten auch zu modifizieren. Da die APIs inzwischen sehr leistungsfähig sind und durchaus auch außerhalb des lokalen Netzwerks eingesetzt werden können, erhöht diese Maßnahme die Zugriffssicherheit auf Ihre Daten.

Dazu gehört, daß man bestimmten Mitarbeitern (ein Personal-Datensatz ist Voraussetzung) ein Token gibt, mit dem der Zugriff gewährt, aber eben auch zeitlich limitiert oder entzogen werden kann. 

Zugriff

In den Voreinstellungen, profacto API und OTA werden die Tokens vergeben. 

Image Removed

Der Schlüssel öffnet die Token-Vergabe. 

Die WAN-Server-Adresse muß hinterlegt werden, um für die OTA-Integration eine spezielle Konfigurationsdatei zu erzeugen oder andere externe API-Zugriffe auf profacto zu ermöglichen.

Image RemovedImage Added

Das eindeutige Token wird einer Personalnummer wie ein Fingerabdruck zugeordnet und danach der gewünschten API. Für diverse APIs muß man auch verschiedene Tokens erstellen. Standard ist eine Laufzeit von 5 Jahren, die email dient dazu es auch direkt übermitteln zu können.

Mittels Token wird zugleich identifiziert, welche API von wem aufgerufen wird.

Das Token kopieren Sie im Zweifelsfall einfach  heraus.

Aufruf

API-Basis = http://<Servername im LAN oder WAN |LAN oder WAN-IP|>:8080/4DAction/<api-Methode>?token=<Token>

Weil das darunter liegende Framework von Profacto Case-Insensitive ist verhält sich das auch so mit den API-Methoden bzw. Aufrufen.

Folgende API-Methoden stehen zur Verfügung:

api_getapilist (Alle API) - Gibt eine Liste der verfügbaren APIs der profacto Installation zurück

api_getmytokens (Alle API mit persönlichem Token) - Gibt eine List der APIs mit Token der aufrufenden Person (gemäß Token) zurück

api_getzeitmodell  (API Zeiterfassung) - liefert daß Zeitmodell von dem Mitarbeiter der dem Zeiterfassung-Token zugeordnet ist

api_cadtextures - (API Integration) - empfängt Texturnamen vom CAD

api_get (API diverse) - Daten aus der Datenbank lesen.

api_get_doccopybyid (API Projekte) - Gibt eine Datei bestimmt durch die id aus der Tabelle DokumentSeiten

api_get_filebyid - Gibt eine Datei bestimmt durch die id aus der Tabelle Alias

api_get_personaltokens - Liefert für die übergebene Personalnummer und ggf. API das notwendige Token

api_get_project_doccopylist (API Projekte)

api_get_project_filelist - Liefert eine Liste aller Dateien, die einem Projekt zugeordnet sind

api_get_qr - erlaubt URLs mit "/" statt "?", um aus der Tabellenkalkulation Daten abzurufen

api_getkunden -  Holt alle Kundendatensätze ab (veraltet - besser api_get benutzen)

api_getposdelta - Ermittelt die für das übergebene Projekt seit dem als zweiten Parameter gegebenen Zeitstempel erfolgten Änderungen an Projektpositionen

api_getproduction - Gibt eine Projektübersicht im HTML-Format wieder

api_license_redirect - Zeigt den Status der verfügbaren API & OTA Lizenzen an

api_newstockdemand - verarbeitet eine Artikel-UUID in einen Bestellvorschlag

api_partcncqrcode - gibt den QR-Code für ein CNC-Programm aus

api_partdone - Fortschrittsmeldung in einer Stückliste

api_partitem - Liefert eine Stückliste aus (ElementID)

api_partstation - Setzt den Status einer Stückliste und gibt ihn wieder

api_ping - Gibt eine einfache Response zurück, ob eine API verfügbar ist

api_productionposition - Liefert alle zugehörigen Stücklisten zu einem Projekt

api_put_activity (API Aktivitäten) - Schreibt eine Aktivität.

api_put_bestellpos (API Bestellung) - Schreibt eine Bestellposition.

api_put_bestellung (API Bestellung) - Erstellt eine Bestellung

api_put_contact (API Kontakte) - Schreibt einen Kontakt zu einem vorhandenden Kunden oder Lieferanten.

api_put_customer (API Kunden) - Schreibt einen Kundendatensatz.

api_put_employee (API Personal) - Schreibt einen Personaldatensatz.

api_put_item (API Artikel) - Schreibt einen Artikeldatensatz.

api_put_project (Alle API) - Projekt anlegen.

api_put_projectpos - Schreiben einer Projektposition

api_put_supplier (API Lieferanten - Schreibt einen Lieferantendatensatz.

api_put_time (API Zeiterfassung)- Schreibt einen Zeitdatensatz.

api_qasignature - Speichert eine digitale Unterschrift oder liefert sie aus

api_sandbox - Gibt eine HTML-Seite wieder zur Verwendung des Proglove Handschuhs

api_stornostockdemand - Lagerbestellungen stornieren

api_time_getday - Liefert alle gebuchten Zeiten für gegebenen Tag für gegebenen Mitarbeiter aus

api_time_getpositions (API Zeiterfassung) - liefert zu gegebenem Projekt die Positionen

api_time_start (API Zeiterfassung) - Startet einen Zeiterfassungsvorgang im Browser - Kern der WebZE

http://<Servername im LAN oder WAN |LAN oder WAN-IP|>:8080/4DAction/api_get?token=<Token>

Der Port 8080 ist hart vorgegeben und darf nicht geändert werden.

Tabellen und Feld-Namen

Die Namen aller Tabellen und Felder in profacto können hier eingesehen werden

Link: Datenbankstruktur

Die APIs haben jeweils auch Felder, die nicht unterstützt werden, insbesondere BLOB- und Bild-Felder, aber auch unzulässige Felder. So braucht man für Zeiterfassung bestimmte Personal-Informationen, jedoch nicht das Gehalt oder andere private Informationen.

Für verschiedene Szenarien kann es daher sein, daß ein Aufruf abgelehnt wird, wenn man unzulässige Felder verwendet hat.

Daten  lesen mit api_get

API-Basis = http://<Servername im LAN oder WAN |LAN oder WAN-IP|>:8080/4DAction/api_get?token=<Token>

weitere Parameter:

table = je nach API eine darin zulässige Tabelle  - Beispiel API-Basis&table=Ansprechpartner

fields = eine kommagetrennte Liste von auszugebenden Feldern der Standardtabelle des APIs oder der per table-Parameters gewünschten Tabelle - Beispiel API-Basis&fields=KundenNr,Ort,PLZ,Name1

query = Ein query-String, der per URL-Encoding mit Prozentzeichen übergeben werden muss, also zB %20  für ein Leerzeichen, etc. siehe hier in Wikipedia: https://de.wikipedia.org/wiki/URL-Encoding#Relevante_ASCII-Zeichen_in_Prozentdarstellung - Beispiel 

API-Basis&query=KundenNr%3D131%20AND%20Ort%3DHildesheim

  (entspricht KundenNr=131 AND Ort=Hildesheim)

Vollständiges Beispiel: 

http://meinServer:8080/4DAction/api_get?token=124&table=Ansprechpartner&fields=Anrede,Geschlecht,Name,VorName,email,Telefon,MobilTel,isInaktiv,Suchfeld1&query=TypNr%3D131

Operatoren

Für eine Übersicht der query-Syntax bitte folgende Darstellung verwenden (Übersetzung folgt).

Symbole zum Vergleichen von Attribut und Value. Es gibt folgende Symbole:

...

LogicalOperator: verbindet mehrere Bedingungen in der Suche (optional). Es gibt folgende logische Operatoren (Sie können Name oder Symbol übergeben):

...

Die Tabellen- und Feldnamen für table und fields müssen nicht exakt der Groß-Kleinschreibung der Struktur folgen, für query ist dies jedoch zwingend.

Ausgabe der Daten

Die Daten werden als JSON-String zurückgegeben. 

Dazu gibt es stets initiale Objekte: Error, success, errorType und der aufgerufene Tabellenname.

Im Error steht  - möglichst menschenfreundlich in einem Satz formuliert - welche Fehler es gab. Gab es keine Fehler, enthält das Feld eine leere Kette.

In dem Objekt success steckt eine boolesche Variable mit true oder false, die bestimmt, ob der api_get Aufruf  erfolgreich war.

In dem Objekt errorType steht (falls es einen Fehler gab) ein oder mehrere Schlüsselwörter, die den Fehler beschreiben.

Danach kommen die eigentlichen Daten im Format Feldname:Feldinhalt.

Das sieht bei einem Aufruf mit einem nicht vorhandenen Quatschfeld wie folgt aus:

...

{"Error":["Das Feld Quatschfeld ist nicht vorhanden."],"Kunden":[{"KundenNr":"100001"},{"KundenNr":"100019"},{"KundenNr":"100003"},{"KundenNr":"131"},{"KundenNr":"130"},{"KundenNr":"129"},{"KundenNr":"128"},{"KundenNr":"127"},{"KundenNr":"125"},{"KundenNr":"124"},{"KundenNr":"123"},{"KundenNr":"100018"},{"KundenNr":"100015"},{"KundenNr":"1000012"},{"KundenNr":"126"},{"KundenNr":"100013"},{"KundenNr":"100009"},{"KundenNr":"100008"},{"KundenNr":"100012"},{"KundenNr":"100006"},{"KundenNr":"100005"},{"KundenNr":"100003"},{"KundenNr":"100004"},{"KundenNr":"100002"}]}

Man sieht, daß trotzdem alle zulässigen Felder unterstützt werden, die Abfrage deswegen nicht komplett scheitert.

Beispiel api_get mit Bestellungen

Um sich alle Bestellungen abzuholen benötigt man einen Token für Bestellungen, die Tabelle Bestellungen und die auszugebenden Felder.

http://meinserver:8080/4DAction/api_get?token=C900BFE22DFF4B75917837006E247932&table=Bestellung&fields=BestellNr,Kurzbez,Bestelldatum,Bemerkung

Als Resultat erhält man alle Bestellungen die mit dem Token zugänglich sind:

"{"Error":[],"Bestellung":[{"BestellNr":130001,"Kurzbez":"WHG-Ahmerkamp GmbH - Warendorf","Bestelldatum":"0000-00-00","Bemerkung":""},{"BestellNr":130002,"Kurzbez":"Holzma - Calw-Holzbronn","Bestelldatum":"2015-07-08","Bemerkung":"\\rNeues Bauabnahmedatum: 07.07.15"}],"error":"finished"}"

Standard-Felder für die Tabelle "Bestellung" (Werden keine Felder angegeben, werden die Folgenden automatisch als Abruf-Felder bestimmt)

BestellNr, Bestelldatum, AuftragsNr

Verbotene Felder für das Abrufen der Tabelle "Bestellung"

PKUUID_104

Beispiel api_get mit Bestellpositionen

Das vorher gegangene Beispiel mit den Bestellungen nutzen wir um die Bestellpositionen für eine Bestellung abzurufen.

Dafür müssen wir den Parameter query dem API-Aufruf mitgeben. An dieser Stelle möchten wir alle Bestellpositionen für die Bestellung mit der BestellNr. 130076 abrufen.

Wir ändern die Tabelle auf BestellPos und suchen uns die entsprechenden Felder die wir in unserer Response ausgegeben bekommen möchten (e.g. BestellNr, ArtikelNr,Bestellmenge).

http://meinserver:8080/4DAction/api_get?token=C900BFE22DFF4B75917837006E247932&query=BestellNr=130076&table=BestellPos&fields=BestellNr,ArtikelNr,BestellMenge

Wir erhalten die dazugehörigen Positionen in einem JSON-Objekt:

{"Error":[],"BestellPos":[{"BestellNr":130076,"ArtikelNr":"KF-AH-19","BestellMenge":32},{"BestellNr":130076,"ArtikelNr":"KF-AH-19","BestellMenge":2}],"error":"finished"}

Standard-Felder für die Tabelle "BestellPos" (Werden keine Felder angegeben, werden die Folgenden automatisch als Abruf-Felder bestimmt)

BestellNr, ArtikelNr, LfdNr

Entwickler-Paket

Für Entwickler stellen wir gerne eine profacto Lizenz und Entwicklungsumgebung bereit.

macOS: profacto Installer
Windows: profacto Installer

Die zugehörige Lizenz und Zugang zum API-Netzwerk mit Kunden und anderen Entwicklern stellen wir dir gerne auf Anfrage bereit: am besten gleich das hier verlinkte FairUseAgreement profactoDeveloper vorausgefüllt mitsenden bereit. 

Image Added Auf GitHub stellen wir einerseits HTML-Templates und auch Scripts zum Zugriff auf die API bereit.

Wenn du dort eigene Scripte der Öffentlichkeit zur Verfügung stellen möchtest, ist das herzlich willkommen und wir unterstützen den Austausch dazu sehr gerne. Die Scripts und Templates werden unter der MIT-Lizenz verfügbar gemacht.

Aufruf

API-Basis = http://<Servername im LAN | IP im LAN | WAN-Domain bzw. IP|>:8080/4DAction/<api-Methode>?token=<Token>

An die API-Basis werden dann mit &Attribut=Wert weitere Parameter übergeben.

Tabellen und Feld-Namen

Die Namen aller Tabellen und Felder in profacto können hier eingesehen werden

Link: Datenbankstruktur

Die APIs haben jeweils auch Felder, die nicht unterstützt werden, insbesondere BLOB- und Bild-Felder, aber auch unzulässige Felder. So braucht man für Zeiterfassung bestimmte Personal-Informationen, jedoch nicht das Gehalt oder andere private Informationen.

Für verschiedene Szenarien kann es daher sein, daß ein Aufruf abgelehnt wird, wenn man unzulässige Felder verwendet hat.

Daten  lesen mit api_get

Mögliche Parameter:

table = je nach API eine darin zulässige Tabelle  - Beispiel API-Basis&table=Ansprechpartner

fields = eine kommagetrennte Liste von auszugebenden Feldern der Standardtabelle des APIs oder der per table-Parameters gewünschten Tabelle - Beispiel API-Basis&fields=KundenNr,Ort,PLZ,Name1

query = Ein query-String, der per URL-Encoding mit Prozentzeichen übergeben werden muss, also zB %20  für ein Leerzeichen, etc. siehe hier in Wikipedia: https://de.wikipedia.org/wiki/URL-Encoding#Relevante_ASCII-Zeichen_in_Prozentdarstellung - Beispiel 

API-Basis&query=KundenNr%3D131%20AND%20Ort%3DHildesheim

  (entspricht KundenNr=131 AND Ort=Hildesheim)

Vollständiges Beispiel: 

http://meinServer:8080/4DAction/api_get?token=124&table=Ansprechpartner&fields=Anrede,Geschlecht,Name,VorName,email,Telefon,MobilTel,isInaktiv,Suchfeld1&query=TypNr%3D131

Operatoren

Für eine Übersicht der query-Syntax bitte folgende Darstellung verwenden (Übersetzung folgt).

• Symbole zum Vergleichen von Attribut und Value. Es gibt folgende Symbole:

  Vergleich	Symbol(e)	Kommentar
  Ist gleich	=, ==	Erhält passende Daten, unterstützt den Joker @, berücksichtigt weder Groß- und Kleinschreibung noch diakritische Zeichen.
  	===, IS	Erhält passende Daten, bewertet @ als Standardzeichen und nicht als Joker, berücksichtigt weder Groß- und Kleinschreibung noch diakritische Zeichen.
  Ungleich zu	#, !=	unterstützt den Joker (@)
  	!==, IS NOT	bewertet @ als Standardzeichen und nicht als Joker
  Kleiner als	<
  Größer als	>
  Kleiner als oder gleich	<=
  Größer als oder gleich	>=
  Enthalten in	IN	Erhält Daten, die mit mindestens einem Wert in einer Collection bzw. einem Satz Werte übereinstimmt
  Nicht enthalten in einer Anweisung	NOT	Klammern sind zwingend, wenn NOT vor einer Anweisung mit mehreren Operatoren verwendet wird
  Enthält Schlüsselwort	%	Schlüsselwörter lassen sich in Attributen vom Typ String oder Bild verwenden

  
  

• Value: Wert zum Vergleichen mit dem aktuellen Wert der Eigenschaft. 
  Für eine Suche nach einem String innerhalb eines anderen String (eine Suche "Enthalten in") verwenden Sie den Joker (@) in value, um den zu suchenden String zu isolieren, zum Beispiel: "@Schmi@", um alle Schmid, Schmied, Schmitt und so weiter zu finden.
• Für numerische Werte dient Punkt als Dezimaltrenner.
• Datumsangeben müssen im Format "YYYY-MM-DD" sein.
  Bei einer Suche mit einem IN Vergleichsoperator muss value eine Collection sein bzw. Werte, die zum Typ des Attributspfads zwischen eckigen Klammern [] passen, getrennt durch Kommas (bei Strings müssen Anführungszeichen " mit "\" abschließen).

• LogicalOperator: verbindet mehrere Bedingungen in der Suche (optional). Es gibt folgende logische Operatoren (Sie können Name oder Symbol übergeben):

  Konjunktion	Symbol(e)
  AND	&, &&, and
  OR	|, ||, or

  
  

• order by Attribut: Sie können eine Anweisung order by Attribute in der Suche hinzufügen, so dass die Ergebniswerte sortiert werden. Sie können mehrere Sortieranweisungen, durch Komma getrennt, verwenden, (z.B. order by Attribut1 desc, Attribut2 asc). Die Sortierung ist standardmäßig aufsteigend. Übergeben Sie 'desc' für absteigende Reihenfolge und 'asc' für aufsteigende Reihenfolge 

Die Tabellen- und Feldnamen für table und fields müssen nicht exakt der Groß-Kleinschreibung der Struktur folgen, für query ist dies jedoch zwingend.

Ausgabe der Daten

Die Daten werden als JSON-String zurückgegeben. 

Dazu gibt es stets initiale Objekte: Error, success, errorType und der aufgerufene Tabellenname.

Im Error steht  - möglichst menschenfreundlich in einem Satz formuliert - welche Fehler es gab. Gab es keine Fehler, enthält das Feld eine leere Kette.

In dem Objekt success steckt eine boolesche Variable mit true oder false, die bestimmt, ob der api_get Aufruf  erfolgreich war.

In dem Objekt errorType steht (falls es einen Fehler gab) ein oder mehrere Schlüsselwörter, die den Fehler beschreiben.

Danach kommen die eigentlichen Daten im Format Feldname:Feldinhalt.

Das sieht bei einem Aufruf mit einem nicht vorhandenen Quatschfeld wie folgt aus:

http://meinserver:8080/4DAction/api_get?token=5E05A427CD134432A28F2DAF11EC500E&table=Kunden&fields=KundenNr,Quatschfeld

JSON-Response:

{"Error":["Das Feld Quatschfeld ist nicht vorhanden."],"Kunden":[{"KundenNr":"100001"},{"KundenNr":"100019"},{"KundenNr":"100003"},{"KundenNr":"131"},{"KundenNr":"130"},{"KundenNr":"129"},{"KundenNr":"128"},{"KundenNr":"127"},{"KundenNr":"125"},{"KundenNr":"124"},{"KundenNr":"123"},{"KundenNr":"100018"},{"KundenNr":"100015"},{"KundenNr":"1000012"},{"KundenNr":"126"},{"KundenNr":"100013"},{"KundenNr":"100009"},{"KundenNr":"100008"},{"KundenNr":"100012"},{"KundenNr":"100006"},{"KundenNr":"100005"},{"KundenNr":"100003"},{"KundenNr":"100004"},{"KundenNr":"100002"}]}

Man sieht, daß trotzdem alle zulässigen Felder unterstützt werden, die Abfrage deswegen nicht komplett scheitert.

BestellNr, ArtikelNr, LfdNr

Pagination

Mittels der Pagination kann man sich die Daten in einzelnen Blöcken darstellen lassen.

Dafür werden die Parameter zum api_get-Befehl übergeben:

offset definiert ab welchem Datensatz weitergelesen werden soll

limit wiederum begrenzt die Anzahl der Datensätze die ausgegeben werden sollen

Da jeder neue Abschnitt auch die Daten neu liest kann es zu Verschiebungen kommen, wenn im Verlauf einer Abfrage Daten in einer bestimmten Ordnung hinzugefügt oder gelöscht werden.

In der Rückmeldung wird immer angeben, wieviele records vorhanden sind: 

{"total_in_query":25,"offset":0} - wenn es weder limit noch offset gab

{"total_in_query":25,"offset":25,"total_in_page":0} - wenn limit und offset angegeben waren.

Werte, die nicht erfüllt werden können, werden dabei ohne Fehlermeldung auf das mögliche reduziert, was ggf. auch in einer leeren Rückgabe münden kann.

Fehlermeldungen

"error":"" - immer am Anfang der JSON-Response

"errorMsg":"" - immer am Ende der JSON-Response

"structure_access_info":[] - vor den Nutzdaten

Neue Daten schreiben mit api_put_*

...

response - Werte: HTML oder JSON. Regelt, ob die Rückmeldung als HTML-Seite oder als JSON-Objekt erfolgen soll. Lassen Sie dieses Flag weg, wird JSON rückgeliefertoder als JSON-Objekt erfolgen soll. Lassen Sie dieses Flag weg, wird JSON rückgeliefert.

Exklusiv für api_put_bestellpos und api_put_projectpos:

append - Werte: True oder False. Bestimmt ob die gegenwärtige Positionsnummer hochgezählt werden soll, ist das der Fall gibt man bei Positionsnummer (api_put_projectpos) bzw. LfdNr (api_put_bestellpos) 0 an.

Ausgeschlossene Parameter:

...

Wir haben für das Testen der API-Methoden ein kleines Template-Paket auf GitHub bereitgestellt, ebenso stehen die Templates auch als Zip-Datei zur Verfügung. Die konkreten Beispiele sind auf den jeweiligen API-Seite mit Screenshot und Direktverlinkung verfügbar.

Verhalten bei gesperrten Datensätzen

...