Dart Wrapper für PROFFIX REST-API

Dieser Wrapper wird von der Pedrett IT+Web AG - dem unabhängigen und innovativen Proffix Px5 Partner - unterhalten und entwickelt.

Übersicht

• Installation
  • Konfiguration
• Optionen
  • Methoden
  • Spezielle Endpunkte
• Weitere Beispiele

Installation

dart pub add dart_proffix_rest

Konfiguration

Die Konfiguration wird dem Client mitgegeben:

Konfiguration	Beispiel	Type	Bemerkung
restURL	myserver.ch:12299	string	URL der REST-API ohne pxapi/v4/
database	DEMO	string	Name der Datenbank
username	USR	string	Names des Benutzers
password	b62cce2fe18f7a156a9c...	string	SHA256-Hash des Benutzerpasswortes
modules	"ADR", "FIB"	List<String>?	Benötigte Module (mit Komma getrennt)
options	ProffixRestOptions(volumeLicence: true)	ProffixRestOptions	Optionen (Details unter Optionen)

Beispiel:

import 'package:dart_proffix_rest/dart_proffix_rest.dart';


var pxClient = ProffixClient(
        database: 'DEMODBPX5',
        restURL: 'https://myserver.ch:12299',
        username: 'USR',
        password: 'b62cce2fe18f7a156a9c719c57bebf0478a3d50f0d7bd18d9e8a40be2e663017',
        modules: ["VOL"],
        options: null);

    var request =
        await pxClient.get(endpoint: "ADR/Adresse", params: {"Limit": "1"});

Hinweis zu VOL: Wenn das Modul "VOL" genutzt wird (oder volumeLicence == true gesetzt ist), führt logout() standardmäßig keinen Aufruf an die REST-API aus. Bei Bedarf können Sie einen Logout mit forceLogout: true erzwingen und mit clearSessionCache steuern, ob ein aktivierter Session-Cache geleert werden soll. Siehe Abschnitt „Logout“ weiter unten.

Optionen

Optionen sind fakultativ und werden in der Regel nicht benötigt:

Option	Beispiel	Bemerkung
key	112a5a90fe28b...242b10141254b4de59028	API-Key als SHA256 - Hash (kann auch direkt mitgegeben werden)
version	v3	API-Version; Standard = v3
loginEndpoint	/pxapi/	Prefix für die API; Standard = /pxapi/
LoginEndpoint	PRO/Login	Endpunkt für Login; Standard = PRO/Login
userAgent	DartWrapper	User Agent; Standard = DartWrapper
timeout	15	Timeout in Sekunden
batchsize	200	Batchgrösse für Batchrequests; Standard = 200
log	true	Aktiviert den Log für Debugging; Standard = false
volumeLicence	false	Nutzt PROFFIX Volumenlizenzierung

Session Caching (optional)

Ab Version X.X kann die PxSessionId optional gecached werden, um unnötige Logins zu vermeiden. Der Cache wird solange verwendet, bis eine Anfrage mit HTTP 401 (Unauthorized) fehlschlägt. In diesem Fall wird die Session automatisch invalidiert, neu eingeloggt und die Anfrage einmalig wiederholt.

Es gibt zwei Möglichkeiten:

1. Einfach aktivieren (Default: Datei-basierter Cache)

Ohne eigene Callbacks wird automatisch ein Datei-basierter Cache verwendet:

• Windows: %APPDATA%/dart_proffix_rest
• Sonst: systemTemp/dart_proffix_rest

final client = ProffixClient(
  database: 'DEMO',
  restURL: 'https://myserver.ch:12299',
  username: 'USR',
  password: '...SHA256... ',
  options: ProffixRestOptions(
    enableSessionCaching: true, // aktiviert den Cache
  ),
);

1. Eigene Speicherlogik verwenden

Sie können eigene Callbacks zum Laden/Speichern/Löschen der Session-ID übergeben (z. B. Secure Storage, SharedPreferences, etc.):

final myStore = MySessionStore(); // ihre eigene Implementierung

final client = ProffixClient(
  database: 'DEMO',
  restURL: 'https://myserver.ch:12299',
  username: 'USR',
  password: '...SHA256... ',
  options: ProffixRestOptions(
    enableSessionCaching: true,
    loadSessionId: () async => await myStore.read(),
    saveSessionId: (sid) async => await myStore.write(sid),
    clearSessionId: () async => await myStore.clear(),
  ),
);

Verhalten im Überblick:

• Der Client lädt beim ersten Zugriff auf getPxSessionId() einen vorhandenen Cache, falls aktiviert.
• Jeder erfolgreiche Request aktualisiert die intern gespeicherte Session und persistiert sie (falls aktiviert).
• Bei HTTP 401 wird der Cache invalidiert, neu eingeloggt und die Anfrage einmal wiederholt.

Methoden

Parameter	Typ	Bemerkung
endpoint	string	Endpunkt der PROFFIX REST-API; z.B. ADR/Adresse,STU/Rapporte...
data	string	Daten (werden automatisch in JSON konvertiert)
parameters	Map<String, dynamic>?	Parameter gemäss PROFFIX REST API Docs

Folgende unterschiedlichen Methoden sind mit dem Wrapper möglich:

Get / Query

    var request =
        await pxClient.get(endpoint: "ADR/Adresse/1", params: {"Fields": "AdressNr"});

Put / Update

    var request =
        await pxClient.put(endpoint: "ADR/Adresse/1", {
  "Name":   "Muster GmbH",
  "Ort":    "Zürich",
  "Zürich": "8000",
 });

