REST-API (demnächst)

Warum eine API?

FloOne ist heute ein vollständiges Self-Service-Dashboard für Multichannel-Händler — alles was du brauchst, läuft im Browser. Aber manche Workflows enden nicht in FloOne: ein eigener Online-Shop, ein internes ERP, ein Excel-Report fürs Controlling, ein Reporting- Dashboard. Damit FloOne in diese Welten reinpasst, kommt eine saubere, versionierte REST-API.

Was die API können soll

Die geplanten Endpoints decken die drei FloOne-Säulen ab — Order, Lager, Versand — plus den Brücken-Layer zur Buchhaltung.

Order-Management

• Bestellungen abfragen — Filter nach Plattform, Status, Zeitraum, Bucket. Pagination, ETags.
• Bestellungen anlegen — für eigene Shop-Frontends ohne Standard-Connector.
• Status & Buckets aktualisieren — Auslöser für die Workflow-Engine (Versand, Rechnung, Refund).
• Refunds & Stornos — Teilrefund pro Position, inklusive Rückbuchungs-Logik.

Artikel & Lager

• Artikelstamm CRUD — SKU, EAN, Preise pro Channel, Custom-Attribute.
• Bestandsabfrage & -korrektur — pro Lager, mit Buchungsgrund für die Inventurspur.
• Bundle / Stückliste — BOM-Komponenten lesen und schreiben.

Rechnungen & Buchhaltung

• Rechnungen erzeugen & abrufen — PDF, ZUGFeRD-XML, inkl. §25a, §13b und OSS.
• Buchungsjournal exportieren — JSON-Stream als DATEV-/Lexoffice-Alternative für eigene Reportings.
• UStVA-Kennzahlen abrufen — Monatsaggregat, read-only.

Versand

• Labels erzeugen — Carrier-agnostisch über die FloOne-Routing-Logik (DHL, DPD, GLS, UPS, manual).
• Tracking-Status abrufen — letzter bekannter Event pro Sendung.
• Retourenlabels — manuell oder per Auto-Mode.

Webhooks (Outbound)

Push statt Poll: FloOne wird Webhooks für die wichtigsten Events anbieten — neue Bestellung, Status-Wechsel, Rechnung erstellt, Sendung zugestellt. Signatur über HMAC-SHA256, Replay-Schutz über Timestamp + Idempotency-Key.

Auth & Sicherheit

• Personal Access Tokens im Self-Service erstellbar (analog GitHub) — Header Authorization: Bearer floone_pat_….
• Multi-Tenancy bleibt strikt: jeder Token ist auf genau einen Tenant gemappt. Kein Endpoint liefert Daten über Tenant-Grenzen.
• Rate-Limit pro Token — fair-use Default, höhere Limits auf Anfrage.
• Scopes — schreibender Zugriff (orders:write, articles:write, invoices:write) optional aktivierbar; Default ist read-only.
• Audit-Log pro Token-Aufruf — IP, Endpoint, Statuscode, Antwortzeit.

Versionierung & Stabilitätszusage

Sobald die API als /api/v1/ öffentlich ist, gilt jedes Breaking Change als Major-Bump (/api/v2/). Ältere Versionen laufen mindestens 12 Monate parallel. Deprecation wird per Header (Deprecation, Sunset) und per E-Mail an alle Token-Inhaber angekündigt.

OpenAPI & SDKs

FloOne nutzt intern FastAPI — die OpenAPI-Spec wird automatisch generiert und unter /api/v1/openapi.json öffentlich verfügbar sein. Daraus lassen sich Client-Libraries für Python, TypeScript, PHP und Go mit Standard-Tools erzeugen. Offizielle SDKs folgen je nach Bedarf.

Zeitplan

Wir bauen die API in Stufen aus — erst read-only (Orders, Articles, Invoices), dann Write-Endpoints, danach Webhooks und OAuth-Apps für Drittanbieter. Ein konkretes Datum nennen wir bewusst noch nicht: die Reihenfolge orientiert sich an dem, was die ersten Beta-Tester tatsächlich brauchen.

Für wen ist die API gedacht?

• Händler mit eigenem Shop, der nicht über einen der Standard-Connectoren läuft.
• Agenturen, die mehrere Kundenshops gebündelt reporten wollen.
• Teams, die eigene Dashboards oder BI-Auswertungen außerhalb von FloOne bauen.
• Steuerkanzleien, die Mandantendaten maschinell ins eigene Kanzlei-Tool ziehen wollen.