199 lines
14 KiB
Markdown
199 lines
14 KiB
Markdown
# holzleitner_api (EXPERIMENTAL)
|
|
Backend für die Holzleitner-Lieferservice-App — Tour, Beladung, Ausführung.
|
|
|
|
This Dart package is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) project:
|
|
|
|
- API version: 0.1.0
|
|
- Generator version: 7.10.0
|
|
- Build package: org.openapitools.codegen.languages.DartDioClientCodegen
|
|
|
|
## Requirements
|
|
|
|
* Dart 2.15.0+ or Flutter 2.8.0+
|
|
* Dio 5.0.0+ (https://pub.dev/packages/dio)
|
|
|
|
## Installation & Usage
|
|
|
|
### pub.dev
|
|
To use the package from [pub.dev](https://pub.dev), please include the following in pubspec.yaml
|
|
```yaml
|
|
dependencies:
|
|
holzleitner_api: 1.0.0
|
|
```
|
|
|
|
### Github
|
|
If this Dart package is published to Github, please include the following in pubspec.yaml
|
|
```yaml
|
|
dependencies:
|
|
holzleitner_api:
|
|
git:
|
|
url: https://github.com/GIT_USER_ID/GIT_REPO_ID.git
|
|
#ref: main
|
|
```
|
|
|
|
### Local development
|
|
To use the package from your local drive, please include the following in pubspec.yaml
|
|
```yaml
|
|
dependencies:
|
|
holzleitner_api:
|
|
path: /path/to/holzleitner_api
|
|
```
|
|
|
|
## Getting Started
|
|
|
|
Please follow the [installation procedure](#installation--usage) and then run the following:
|
|
|
|
```dart
|
|
import 'package:holzleitner_api/holzleitner_api.dart';
|
|
|
|
|
|
final api = HolzleitnerApi().getAccountsApi();
|
|
final int personalnummer = 789; // int | Personalnummer des Accounts
|
|
|
|
try {
|
|
final response = await api.getAccount(personalnummer);
|
|
print(response);
|
|
} catch on DioException (e) {
|
|
print("Exception when calling AccountsApi->getAccount: $e\n");
|
|
}
|
|
|
|
```
|
|
|
|
## Documentation for API Endpoints
|
|
|
|
All URIs are relative to *http://localhost*
|
|
|
|
Class | Method | HTTP request | Description
|
|
------------ | ------------- | ------------- | -------------
|
|
[*AccountsApi*](doc/AccountsApi.md) | [**getAccount**](doc/AccountsApi.md#getaccount) | **GET** /accounts/{personalnummer} | Liest den Account zu einer Personalnummer.
|
|
[*AdminApi*](doc/AdminApi.md) | [**deliveredBelegnummern**](doc/AdminApi.md#deliveredbelegnummern) | **GET** /admin/delivered-belegnummern | Liefert die Belegnummern ausgelieferter (abgeschlossener) Lieferungen, **deren Liefermail noch nicht versendet wurde** (`mail_sent_at IS NULL`). „Ausgeliefert\" = es existiert ein Abschluss. Mit `day` (DD-MM-YYYY) nur Abschlüsse dieses Berliner Kalendertages; **ohne `day` alle offenen** (über alle Tage) — so bleiben Belege über Mitternacht nicht hängen.
|
|
[*AdminApi*](doc/AdminApi.md) | [**importErp**](doc/AdminApi.md#importerp) | **POST** /admin/import-erp | Stößt den ERP-Import für ein Datum an und liefert die Zusammenfassung.
|
|
[*AdminApi*](doc/AdminApi.md) | [**markMailSent**](doc/AdminApi.md#markmailsent) | **POST** /admin/mark-mail-sent | Markiert die Liefermails der angegebenen Belegnummern als **versendet** (`mail_sent_at = now()`, nur wo noch offen). Vom Mailclient aufzurufen, NACHDEM ERPframe die Mails erfolgreich verschickt hat — danach erscheinen die Belege nicht mehr in `GET /admin/delivered-belegnummern`.
|
|
[*AdminApi*](doc/AdminApi.md) | [**pushCompletion**](doc/AdminApi.md#pushcompletion) | **POST** /admin/push-completion | Stößt das ERP-Rückschreiben eines bereits lokal abgeschlossenen Lieferabschlusses erneut an (idempotenter Retry, falls der automatische Push beim Abschluss fehlschlug).
|
|
[*AttachmentsApi*](doc/AttachmentsApi.md) | [**getAttachment**](doc/AttachmentsApi.md#getattachment) | **GET** /attachments/{id} | Liefert ein gerendertes Vorschaubild des Attachments (Bytes), geladen aus DOCUframe. Auflösung/Format über Query-Parameter steuerbar (`?w=&h=&q=&ext=&page=`).
|
|
[*CarsApi*](doc/CarsApi.md) | [**createMyCar**](doc/CarsApi.md#createmycar) | **POST** /me/cars | Legt ein neues Fahrzeug für den angemeldeten Fahrer an.
|
|
[*CarsApi*](doc/CarsApi.md) | [**listMyCars**](doc/CarsApi.md#listmycars) | **GET** /me/cars | Listet die Fahrzeuge des angemeldeten Fahrers.
|
|
[*CarsApi*](doc/CarsApi.md) | [**updateMyCar**](doc/CarsApi.md#updatemycar) | **PATCH** /me/cars/{car_id} | Aktualisiert ein Fahrzeug (Kennzeichen ändern / deaktivieren).
|
|
[*DeliveriesApi*](doc/DeliveriesApi.md) | [**applyCredit**](doc/DeliveriesApi.md#applycredit) | **POST** /deliveries/{delivery_id}/credit | Wendet ein Betrags-Gutschrift-Ereignis an (`set`/`remove`). Append-only, idempotent über `clientEventId`. Nur bei aktiver Lieferung; bei `set` sind Betrag (0 < x ≤ 150 €, 10-€-Schritte) und Grund Pflicht. Antwort: der aktuelle Gutschrift-Stand (`null`, wenn entfernt).
|
|
[*DeliveriesApi*](doc/DeliveriesApi.md) | [**assignCar**](doc/DeliveriesApi.md#assigncar) | **PUT** /deliveries/{delivery_id}/assigned-car | Setzt das `assigned_car_id` einer Lieferung. `carId: null` löst die Zuordnung wieder. Der Use Case stellt sicher, dass das Fahrzeug zum angemeldeten Account gehört.
|
|
[*DeliveriesApi*](doc/DeliveriesApi.md) | [**cancel**](doc/DeliveriesApi.md#cancel) | **POST** /deliveries/{delivery_id}/cancel | Setzt die Lieferung auf `canceled` — endgültig. Erlaubt aus `active` und `held`.
|
|
[*DeliveriesApi*](doc/DeliveriesApi.md) | [**complete**](doc/DeliveriesApi.md#complete) | **POST** /deliveries/{delivery_id}/complete | Schließt die Lieferung ab — `state = completed`. Nur aus `active`.
|
|
[*DeliveriesApi*](doc/DeliveriesApi.md) | [**createNote**](doc/DeliveriesApi.md#createnote) | **POST** /deliveries/{delivery_id}/notes | Legt eine neue Notiz an einer Lieferung an. Mindestens eines von `text` und `imageAttachment` muss inhaltlich gefüllt sein (Leerstrings werden serverseitig getrimmt und als leer behandelt).
|
|
[*DeliveriesApi*](doc/DeliveriesApi.md) | [**deleteNote**](doc/DeliveriesApi.md#deletenote) | **DELETE** /deliveries/{delivery_id}/notes/{note_id} | Löscht eine Notiz. Antwortet mit `204 No Content`.
|
|
[*DeliveriesApi*](doc/DeliveriesApi.md) | [**deleteServiceValue**](doc/DeliveriesApi.md#deleteservicevalue) | **DELETE** /deliveries/{delivery_id}/services/{service_id} | Entfernt den Service-Wert einer Lieferung (Service „nicht gesetzt\"). Nur bei aktiver Lieferung. Antwort `204`.
|
|
[*DeliveriesApi*](doc/DeliveriesApi.md) | [**hold**](doc/DeliveriesApi.md#hold) | **POST** /deliveries/{delivery_id}/hold | Setzt die Lieferung auf `held`. Nur aus `active` zulässig.
|
|
[*DeliveriesApi*](doc/DeliveriesApi.md) | [**resume**](doc/DeliveriesApi.md#resume) | **POST** /deliveries/{delivery_id}/resume | Setzt die Lieferung zurück auf `active`. Nur aus `held` zulässig.
|
|
[*DeliveriesApi*](doc/DeliveriesApi.md) | [**setService**](doc/DeliveriesApi.md#setservice) | **PUT** /deliveries/{delivery_id}/services/{service_id} | Setzt (Upsert) den Wert eines Service für eine Lieferung. Genau das zum Service-Typ passende Feld (`boolValue`/`numericValue`) muss gesetzt sein; numerische Werte werden gegen min/max geprüft. Nur bei aktiver Lieferung.
|
|
[*DeliveriesApi*](doc/DeliveriesApi.md) | [**updateNote**](doc/DeliveriesApi.md#updatenote) | **PATCH** /deliveries/{delivery_id}/notes/{note_id} | Ändert Text/Bild einer Notiz. Innerhalb des (geteilten) Accounts darf jeder Fahrer Notizen pflegen — kein Autor-Check. `delivery_id` ist Teil des Pfads (REST-Konsistenz), die Notiz wird über `note_id` adressiert.
|
|
[*DeliveriesApi*](doc/DeliveriesApi.md) | [**uploadNoteImage**](doc/DeliveriesApi.md#uploadnoteimage) | **POST** /deliveries/{delivery_id}/notes/image | Lädt ein Bild zu einer Lieferung hoch (multipart/form-data, Feld `file`) und legt dafür eine Bild-Notiz an. Das Bild geht in den DOCUframe-Dokumentenspeicher; gespeichert wird die zurückgelieferte Referenz (`~ObjectID`) als `image_attachment` der Notiz.
|
|
[*HealthApi*](doc/HealthApi.md) | [**health**](doc/HealthApi.md#health) | **GET** /health | Health-Endpoint für Load-Balancer und Container-Probes. Bewusst kein Auth — eine `200 ok`-Antwort darf nicht von der Auth abhängen.
|
|
[*PaymentMethodsApi*](doc/PaymentMethodsApi.md) | [**createPaymentMethod**](doc/PaymentMethodsApi.md#createpaymentmethod) | **POST** /payment-methods | Legt eine neue Zahlungsmethode an.
|
|
[*PaymentMethodsApi*](doc/PaymentMethodsApi.md) | [**deletePaymentMethod**](doc/PaymentMethodsApi.md#deletepaymentmethod) | **DELETE** /payment-methods/{id} | Hartes Löschen. `409 Conflict`, wenn die Methode von einer Lieferung referenziert wird — der Admin soll dann den `active = false`-Pfad nutzen.
|
|
[*PaymentMethodsApi*](doc/PaymentMethodsApi.md) | [**listPaymentMethods**](doc/PaymentMethodsApi.md#listpaymentmethods) | **GET** /payment-methods | Listet die Zahlungsmethoden.
|
|
[*PaymentMethodsApi*](doc/PaymentMethodsApi.md) | [**updatePaymentMethod**](doc/PaymentMethodsApi.md#updatepaymentmethod) | **PATCH** /payment-methods/{id} | Patcht Anzeige-Name und/oder Aktiv-Flag.
|
|
[*ScansApi*](doc/ScansApi.md) | [**applyScans**](doc/ScansApi.md#applyscans) | **POST** /scans | Wendet eine Liste von Scan-Events idempotent an.
|
|
[*ServicesApi*](doc/ServicesApi.md) | [**createService**](doc/ServicesApi.md#createservice) | **POST** /services | Legt einen neuen Service an.
|
|
[*ServicesApi*](doc/ServicesApi.md) | [**deleteService**](doc/ServicesApi.md#deleteservice) | **DELETE** /services/{id} | Hartes Löschen. `409 Conflict`, wenn der Service noch von einer Lieferung referenziert wird — dann stattdessen deaktivieren.
|
|
[*ServicesApi*](doc/ServicesApi.md) | [**listServices**](doc/ServicesApi.md#listservices) | **GET** /services | Listet die Services (sortiert nach `sortOrder`).
|
|
[*ServicesApi*](doc/ServicesApi.md) | [**updateService**](doc/ServicesApi.md#updateservice) | **PATCH** /services/{id} | Patcht Name/Grenzen/Aktiv-Flag/Sortierung. `kind` ist nicht änderbar.
|
|
[*SyncApi*](doc/SyncApi.md) | [**syncTour**](doc/SyncApi.md#synctour) | **POST** /sync/tour | Sync-Endpoint für das ERP: legt eine Tagestour samt Lieferungen und Positionen idempotent an. Identität pro Tour `(driver_personalnummer, tour_date)`, pro Lieferung `(belegart_id, belegnummer)`.
|
|
[*ToursApi*](doc/ToursApi.md) | [**getTour**](doc/ToursApi.md#gettour) | **GET** /tours/{tour_id} | Lädt eine Tour mit allen Lieferungen, Positionen und referenzierten Stammdaten — die App nutzt das als einzigen großen Read.
|
|
[*ToursApi*](doc/ToursApi.md) | [**listMyToursToday**](doc/ToursApi.md#listmytourstoday) | **GET** /me/tours/today | Listet heutige Touren des angemeldeten Fahrers (Filter aus dem JWT).
|
|
[*ToursApi*](doc/ToursApi.md) | [**setDeliveryOrder**](doc/ToursApi.md#setdeliveryorder) | **PUT** /tours/{tour_id}/delivery-order | Schreibt die Sortier-Reihenfolge aller Lieferungen einer Tour neu. Der Client schickt die **vollständige** neue Reihenfolge; fehlende oder fremde Lieferungs-Ids werden mit `400 validation` abgelehnt.
|
|
|
|
|
|
## Documentation For Models
|
|
|
|
- [Account](doc/Account.md)
|
|
- [Address](doc/Address.md)
|
|
- [ApplyScansRequest](doc/ApplyScansRequest.md)
|
|
- [ApplyScansResponse](doc/ApplyScansResponse.md)
|
|
- [Article](doc/Article.md)
|
|
- [AssignCarRequest](doc/AssignCarRequest.md)
|
|
- [AuditAction](doc/AuditAction.md)
|
|
- [CancelDeliveryRequest](doc/CancelDeliveryRequest.md)
|
|
- [Car](doc/Car.md)
|
|
- [CarResponse](doc/CarResponse.md)
|
|
- [CarsList](doc/CarsList.md)
|
|
- [CompleteDeliveryAcknowledgements](doc/CompleteDeliveryAcknowledgements.md)
|
|
- [ContactChannel](doc/ContactChannel.md)
|
|
- [ContactKind](doc/ContactKind.md)
|
|
- [ContactRole](doc/ContactRole.md)
|
|
- [ContactSource](doc/ContactSource.md)
|
|
- [CreateCarRequest](doc/CreateCarRequest.md)
|
|
- [CreateDeliveryNoteRequest](doc/CreateDeliveryNoteRequest.md)
|
|
- [CreatePaymentMethodRequest](doc/CreatePaymentMethodRequest.md)
|
|
- [CreateServiceRequest](doc/CreateServiceRequest.md)
|
|
- [CreditAction](doc/CreditAction.md)
|
|
- [Customer](doc/Customer.md)
|
|
- [CustomerContact](doc/CustomerContact.md)
|
|
- [DeliveredBelegnummernResponse](doc/DeliveredBelegnummernResponse.md)
|
|
- [Delivery](doc/Delivery.md)
|
|
- [DeliveryCredit](doc/DeliveryCredit.md)
|
|
- [DeliveryCreditEventRequest](doc/DeliveryCreditEventRequest.md)
|
|
- [DeliveryCreditResponse](doc/DeliveryCreditResponse.md)
|
|
- [DeliveryItem](doc/DeliveryItem.md)
|
|
- [DeliveryNote](doc/DeliveryNote.md)
|
|
- [DeliveryNoteResponse](doc/DeliveryNoteResponse.md)
|
|
- [DeliveryOrderEntry](doc/DeliveryOrderEntry.md)
|
|
- [DeliveryResponse](doc/DeliveryResponse.md)
|
|
- [DeliveryServiceResponse](doc/DeliveryServiceResponse.md)
|
|
- [DeliveryServiceValue](doc/DeliveryServiceValue.md)
|
|
- [DeliveryState](doc/DeliveryState.md)
|
|
- [DeliveryWithItems](doc/DeliveryWithItems.md)
|
|
- [HoldDeliveryRequest](doc/HoldDeliveryRequest.md)
|
|
- [ImportSummary](doc/ImportSummary.md)
|
|
- [MarkMailSentRequest](doc/MarkMailSentRequest.md)
|
|
- [MarkMailSentResponse](doc/MarkMailSentResponse.md)
|
|
- [PaymentMethod](doc/PaymentMethod.md)
|
|
- [PaymentMethodResponse](doc/PaymentMethodResponse.md)
|
|
- [PaymentMethodsList](doc/PaymentMethodsList.md)
|
|
- [ScanEvent](doc/ScanEvent.md)
|
|
- [ScanResult](doc/ScanResult.md)
|
|
- [ScanResultStatus](doc/ScanResultStatus.md)
|
|
- [ScanState](doc/ScanState.md)
|
|
- [ScanStatus](doc/ScanStatus.md)
|
|
- [Service](doc/Service.md)
|
|
- [ServiceKind](doc/ServiceKind.md)
|
|
- [ServiceResponse](doc/ServiceResponse.md)
|
|
- [ServicesList](doc/ServicesList.md)
|
|
- [SetDeliveryOrderRequest](doc/SetDeliveryOrderRequest.md)
|
|
- [SetDeliveryOrderResponse](doc/SetDeliveryOrderResponse.md)
|
|
- [SetDeliveryServiceRequest](doc/SetDeliveryServiceRequest.md)
|
|
- [SyncContactChannel](doc/SyncContactChannel.md)
|
|
- [SyncContactSource](doc/SyncContactSource.md)
|
|
- [SyncDelivery](doc/SyncDelivery.md)
|
|
- [SyncDeliveryItem](doc/SyncDeliveryItem.md)
|
|
- [SyncTourRequest](doc/SyncTourRequest.md)
|
|
- [SyncTourResponse](doc/SyncTourResponse.md)
|
|
- [Tour](doc/Tour.md)
|
|
- [TourDetails](doc/TourDetails.md)
|
|
- [TourSummary](doc/TourSummary.md)
|
|
- [TourSummaryList](doc/TourSummaryList.md)
|
|
- [UpdateCarRequest](doc/UpdateCarRequest.md)
|
|
- [UpdateDeliveryNoteRequest](doc/UpdateDeliveryNoteRequest.md)
|
|
- [UpdatePaymentMethodRequest](doc/UpdatePaymentMethodRequest.md)
|
|
- [UpdateServiceRequest](doc/UpdateServiceRequest.md)
|
|
- [Warehouse](doc/Warehouse.md)
|
|
|
|
|
|
## Documentation For Authorization
|
|
|
|
|
|
Authentication schemes defined for the API:
|
|
### admin_api_key
|
|
|
|
- **Type**: API key
|
|
- **API key parameter name**: X-Admin-Api-Key
|
|
- **Location**: HTTP header
|
|
|
|
### bearer_auth
|
|
|
|
- **Type**: HTTP Bearer Token authentication (JWT)
|
|
|
|
|
|
## Author
|
|
|
|
|
|
|