Patch / Update

 var request =
        await pxClient.patch(endpoint: "ADR/Adresse/1", {
  "Name":   "Muster GmbH",
  "Ort":    "Zürich",
  "Zürich": "8000",
 });

Post / Create

 var request =
        await pxClient.post(endpoint: "ADR/Adresse/1", {
  "Name":   "Muster GmbH",
  "Ort":    "Zürich",
  "Zürich": "8000",
 });

Delete / Delete

  var request =
        await pxClient.delete(endpoint: "ADR/Adresse/1");

Spezielle Endpunkte

Check

Prüft die Login - Credentials und gibt bei Fehlern eine Exception aus.

 var check = await pxClient.check();

 // If statusCode = 200 -> Success
 if(check.statusCode = 200){
  print("OK")
// Else show exception
 } else {
  print(check)
 }

Upload / Download File

Lädt eine Datei auf PRO/Datei hoch und gibt die DateiNr als String zurück

  // Upload File
  final File file = File("_assets/dart-proffix.png");

  var bytes = file.readAsBytesSync();
  var dataUpload = Uint8List.fromList(bytes);

  var dateiNr = await pxClient.uploadFile("testDate.png",dataUpload);

  // Download File (again)
  var fileAgain = await pxClient.downloadFile(dateiNr: dateiNr.toString());

Logout

Loggt den Client von der PROFFIX REST-API aus und gibt die Session / Lizenz damit wieder frei. Zusätzlich wird der Dart Client geschlossen.

Ab dieser Version berücksichtigt der Client die PROFFIX Volumenlizenzierung (VOL):

• Wenn die Volumenlizenz aktiv ist (Option volumeLicence == true oder das Modul "VOL" gesetzt ist), wird standardmässig kein Logout ausgeführt, da dies nicht erforderlich ist.
• Mit dem Parameter forceLogout: true können Sie dennoch einen Logout erzwingen.
• Mit clearSessionCache: false können Sie steuern, ob ein aktivierter Session-Cache beim Logout geleert werden soll (Standard: true).

Parameter der Methode logout():

• forceLogout (bool, default false): Erzwingt den Logout auch bei VOL.
• clearSessionCache (bool, default true): Löscht bei aktivem Session-Caching die persistierte PxSessionId.

// Standard-Logout (bei VOL wird nichts gemacht)
var logoutResp = await pxClient.logout();

// Logout erzwingen, auch wenn VOL aktiv ist
var forcedLogoutResp = await pxClient.logout(forceLogout: true);

// Logout erzwingen, aber den Session-Cache behalten (z. B. zur Wiederverwendung)
var forcedLogoutKeepCache = await pxClient.logout(
  forceLogout: true,
  clearSessionCache: false,
);

Der Wrapper führt den Logout auch automatisch bei Fehlern durch, damit keine Lizenz geblockt wird. Bei aktivem Session-Caching wird der Cache im Fehlerfall invalidiert und beim nächsten Request automatisch neu eingeloggt.

getPxSessionId()

Gibt die aktuelle PxSessionId zurück

 var pxSessionId = await pxClient.getPxSessionId();

setPxSessionId()

Setzt die PxSessionId manuell

Hinweis: Diese Methode wird nur für Servicelogins (z.b. via Extension oder Proffix WebView benötigt)

 pxClient.setPxSessionId("99753429-9716-cf41-066a-8c98edc5e928");

GET List

Gibt direkt die Liste der PROFFIX REST API aus (ohne Umwege)

var list = await pxClient.getList(listeNr: 1232,data: {});

Hinweis: Der Dateityp (zurzeit nur PDF) kann über den Header File-Type ermittelt werden*

Hilfsfunktionen

convertPxTimeToTime

Konvertiert einen Zeitstempel der PROFFIX REST-API in time.Time

var tim = ProffixHelpers().convertPxTimeToTime('2004-04-11 00:00:00')

convertTimeToPxTime

Konvertiert einen time.Time in einen Zeitstempel der PROFFIX REST-API

// Create DateTime from now
var timeNow = DateTime tmpDateTime = DateTime.now();

// Convert to PxTime
var tm = ProffixHelpers().convertTimeToPxTime(timeNow);

convertLocationId

Extrahiert die ID aus dem Header Location der PROFFIX REST-API

// Example Create Address
  var postReq =
        await tempClient.post(endpoint: "ADR/Adresse", data: {
    "Name": "Test",
    "Vorname": "Rest",
    "Ort": "Zürich",
    "PLZ": "8000",
    "Land": {"LandNr": "CH"},
  });

  // Get LocationID from Header --> returns newly created AdressNr from posted Address
 createdAdressNr = ProffixHelpers().convertLocationId(postReq.headers);

getFilteredCount

Extrahiert die Anzahl Ergebnisse aus dem Header PxMetaData der PROFFIX REST-API

// Example Get Address with Filter PLZ == Münchwilen
    var getReq = await tempClient.get(endpoint: "ADR/Adresse", params: {
      "Filter": "PLZ=='Münchwilen'",
      "Fields": "AdressNr,Name,Vorname,Ort,PLZ"
    });

  // Get FilteredCount from Header --> returns the total amount of filtered Addresses
 countAddresses = ProffixHelpers().getFilteredCount(getReq.headers);

Weitere Beispiele

Im Ordner /example finden sich weitere, auskommentierte Beispiele.

Proof of Work

Dieser Wrapper wird produktiv mit allen pfx Apps - den Apps für Proffix eingesetzt.