profacto bietet einen token-gesicherten Zugriff auf ausgewählte Tabellen und Felder mit sehr flexibler Architektur. Bei Wünschen für zusätzliche Tabellen, API-Sets oder als externer Entwickler sprich uns gerne an.
| Inhalt |
|---|
Lizenz
...
profacto bietet einen token-gesicherten Zugriff auf ausgewählte Tabellen und Felder mit sehr flexibler Architektur. Bei Wünschen für zusätzliche Tabellen, API-Sets oder als externer Entwickler sprich uns gerne an.
| Inhalt |
|---|
Lizenz
- Ein API-Access beinhaltet einen parallelen Zugriff je API-Token + IP-Adress-Kombination für ein Zeitfenster von 15 Minuten ab dem erstem Aufruf.
- Jeder neue Aufruf innerhalb dieses Zeitfenster verlängert die Nutzungsphase dieses API-Accesses um weitere 15 Minuten.
- Je profacto Lizenz (exkl. TZE-Clients) ist ein freier Zugriff bereits integriert. In profacto SmallBusiness ist die API für die Zeiterfassung und Integration (s.u.) reduziert - Sonderfall ist die Craftboxx-Anbindung.
- Zusätzlich erhält jede profacto Lizenz (inkl. Small Business, StartUp) einen parallelen OTA-Integration Zugriff, der wie ein zweckbestimmter API-Zugriff ebenso berechnet wird.
- Weitere API-Accesses (auch für die OTA-Integration) können ab profacto 2021 für profacto (exkl. StartUp) separat erworben werden. Bis dahin wird kein erweitertes Entgelt erhoben, selbst wenn man mehr Zugänge nutzen möchte.
...
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
...
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: "@Smith@".
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 Namen aller Tabellen und Felder in profacto können hier eingesehen werden. Für die verschiedenen put-Befehle wird auf jeweils eine Tabelle schreibend zugriffen. Bestimmte Felder dürfen nicht geschrieben werden, dies ist unten in der Dokumentation jeweils aufgeführt.
Link: Datenbankstruktur
Verhalten bei gesperrten Datensätzen
...
Beispiel Templates (api_put_*)
Wir haben für das Testen der API-Methoden ein kleines Template-Paket auf GitHub bereitgestellt.
Zum schnellen Ausprobieren der Methode api_put_customer in der Kunden-API und der Methode api_put_project in der Projekt-API haben wir auf unserem ftp-Server Templates zugänglich gemacht.
Verhalten bei gesperrten Datensätzen
Versuchen Sie mit einem api_put_* Aufruf Daten zu verändern die gerade in Profacto geöffnet sind schlägt der Aufruf fehl.
...
{"success":false,"error":"Datensatz der Tabelle Kunden mit Schlüssel KundenNr:100019 ist gesperrt und kann nicht geschrieben werden.","processingTime":7575,"errorMsg":"Datensatz der Tabelle Kunden mit Schlüssel KundenNr:100019 ist gesperrt und kann nicht geschrieben werden."}API-Methodenauflistung mit Beispielen
api_getapilist - Auflistung aller API's
Erforderliche Parameter:
Token
Konkretes Beispiel:
http://meinServer:8080/4DAction/api_getapilist?token=5E05A427CD134432A28F2DAF11EC500EIn der JSON-Rückmeldung wird eine Liste aller verfügbaren Schnittstellen im Feld 'APIList' zurückgegeben:
{"error":"","success":true,"APIList":["Integration","Zeiterfassung","APIPinger","Produktion","Kunden","Kontakte","Lieferanten","Artikel","Lager","Bestellung","Personal","Aktivitäten","Projekte","Dateien","extragroup"]}api_put_contact - Ansprechpartner anlegen
Erforderliche Parameter:
VorName, Name, TypNr, Typ
Ausgeschlossene Parameter:
PKUUID_90
Optionale Parameter:
Telefon, Telefax, response, update
Konkretes Beispiel:
http://meinserver:8080/4DAction/api_put_contact?token=5223EE4D186449B0BDBE9ED7EC53F747&VorName=Heinz&Name=Ruehmann&TypNr=_0573&Typ=1&Telefon=089&Telefax=0891Zu Beachten ist, daß die TypNr je nach Ansprechpartner der KundenNr, LieferantenNr oder PersonalNr entsprechen sollte.
In der JSON-Rückmeldung haben Sie beispielhaft folgenden Inhalt:
{"success":true,"error":"","processingTime":6996,"errorMsg":""}api_put_customer - Kundenanlage
Erforderliche Parameter:
Name1, PLZ
Ausgeschlossene Parameter:
PKUUID_12
Konkretes Beispiel:
http://meinServer:8080/4DAction/api_put_customer?token=5E05A427CD134432A28F2DAF11EC500E&Name1=Schreinerei%20Meier&PLZ=48149&Strasse=Hauptstr.%201&response=trueIn der JSON-Rückmeldung wird auch die neue vergebene Kundennummer rückgeliefert:
{"success":true,"wasUpdate":false,"mainKey":"n20-01170","processingTime":54,"errorMsg":""}api_put_project - Projekt anlegen
Erforderliche Parameter:
Bauvorhaben, Bezeichnung
Ausgeschlossene Parameter:
PKUUID_20
Optionale Parameter:
response - (true|false) bestimmt ob der API-Aufruf eine Response zurückgibt
textupdatemode - bestimmt wie Textbausteine für den gegebenen Kunden aktualisiert werden können
default: Standardtexte aus Voreinstellungen, customer: Texte wie im Kunden hinterlegt, none: Texte lassen
paymentupdatemode - bestimmt ob die Zahlungskonditionen des Projekts oder des Kunden maßgeblich sind
default: Zahlungsbedingungen mit den aus dem Kunden hinterlegten Werten überschreiben, none: Werte aus dem Projekt stehen lassen
update - (true|false) - bestimmt ob ein bestehender Datensatz aktualisiert wird, hierbei ist der zusätzliche Parameter AuftragsNr (ProjektNr e.g. PK-0003) zwingend erforderlich
Konkretes Beispiel:
http://meinServer:8080/4DAction/api_put_project?token=41356A67726F4D219330ED924AE68E63&AuftragsNr=S019&update=true&Bauvorhaben=Altbau&Bezeichnung=kleines%20Nebenprojekt&textupdatemode=0&paymentupdatemode=1&response=trueIn der JSON-Rückmeldung wird auch die neue vergebene AuftragsNr zurückgeliefert:
{"success":true,"error":"","wasUpdate":false,"AuftragsNr":"S014","processingTime":7819,"errorMsg":""}api_put_item - Artikel anlegen
Erforderliche Parameter:
ArtikelTypenNr, Artikelgruppe
Ausgeschlossene Parameter:
PKUUID_21
Konkretes Beispiel:
http://meinServer:8080/4DAction/api_put_item?token=5E05A427CD134432A28F2DAF11EC500E&ArtikelTypenNr=FuzzyWuzzyOrigin&ArtikelGruppe=ZukaufteileIn der JSON-Rückmeldung wird auch die neue vergebene Kundennummer rückgeliefert:
{"success":true,"wasUpdate":false,"ArtikelTypNr":"FuzzyWuzzyOrigin","processingTime":54,"errorMsg":""}api_put_time - erfasste Arbeitszeit in das System Einbuchen
Erforderliche Parameter:
project, position, costsource, fromtime, totime
oder
project, position, costsource, fromtime, totaltime
Optionale Parameter:
date, pause, comment, feedback, response
Ausgeschlossene Parameter:
UUID, PersonalNr, BDEID
Konkretes Beispiel:
http://meinserver:8080/4DAction/api_put_time?response=JSON&token=41356A67726F4D219330ED924AE68E63&project=.GK&position=1&costsource=100&fromtime=06:00:00&totime=12:00:00&date=27.08.20&pause=00:00:00&comment=&feedback=falseZu den Parametern:
- project → entspricht der ProjektNr (String)
- position → entspricht der Projekt-Position (Integer)
- costsource → entspricht der Kostenstelle (Integer)
- fromtime → entspricht der Startzeit des zu buchenden Eintrags im Format 'hh:mm:ss'
- totime → entspricht der Endzeit des zu buchenden Eintrags im Format 'hh:mm:ss'
(Nur verwenden wenn man den Parameter totaltime nicht nutzt) - totaltime → entspricht der Gesamtzeit des zu buchenden Eintrags im Format 'hh:mm:ss'
(Nur verwenden wenn man den Parameter totime nicht nutzt) - date → entspricht dem Datum des zu buchenden Eintrags im Format 'dd.mm.yy'
(Wir dieser Parameter weggelassen, verwendet Profacto das gegenwärtige Datum) - pause → entspricht der Gesamtzeit für die zu buchende Pause im Format 'hh:mm:ss'
(Wird keine Pause angegeben, nimmt Profacto die vom Zeitmodell vorgeschlagenen Pausen) - comment → entspricht der Bemerkung als Zeichenkette (String)
- feedback → entspricht Anforderung von Rückfragen als boolischer Wert (Boolean als String)
- response → mögliche Werte sind 'HTML' und 'JSON'. Wird kein Wert angegeben erfolgt die Response in HTML
In der JSON-Rückmeldung wird auch die neue vergebene UUID zurückgeliefert:
{"success":true,"error":"","processingTime":1326,"errorMsg":"","recNum":885,"UUID":"3665FF277C1C4589AD07C075EA159314"}api_put_bestellung - Bestellung anlegen
Erforderliche Parameter:
Bezeichnung, Bauvorhaben
Ausgeschlossene Parameter:
PKUUID_104
Optionale Parameter:
BestellNr (nur bei update), Lieferant, Adr1, Adr2, Adr3, Adr4, Datum, Lieferdatum, Status, SkontoSatz, Frachtkosten, Kurzbez, vollstandig, Bestelldatum, Besteller, Bemerkung, LieferDatVorgab, AuftragsNr, VorText, NachText, RechnungsNr, LiefZugesagt, BestPreis, LieferPreis, LieferArt, AnfVorText, AnfNachText, LieferWoche, WahrungISO, LieferscheinNr, SkontoTage, FalligkeitTage, Rabatt, ABDatum, ABNr, AnsprechpartnerRecNum, Adr5, Adr6, StornoVorText, StornoNachText, StornoDatum, AufwandsKonto, StatusDatum, SuchFeld1, SuchFeld2, SuchFeld3, SuchFeld4, BestnrAlpha, UpdateDate, UpdateUser, isRahmenBestellung, isAbrufBestellung, RahmenBestellnr, isVorgabe, Berechnet, VollBerechnet, UStG13b, UStKlasse, LieferungProjektLieferadresse, SCVorlieferant, SCNachLieferant, VorgabeDatumFesthalten, IsGU, isBetriebsauftrag, MandantenKennung, AnfrageDatum, AngebotDatum, AngebotDatumWunsch, BestPreisRabattiert, LiefPreisRabattiert, Abschlag1Betrag, Abschlag2Betrag, Abschlag3Betrag, Abschlag4Betrag, Abschlag1Satz, Abschlag2Satz, Abschlag3Satz, Abschlag4Satz, EinbehaltAZ, EinbehaltSR, EinbehaltAllgemein, EinbehaltSRFaelligTage, EinbehaltAllgemeinText, GUBearbeitungStart, GUBearbeitungEnde, RabattAbsolut, IsRabattAbsolut, current_xUser, Absagedatum, Absagegrund, Bauabnahmedatum, isReklamation, GUBankbuergschaft, usePOBox, ViewProObject, ProjektBauvorhaben, ProjektKommission, response, update
Konkretes Beispiel:
http://meinserver:8080/4DAction/api_put_bestellung?token=C900BFE22DFF4B75917837006E247932&response=true&Bauvorhaben=Klettergerüst&Bezeichnung=KinderspielplatzIn der JSON-Rückmeldung haben Sie beispielhaft folgenden Inhalt:
{"success":true,"error":"","wasUpdate":false,"BestellNr":130128,"processingTime":29210,"errorMsg":""}api_put_bestellpos - Bestellposition anlegen
Erforderliche Parameter:
BestellNr, LfdNr, BestellMenge
Ausgeschlossene Parameter:
PKUUID_105
Optionale Parameter:
ArtikelNr, LieferArtikelNr, LieferMenge, Einheit, Preis, Beschreibung, geliefert, LieferPreis, Rabatt, LieferRabatt, AuftragsNr, PositionsNr, LiefZugesagt, orgMenge, Lange, Breite, Dicke, Gebindegrosse, inKalkEinheit, KalkMenge, KalkEinheit, GewichtLiefME, WahrungISO, Suchfeld1, Suchfeld2, Suchfeld3, Suchfeld4, RecNum, ExtraBeschreibung, KontoAufwand, Lieferdatum, Skizze1, Skizze2, LieferterminVorgabe, Freigegeben, FreigegebenDurch, FreigegebenAm, Loeschbar, Bemerkung, DurchLieferzeit, UpdateDate, UpdateUser, Rahmenbestellnr, RechMenge, LieferantenNr, isHeadline, isBetriebsauftrag, beImperial, BestNichtZusammenfassen, Alternativ, Eventual, Lagerort, RegalNr, RegalEbene, RegalSpalte, LieferantDefault, Lieferadresstyp, LieferadressePAName, CreationDate, CreationUser, ArtikelGruppe, RecNumOriginal, response, update
Konkretes Beispiel:
http://meinserver:8080/4DAction/api_put_bestellpos?token=C900BFE22DFF4B75917837006E247932&response=true&BestellNr=130076&LfdNr=5&BestellMenge=2&ArtikelNr=10089&LieferArtikelNr=10023&BestellMenge=3&LieferMenge=4&Einheit=m&Preis=20&Beschreibung=TestPositionDer Parameter LfdNr entspricht der Bestell-Position, das ist in der Regel eine fortlaufende Nummer die mit der 1 beginnt.
In der JSON-Rückmeldung haben Sie beispielhaft folgenden Inhalt:
{"success":true,"error":"","wasUpdate":false,"BestellNr":130076,"LfdNr":5,"processingTime":28821,"errorMsg":""}api_put_projectpos - Projektposition anlegen
Erforderliche Parameter:
AuftragsNr, PositionsNr, Anzahl
Optionale Parameter:
response, update ArtikelNr, Bezeichnung, Breite, Höhe, Tiefe, Einzelpreis, Rabatt, Gesamtpreis, Alt, DokumentNr, Status, Hopsasa, Suchfeld2, Suchfeld3, Suchfeld4
Konkretes Beispiel:
http://meinserver:8080/4DAction/api_put_projectpos?token=41356A67726F4D219330ED924AE68E63&response=true&AuftragsNr=08/15&PositionsNr=5&Anzahl=5In der Response steht dann im Erfolgsfall die AuftragsNr und die PositionsNr wie übergeben:
{"success":true,"error":"","wasUpdate":false,"AuftragsNr":"08/15","PositionsNr":5,"processingTime":28575,"errorMsg":""}api_time_getpositions - Projektpositionen abrufen
Erforderliche Parameter:
Token, projectid
Konkretes Beispiel:
http://meinServer:8080/4DAction/api_time_getpositions?token=5E05A427CD134432A28F2DAF11EC500E&projectid=bb0664617357c9cd7d7ddb9d56d014feIn der Rückmeldung enthaltenem JSON-Object wird der Tabellenname angeführt ("positions") in dem ein Array alle zu dem Projekt verfügbaren Positionen enthält im Format { "positonsnr": integer, "Bezeichnung": string}:
{"positions":[{"positionsnr":"1","bezeichnung":"Infomaterial Display X\r\rHochglanz weiß gemäß Entwurfskizze von Mies van der Rohe\r6 Flyerfäche\r4 Zeitschriften"},{"positionsnr":"2","bezeichnung":"Theke \r\rSockel mit indirekter LED-Beleuchtung\r3 PC-Arbeitsplätze\r2 Kassenzonen\rAudioguide-Wechselstation"}]}api_time_getday - Gebuchte Zeit-Einträge für einen Tag abrufen
Erforderliche Parameter:
Token
Optionale Parameter:
Date - Ist der Parameter Date nicht gesetzt, werden die Datensätze für den gegenwärtigen Tag ausgeliefert.
Konkretes Beispiel:
http://meinServer:8080/4DAction/api_time_getday?token=5E05A427CD134432A28F2DAF11EC500E&date=01.10.20In der Rückmeldung enthaltenem JSON-Object wird der Tabellenname angeführt ("Zeiten") in dem ein Array alle zu dem Tag gebuchten Zeiterfassungs-Einträge enthält im Format:
{"AuftragsNr": Alphanum, "VonZeit": Integer[Sekunden], "BisZeit":Integer[Sekunden], "PositionsNr": Integer, "KSTNR": Integer, "GesamtZeit": Integer[Stunden], "Bemerkung": String,"Nachweis": Boolean, "FeedbackRequired": Boolean, "BisZeitIstPausenAnfang": Boolean, "VonZeitIstPausenEnde": Boolean, "Zeitart": String, "Pause": Float[Stunden]}
Response:
{"success":true,"error":"","zeiten":[{"AuftragsNr":"100019","VonZeit":21600,"BisZeit":43200,"PositionsNr":3,"KSTNR":200,"GesamtZeit":6,"Bemerkung":"","Nachweis":false,"FeedbackRequired":true,"BisZeitIstPausenAnfang":false,"VonZeitIstPausenEnde":false,"Zeitart":"B","Pause":0.5},{"AuftragsNr":"100019","VonZeit":43200,"BisZeit":64800,"PositionsNr":3,"KSTNR":400,"GesamtZeit":6,"Bemerkung":"","Nachweis":false,"FeedbackRequired":true,"BisZeitIstPausenAnfang":false,"VonZeitIstPausenEnde":false,"Zeitart":"B","Pause":0.5}],"processingTime":6,"errorMsg":"","procTime2":0}api_getZeitModell - Zeitmodell für einen Mitarbeiter für einen Tag abrufen
Erforderliche Parameter:
Token
Optionale Parameter:
Datum - Ist der Parameter Datum nicht gesetzt, wird das Zeitmodell für den gegenwärtigen Tag ausgeliefert.
Konkretes Beispiel:
http://meinServer:8080/4DAction/api_getZeitModell?token=41356A67726F4D219330ED924AE68E63&Datum=14.10.20In der Rückmeldung enthaltenem JSON-Object wird der Wert "zeitmodell" aufgeführt und enthält in einem separaten Objekt die Kerndaten zu gegebenem Zeitmodell.
Response:
{"error":"","success":true,"zeitmodell":{"PersonalNr":"10","Name":"Krtek Maulwurf","Datum":"2020-10-13T22:00:00.000Z","PersUrlaubVerplantHHMM":0,"pers_ILEintritt":"12.08.04","pers_ILAustritt":"-","pers_ILUrlaubAnspruch":"160 h = 2.0 Tage","pers_ILUrlaubRest":"100 h = 1.2 Tage","pers_ILZeitmodell":"","pers_ILZeitmodellVon":"Von: jeher","pers_ILZeitmodellBis":"Bis: auf Weiteres","pers_ILMontag":"6:00 - 18:00","pers_ILMontagP1":"9:00 - 9:30","pers_ILMontagP2":"12:30 - 13:00","pers_ILDienstag":"6:00 - 18:00","pers_ILDienstagP1":"9:00 - 9:30","pers_ILDienstagP2":"12:30 - 13:00","pers_ILMittwoch":"6:00 - 18:00","pers_ILMittwochP1":"9:00 - 9:30","pers_ILMittwochP2":"12:30 - 13:00","pers_ILDonnerstag":"6:00 - 18:00","pers_ILDonnerstagP1":"9:00 - 9:30","pers_ILDonnerstagP2":"12:30 - 13:00","pers_ILFreitag":"6:00 - 16:00","pers_ILFreitagP1":"9:00 - 9:30","pers_ILFreitagP2":"12:30 - 13:00","pers_ILZeitmodellStdWoche":"40 Std./Wo","pers_ILZeitmodellStdWocheHHMM":144000,"zArbVon":21600,"zArbBis":64800,"zArbStd":8.5,"zPause1Von":32400,"zPause1Bis":34200,"zPause2Von":45000,"zPause2Bis":46800}}Lagerbedarfsmeldung
api_newstockdemand?ArtikelID=ABC123 - die ArtikelID wird parallel zur ArtikelTypenNr erstellt.
...
Aufruf löst einen Bestellvorschlag des Artikels basierend auf den Mindest und Maximalbeständen aus. Sinnvollerweise nur für Artikel im Standardlagersortiment, und der Aufruf sollte über QRCode per Smartphone erfolgen, damit man als Rückmeldung auch sieht, ob es geklappt hat.
Zeiten erfassen mit api_time_start
Die API api_time_start gibt ein Webanwendung (WebZE) wieder mit der Zeiten in Profacto gebucht werden können. Der Mitarbeiter identifiziert sich anhand eines persönlichen und Aufgaben bezogenen Tokens.
...
| Untergeordnete Seiten (Anzeige untergeordneter Seiten) |
|---|
...