Accounting REST API¶

1. Purpose¶

The accounting adapter transmits a booked foreign invoice, supplier, vehicle positions and original documents to a configured HTTPS endpoint. FLEET Mira is the HTTP client; the accounting system implements the receiver.

2. Preconditions¶

invoice status is BOOKED;
header totals match active positions to the cent;
at least one original document is locally verified; backup status is irrelevant;
user has finance.export;
endpoint uses HTTPS;
no successful export exists for the same idempotency key.

3. Request¶

POST /configured/accounting/path HTTP/1.1
Content-Type: multipart/form-data; boundary=...
Idempotency-Key: <stable-sha256>

Multipart fields:

Field	Content type	Meaning
`metadata`	`application/json; charset=utf-8`	complete versioned accounting bundle
`document_1...n`	original MIME type	byte-identical, hash-verified originals

4. Metadata model¶

Top level:

Field	Meaning
`format`	technical constant `DLTNG-ACCOUNTING` retained for compatibility
`version`	contract version
`invoice`	invoice header
`supplier`	supplier master snapshot
`positions`	vehicle-linked cost/credit positions

Important invoice fields include stable ID, document type/number/date, delivery date/number, cost centre, due date, payment/discount terms, net/tax/gross cents, status and currency. Supplier includes stable ID, supplier/creditor numbers, address, tax ID, phone and email. Positions include stable ID, vehicle ID/number/registration/VIN, category, type, description, validity/document dates, net/tax/gross cents, tax rate basis points and variable flag.

Amounts are integer cents. Tax rates are integer basis points (1900 = 19.00%). Credits are identified by type; stored amounts remain positive.

5. Idempotency¶

The key is deterministic for invoice ID, booked revision and export contract version. A receiver must return the original successful result for a repeated key and must not post twice.

6. Response¶

Success (200 or 201):

{
  "status": "accepted",
  "external_id": "ACC-2026-004712",
  "message": "Imported"
}

external_id is persisted with response time. A non-2xx response keeps the outbox item retryable and stores a sanitised error. Authentication bodies/secrets are not audited.

7. Process¶

sequenceDiagram
    participant U as User
    participant M as FLEET Mira
    participant V as Document vault
    participant A as Accounting endpoint
    U->>M: Transfer booked invoice
    M->>V: Download and hash-check originals
    M->>M: Build bundle and idempotency key
    M->>A: HTTPS multipart POST
    alt accepted
        A-->>M: external_id
        M->>M: Mark export successful and audit
    else temporary failure
        A-->>M: error
        M->>M: Persist outbox retry
    end

8. Receiver requirements¶

enforce HTTPS and authenticated clients;
limit body size and accepted MIME types;
stream originals and verify declared hashes where exposed;
implement atomic invoice/document handling;
persist idempotency keys;
return stable external IDs;
redact credentials and document contents from logs.

9. Error handling¶

Status	Receiver meaning
`400/422`	permanent contract/validation error; operator correction required
`401/403`	credentials/permission error
`409`	idempotency or business conflict; return existing result when equivalent
`413`	payload exceeds receiver limit
`429`	retry later; honour `Retry-After`
`5xx`	transient receiver failure; outbox retry

10. Compatibility¶

Fields are additive within a contract version. Removing/renaming fields or changing amount semantics requires a new version. The legacy DLTNG-ACCOUNTING format token is deliberately not rebranded.