Accounting CSV/ZIP interface

1. Purpose

The CSV/ZIP export is a transport-neutral hand-off for booked foreign invoices. One ZIP contains the invoice header, supplier snapshot, all vehicle positions, a manifest and every verified original document.

2. Foreign-invoice workflow in FLEET Mira

1. Create the supplier and cost categories.
2. Create an invoice draft with number/date, totals and payment details.
3. Add one or more vehicle-linked cost/credit positions.
4. Add received originals; the document vault uploads and verifies each hash.
5. Resolve the gross/split difference to exactly zero cents.
6. Verify and book the invoice.
7. Export once or transfer through REST. Corrections use cancellation/credit, never edits to booked rows.

flowchart LR
    H[Invoice header] --> P[Vehicle positions]
    P --> D[Original documents]
    D --> V[Cloud verification]
    V --> C[Cent-accurate validation]
    C --> B[Booking]
    B --> Z[CSV/ZIP export]

3. Archive layout

Filename: Accounting_<document-number>_<invoice-id>.zip (filesystem-invalid characters are replaced).

manifest.json
invoice.csv
supplier.csv
positions.csv
documents/
  <document-id>_<original-file-name>

CSV is UTF-8 with BOM and semicolon delimiter. The first row contains stable field names. Line endings are CRLF. Values containing delimiter, quotes or line breaks are RFC-4180 quoted.

4. manifest.json

Field	Meaning
format	DLTNG-ACCOUNTING-EXPORT legacy contract token
version	export format version
idempotency_key	stable duplicate-prevention key
invoice_id	FLEET Mira invoice UUID
documents[]	ordered archive names of original documents

5. invoice.csv

Exactly one data row.

Field	Meaning/function
id	immutable invoice UUID
document_type	INVOICE or CREDIT_NOTE
correction_of_invoice_id	linked corrected invoice, optional
document_number	supplier invoice/credit number
document_date	ISO document date
delivery_date	ISO performance/delivery date, optional
delivery_note_number	supplier delivery note, optional
cost_center	accounting cost centre, optional
payable_until	due date
payment_term_days	net payment term
discount_term_days	cash-discount term
discount_rate_bp	discount basis points
net_cents	declared invoice net amount
tax_cents	declared tax amount
gross_cents	calculated net + tax
currency	currently EUR
status	must be BOOKED
booked_at_utc, booked_by	booking evidence
created_at_utc, updated_at_utc	technical history
description, note	optional business text

6. supplier.csv

Exactly one snapshot row.

Field	Meaning/function
id	supplier UUID
supplier_number	internal supplier number
name	supplier name
creditor_number	accounting creditor number
street, postal_code, city, country	postal address
tax_id	tax/VAT identifier
phone, email	validated contact data
payment_term_days	supplier default

The row is the current master snapshot at export time; the invoice ID and originals remain the audit anchor.

7. positions.csv

One row per active invoice position.

Field	Meaning/function
id	position UUID
invoice_id	owning invoice UUID
vehicle_id	vehicle UUID
vehicle_internal_number	operational fleet number
vehicle_registration	registration snapshot
vehicle_vin	VIN snapshot
cost_category_id, cost_category_code, cost_category_name	cost classification
entry_type	COST or CREDIT
description	booking text
valid_from, valid_to, document_date	invoice date for invoice-bound positions
net_cents, tax_cents, gross_cents	cent amounts
tax_rate_bp	VAT basis points
variable	always true for invoice-bound positions
note	optional text

Signed comparison amount is cost positive and credit negative. For a credit-note header the comparison normalises the invoice sign so the displayed difference remains meaningful.

8. Original documents

Only locally verified originals are included. Bytes must match the stored SHA-256; generated previews never replace XML or hybrid invoice originals. The ZIP itself is a delivery package, not the retention master. The local financial archive remains the evidence store; external backup is optional.

9. Validation rules

• gross_cents = net_cents + tax_cents;
• signed sum of active position gross equals the invoice gross under document-type sign rules;
• every position references exactly one vehicle;
• every manifest document exists in documents/;
• duplicate supplier/document number/date or identical document hash requires administrative override before booking;
• only one successful export per idempotency key.

10. Audit and import guidance

FLEET Mira audits export start/result, invoice, document IDs and correlation ID but not document content. Importers should validate manifest version, reject path traversal, process to a transaction/staging area, persist the idempotency key and return a reconciliation report containing invoice ID and target accounting ID.

11. Compatibility

Consumers must ignore unknown additive columns. Required column removal, rename, type or sign change creates a new format version. The DLTNG-... format string remains a legacy technical identifier.