Tankkartentransaktionen importieren

Anstatt Tankkartentransaktionen einzeln einzugeben, können Sie eine Anbieterdatei importieren und das Modul jede Transaktion einem Fahrzeug zuordnen und den Stapel in Beleg-Entwürfe umwandeln lassen. Dieser Artikel führt Sie durch den Ablauf aus Hochladen, Prüfen und Übernehmen. Jeder Schritt erfordert mindestens tankmanagement:view; die Aktionen zum Hochladen, Zuordnen und Übernehmen erfordern tankmanagement:manage.

Vor dem Import

Einen Anbieter registrieren. Erstellen Sie einen Tankkartenanbieter-Datensatz mit einem Namen und einem Anbieterschlüssel. Der Schlüssel muss zu einem vom System mitgelieferten Parser passen. Verfügbare Parser sind Generic CSV (generic-csv), DKV (dkv) und UTA (uta), die alle .csv-Dateien lesen.
Optional Kartenzuordnungen hinzufügen. Ordnen Sie eine Kartennummer einem Fahrzeug zu, mit einem optionalen Gültigkeitszeitraum, sodass Transaktionen auf dieser Karte automatisch zugeordnet werden, selbst wenn die Datei kein Kennzeichen oder keine FIN enthält.

Schritt 1 — Testlauf (Hochladen und Vorschau)

Laden Sie die Anbieterdatei zusammen mit dem Anbieter und einem Idempotenzschlüssel hoch. Das Modul parst die Datei, validiert jede Zeile und ordnet Zeilen Fahrzeugen zu und speichert dann alles als Staging-Importauftrag im Status Pending — es wird noch nichts übernommen. Sie erhalten eine Vorschau-Zusammenfassung:

Zähler	Bedeutung
Zeilen gesamt	Aus der Datei geparste Transaktionen.
Gültige Zeilen	Zeilen, die die Validierung bestanden haben.
Zugeordnet	Zeilen, die mit einem Fahrzeug verknüpft sind.
Nicht zugeordnet	Gültige Zeilen ohne bisheriges Fahrzeug.
Fehlerzeilen	Zeilen, die die Validierung nicht bestanden haben und nicht übernommen werden können.

Hinweis: Der Idempotenzschlüssel verhindert doppelte Importe. Das erneute Hochladen derselben Datei mit demselben Schlüssel gibt den bestehenden Auftrag zurück, anstatt einen zweiten zu erstellen.

Wie Zeilen Fahrzeugen zugeordnet werden

Die Zuordnung versucht drei Methoden der Reihe nach und stoppt beim ersten Treffer, ausschließlich gegen aktive Fahrzeuge:

FIN — die FIN der Zeile gegen die Fahrzeug-FIN.
Kennzeichen — das Kennzeichen, normalisiert (Leerzeichen und Bindestriche entfernt).
Kartenzuordnung — die Kartennummer gegen eine am Transaktionsdatum gültige Zuordnung.

Zeilen ohne Treffer werden als Unmatched gekennzeichnet; Zeilen, die die Validierung nicht bestehen, werden als Error gekennzeichnet.

Schritt 2 — Zuordnungen prüfen und korrigieren

Öffnen Sie den Auftrag, um jede Zeile mit ihrem Zuordnungsstatus, der Zuordnungsmethode (VIN, LicensePlate, CardMapping oder Manual) und etwaigen Validierungsmeldungen zu sehen. Für jede nicht zugeordnete Zeile können Sie ein Fahrzeug manuell zuweisen; die Zeile wird dann mit der Methode Manual zu Matched, und die Zähler des Auftrags werden aktualisiert.

Schritt 3 — Übernehmen

Bei der Übernahme werden nur gültige, fehlerfreie Zeilen verarbeitet. Die Zeilen werden nach Fahrzeug und Rechnungsnummer gruppiert, und jede Gruppe wird zu einem Beleg-Entwurf vom Typ fuel, mit einer Position pro Transaktion (Kraftstoffart, Tankstelle, Menge, Stückpreis und abgeleiteter Mehrwertsteuersatz). Der Auftrag wechselt in den Status Committed und meldet, wie viele Belege erstellt wurden.

Warnung: Nur ein Auftrag im Status Pending kann übernommen werden, und die Übernahme ist für diesen Auftrag unumkehrbar. Ein erneutes Ausführen der Übernahme für einen bereits übernommenen Auftrag gibt lediglich die Zähler der ersten Übernahme zurück; es werden nicht erneut Belege erstellt.

Generic-CSV-Format

Für den Generic-CSV-Parser sind die erforderlichen Spalten transactionDate, fuelType, quantity und grossAmount (der Bruttobetrag muss größer als null sein). Optionale Spalten umfassen cardNumber, licensePlate, vin, station, unitPrice, netAmount, vatAmount, odometer, currency und invoiceNumber. Die Freitext-Kraftstoffart wird automatisch zu einem Kraftstoffart-Schlüssel aufgelöst.