https://github.com/pitwch/dart_proffix_rest
Flutter Client for Proffix Rest API
https://github.com/pitwch/dart_proffix_rest
dart flutter proffix rest-api restful-api
Last synced: 4 months ago
JSON representation
Flutter Client for Proffix Rest API
- Host: GitHub
- URL: https://github.com/pitwch/dart_proffix_rest
- Owner: pitwch
- License: mit
- Created: 2022-03-15T09:49:04.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2025-12-19T07:45:24.000Z (6 months ago)
- Last Synced: 2025-12-22T02:35:48.725Z (6 months ago)
- Topics: dart, flutter, proffix, rest-api, restful-api
- Language: Dart
- Homepage: https://pub.dev/packages/dart_proffix_rest
- Size: 10.2 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
[](https://pub.dev/packages/dart_proffix_rest)
[](https://github.com/pitwch/dart_proffix_rest/actions/workflows/ci.yml)
[](https://codecov.io/gh/pitwch/dart_proffix_rest)
[](https://github.com/pitwch/dart_proffix_rest/blob/main/LICENSE)
# Dart Wrapper für PROFFIX REST-API
Dieser Wrapper wird von der [Pedrett IT+Web AG](https://www.pitw.ch) - dem unabhängigen und innovativen Proffix Px5 Partner - **unterhalten und entwickelt**.
## Übersicht
- [Installation](#installation)
- [Konfiguration](#konfiguration)
- [Optionen](#optionen)
- [Methoden](#methoden)
- [Spezielle Endpunkte](#spezielle-endpunkte)
- [Weitere Beispiele](#weitere-beispiele)
## Installation
```bash
dart pub add dart_proffix_rest
```
### Konfiguration
Die Konfiguration wird dem Client mitgegeben:
| Konfiguration | Beispiel | Type | Bemerkung |
|---------------|-----------------------------------------|----------------------|---------------------------------------|
| restURL | | `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?` | Benötigte Module (mit Komma getrennt) |
| options | ProffixRestOptions(volumeLicence: true) | `ProffixRestOptions` | Optionen (Details unter Optionen) |
Beispiel:
```dart
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 0.4.1 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
```dart
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.):
```dart
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?` | Parameter gemäss [PROFFIX REST API Docs](https://www.proffix.net/Portals/0/content/REST%20API/index.html) |
Folgende unterschiedlichen Methoden sind mit dem Wrapper möglich:
##### Get / Query
```dart
var request =
await pxClient.get(endpoint: "ADR/Adresse/1", params: {"Fields": "AdressNr"});
```
##### Put / Update
```dart
var request =
await pxClient.put(endpoint: "ADR/Adresse/1", {
"Name": "Muster GmbH",
"Ort": "Zürich",
"Zürich": "8000",
});
```
##### Patch / Update
```dart
var request =
await pxClient.patch(endpoint: "ADR/Adresse/1", {
"Name": "Muster GmbH",
"Ort": "Zürich",
"Zürich": "8000",
});
```
##### Post / Create
```dart
var request =
await pxClient.post(endpoint: "ADR/Adresse/1", {
"Name": "Muster GmbH",
"Ort": "Zürich",
"Zürich": "8000",
});
```
##### Delete / Delete
```dart
var request =
await pxClient.delete(endpoint: "ADR/Adresse/1");
```
#### Spezielle Endpunkte
##### Check
Prüft die Login - Credentials und gibt bei Fehlern eine Exception aus.
```dart
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
```dart
// 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.
```dart
// 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
```dart
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)
```dart
pxClient.setPxSessionId("99753429-9716-cf41-066a-8c98edc5e928");
```
##### GET List
Gibt direkt die Liste der PROFFIX REST API aus (ohne Umwege)
```dart
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
```dart
var tim = ProffixHelpers().convertPxTimeToTime('2004-04-11 00:00:00')
```
##### convertTimeToPxTime
Konvertiert einen time.Time in einen Zeitstempel der PROFFIX REST-API
```dart
// 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
```dart
// 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
```dart
// 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](https://github.com/pitwch/dart_proffix_rest/tree/master/example) finden sich weitere,
auskommentierte Beispiele.
### Proof of Work
Dieser Wrapper wird **produktiv** mit allen pfx Apps - den [Apps für Proffix](https://pfx.ch) eingesetzt.