FiBu REST API

1. Zweck

Der FiBu-Adapter überträgt eine gebuchte Fremdrechnung mit Lieferant, Fahrzeugpositionen und Originalbelegen an einen konfigurierten HTTPS-Endpunkt. FLEET Mira ist HTTP-Client; das FiBu-System implementiert den Empfänger.

2. Voraussetzungen

• Rechnungsstatus BOOKED;
• Kopf-/Positionssummen centgenau gleich;
• mindestens ein lokal verifizierter Originalbeleg; der Backupstatus ist unerheblich;
• Berechtigung finance.export;
• HTTPS-Endpunkt;
• kein erfolgreicher Export mit demselben Idempotenzschlüssel.

3. Request

POST /konfigurierter/fibu/pfad HTTP/1.1
Content-Type: multipart/form-data; boundary=...
Idempotency-Key: <stabiler-sha256>

Feld	Content-Type	Bedeutung
metadata	application/json; charset=utf-8	vollständiges versioniertes Rechnungsbundle
document_1...n	Original-MIME-Type	byteidentische, hashgeprüfte Originale

4. Metadatenmodell

Feld	Bedeutung
format	technische Konstante DLTNG-ACCOUNTING (Kompatibilität)
version	Vertragsversion
invoice	Rechnungskopf
supplier	Lieferanten-Snapshot
positions	fahrzeugbezogene Kosten-/Gutschriftpositionen

Rechnung: stabile ID, Dokumentart/-nummer/-datum, Lieferdatum/-nummer, Kostenstelle, Zahlbar-bis, Zahlungs-/Skontofristen, Netto/Steuer/Brutto in Cent, Status, Währung. Lieferant: stabile ID, Lieferanten-/Kreditorennummer, Anschrift, Steuer-ID, Telefon, E-Mail. Position: stabile ID, Fahrzeug-ID/Nummer/Kennzeichen/FIN, Kostenart, Typ, Bezeichnung, Gültigkeits-/Belegdatum, Netto/Steuer/Brutto in Cent, Steuersatz in Basispunkten, Variabelkennzeichen.

Beträge sind Integer-Cent; Steuersatz 1900 = 19,00 %. Gutschriften werden über den Typ markiert, Beträge bleiben positiv.

5. Idempotenz

Der Schlüssel wird deterministisch aus Rechnungs-ID, Buchungsrevision und Vertragsversion gebildet. Wiederholungen müssen dasselbe Ergebnis liefern und dürfen keine zweite Buchung erzeugen.

6. Antwort

Erfolg (200/201):

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

external_id und Antwortzeit werden gespeichert. Nicht-2xx verbleibt als wiederholbarer Outboxauftrag mit bereinigtem Fehler; Authentifizierungsinhalte werden nicht auditiert.

7. Ablauf

sequenceDiagram
    participant U as Benutzer
    participant M as FLEET Mira
    participant V as Belegarchiv
    participant A as FiBu-Endpunkt
    U->>M: Gebuchte Rechnung übertragen
    M->>V: Originale laden und Hash prüfen
    M->>M: Bundle und Idempotenzschlüssel bilden
    M->>A: HTTPS Multipart POST
    alt angenommen
        A-->>M: external_id
        M->>M: Export erfolgreich + Audit
    else temporärer Fehler
        A-->>M: Fehler
        M->>M: Outbox-Wiederholung speichern
    end

8. Anforderungen Empfänger

• HTTPS und Clientauthentifizierung;
• Größen-/MIME-Limits;
• streamender Empfang und Hashprüfung;
• atomare Verarbeitung von Rechnung/Belegen;
• persistente Idempotenzschlüssel;
• stabile externe ID;
• keine Credentials/Belegtexte in Logs.

9. Fehlerbehandlung

Status	Bedeutung
400/422	dauerhafter Vertrags-/Validierungsfehler
401/403	Zugang/Berechtigung
409	Idempotenz/Fachkonflikt; bei Gleichheit vorhandenes Ergebnis liefern
413	Payload zu groß
429	später wiederholen; Retry-After beachten
5xx	temporärer Empfängerfehler; Outboxretry

10. Kompatibilität

Innerhalb einer Vertragsversion sind Felder additiv. Entfernen/Umbenennen oder geänderte Betragssemantik erfordern neue Version. Der Legacy-Formattoken DLTNG-ACCOUNTING wird bewusst nicht umbenannt.