Import fuel-card transactions

Instead of keying fuel-card transactions one by one, you can import a provider file and let the module match each transaction to a vehicle and turn the batch into draft expense documents. This article walks through the upload, review, and commit workflow. Every step needs at least tankmanagement:view; the upload, matching, and commit actions need tankmanagement:manage.

Before you import

1. Register a provider. Create a fuel-card provider record with a name and a provider key. The key must match a parser the system ships. Available parsers are Generic CSV (generic-csv), DKV (dkv), and UTA (uta), all of which read .csv files.
2. Optionally add card mappings. Map a card number to a vehicle, with an optional validity window, so transactions on that card match automatically even when the file has no plate or VIN.

Step 1 — Dry run (upload and preview)

Upload the provider file together with the provider and an idempotency key. The module parses the file, validates each row, and matches rows to vehicles, then stores everything as a staging import job in Pending status — nothing is committed yet. You get a preview summary:

Note: The idempotency key prevents duplicate imports. Re-uploading the same file with the same key returns the existing job instead of creating a second one.

How rows are matched to vehicles

Matching tries three methods in order and stops at the first hit, against active vehicles only:

1. VIN — the row's VIN against the vehicle VIN.
2. Licence plate — the plate, normalised (spaces and dashes removed).
3. Card mapping — the card number against a mapping valid on the transaction date.

Rows with no hit are marked Unmatched; rows that fail validation are marked Error.

Step 2 — Review and fix matches

Open the job to see every row with its match status, match method (VIN, LicensePlate, CardMapping, or Manual), and any validation messages. For each unmatched row you can assign a vehicle manually; the row then becomes Matched with method Manual, and the job's counters update.

Step 3 — Commit

Committing processes only valid, non-error rows. Rows are grouped by vehicle and invoice number, and each group becomes one draft Beleg (receipt/expense document) of type fuel, with a line item per transaction (fuel type, station, quantity, unit price, and derived VAT rate). The job moves to Committed and reports how many expense documents were created.

Warning: Only a job in Pending status can be committed, and committing is one-way for that job. Re-running commit on an already-committed job simply returns the counts from the first commit; it does not create the documents again.

Generic CSV format

For the Generic CSV parser the required columns are transactionDate, fuelType, quantity, and grossAmount (gross must be greater than zero). Optional columns include cardNumber, licensePlate, vin, station, unitPrice, netAmount, vatAmount, odometer, currency, and invoiceNumber. The free-text fuel type is resolved to a fuel-type key automatically.

Related

• Record a refuelling entry
• Assign a refuelling to a vehicle, driver, or cost center
• Correct a refuelling record
• Fuel cost overview and reporting