Flic Platform API

Vollständige API-Dokumentation und Entwickler-Knowledgebase für die Flic Logistik- und Workflow-Plattform.

API Version 1.0 • Aktualisiert: 31.12.2024

Übersicht

Die Flic Platform ist eine moderne Logistik- und Workflow-Management-Lösung, die aus mehreren Komponenten besteht:

🎛️ Flic Cockpit

Web-basiertes Kontrollzentrum für Disponenten mit Radar-Ansicht, Board, Inbox und Hub-Verwaltung.

📱 Flic Pilot

Mobile App für Fahrer mit Auftragsübersicht, Navigation, Foto-Dokumentation und Unterschriften-Erfassung.

🔧 Workflow Designer

Visueller Editor zum Erstellen von Auftragsmasken mit Drag & Drop und KI-Unterstützung.

🤖 Commander (KI)

KI-gestützter Assistent für Suche, Workflow-Erstellung und Dokument-Analyse.

Base URL

https://app.flicono.ai/api/v1

ℹ️

Alle API-Endpunkte erfordern HTTPS. HTTP-Anfragen werden automatisch auf HTTPS umgeleitet.

Architektur

Die Flic Platform basiert auf einer modernen Microservices-Architektur mit klarer Trennung zwischen Frontend, Backend und Datenbank.

┌─────────────────────────────────────────────────────────────────────────────┐ │ FLIC PLATFORM │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Flic Cockpit │ │ Flic Pilot │ │ Customer │ │ External │ │ │ │ (React) │ │ (React Nat.) │ │ Portal │ │ Apps │ │ │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ │ │ │ │ │ │ │ └─────────────────┴─────────────────┴─────────────────┘ │ │ │ │ │ ┌─────────▼─────────┐ │ │ │ REST API (v1) │ │ │ │ Laravel Backend │ │ │ └─────────┬─────────┘ │ │ │ │ │ ┌──────────────────────────┼──────────────────────────┐ │ │ │ │ │ │ │ ┌──────▼──────┐ ┌───────────────▼───────────────┐ ┌───────▼───────┐ │ │ │ MySQL │ │ Services Layer │ │ Storage │ │ │ │ Database │ │ • Auth (Sanctum + Passkeys) │ │ (S3/Local) │ │ │ │ │ │ • Workflow Engine │ │ │ │ │ │ • Users │ │ • Telemetry Processing │ │ • Documents │ │ │ │ • Flows │ │ • AI Integration (Gemini) │ │ • Photos │ │ │ │ • Hub │ │ • Notification Service │ │ • Exports │ │ │ │ • Vehicles │ │ │ │ │ │ │ └─────────────┘ └───────────────────────────────┘ └───────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘

Technologie-Stack

Komponente	Technologie	Version
Backend	Laravel (PHP)	11.x
Frontend	React + Mantine UI	18.x / 7.x
Mobile	React Native + Expo	51.x
Datenbank	MySQL	8.x
Auth	Laravel Sanctum + WebAuthn	-
KI	Google Gemini API	2.0

Authentifizierung

Die API verwendet Bearer Token Authentication via Laravel Sanctum. Tokens werden beim Login ausgestellt und müssen bei jedem Request im Authorization-Header mitgesendet werden.

Token erhalten

POST /api/v1/auth/login Benutzer authentifizieren

Request Body

Parameter	Typ	Beschreibung
email*	string	E-Mail-Adresse des Benutzers
password*	string	Passwort
device_name(optional)	string	Gerätename für Token-Identifikation

Response

{
  "success": true,
  "token": "1|abc123xyz...",
  "user": {
    "id": 1,
    "name": "Max Mustermann",
    "email": "max@example.com",
    "role": "admin"
  }
}

Token verwenden

Fügen Sie den Token bei jedem API-Request im Authorization-Header hinzu:

Authorization: Bearer 1|abc123xyz...

Passkey-Authentifizierung (WebAuthn)

Die Plattform unterstützt auch passwortlose Authentifizierung via WebAuthn/Passkeys:

POST /api/v1/auth/passkey/challenge Passkey-Challenge anfordern

Fordert eine WebAuthn-Challenge für die Passkey-Authentifizierung an.

POST /api/v1/auth/passkey/verify Passkey verifizieren

Verifiziert die Passkey-Signatur und gibt einen Auth-Token zurück.

Schnellstart

Hier ein einfaches Beispiel, um mit der API zu starten:

# 1. Login und Token erhalten
curl -X POST https://app.flicono.ai/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "secret"}'

# 2. Aufträge abrufen
curl https://app.flicono.ai/api/v1/flows \
  -H "Authorization: Bearer YOUR_TOKEN"

# 3. Neuen Auftrag erstellen
curl -X POST https://app.flicono.ai/api/v1/drafts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "transport-standard",
    "form_data": {
      "customer_name": "Musterfirma GmbH",
      "pickup_address": "Musterstraße 1, 12345 Berlin",
      "delivery_address": "Beispielweg 2, 54321 München"
    }
  }'

// Flic API Client
const API_BASE = 'https://app.flicono.ai/api/v1';

// Login
const login = async (email, password) => {
  const response = await fetch(`${API_BASE}/auth/login`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email, password })
  });
  return response.json();
};

// Aufträge abrufen
const getFlows = async (token) => {
  const response = await fetch(`${API_BASE}/flows`, {
    headers: { 'Authorization': `Bearer ${token}` }
  });
  return response.json();
};

// Verwendung
const { token } = await login('user@example.com', 'secret');
const flows = await getFlows(token);
console.log(flows);

<?php
// Flic API Client für PHP/Laravel

$apiBase = 'https://app.flicono.ai/api/v1';

// Login
$response = Http::post("$apiBase/auth/login", [
    'email' => 'user@example.com',
    'password' => 'secret'
]);

$token = $response->json('token');

// Aufträge abrufen
$flows = Http::withToken($token)
    ->get("$apiBase/flows")
    ->json();

// Neuen Auftrag erstellen
$draft = Http::withToken($token)
    ->post("$apiBase/drafts", [
        'template_id' => 'transport-standard',
        'form_data' => [
            'customer_name' => 'Musterfirma GmbH',
            'pickup_address' => 'Musterstraße 1, 12345 Berlin'
        ]
    ])
    ->json();

import requests

API_BASE = 'https://app.flicono.ai/api/v1'

# Login
response = requests.post(f'{API_BASE}/auth/login', json={
    'email': 'user@example.com',
    'password': 'secret'
})
token = response.json()['token']

# Headers für authentifizierte Requests
headers = {'Authorization': f'Bearer {token}'}

# Aufträge abrufen
flows = requests.get(f'{API_BASE}/flows', headers=headers).json()

# Neuen Auftrag erstellen
draft = requests.post(f'{API_BASE}/drafts', headers=headers, json={
    'template_id': 'transport-standard',
    'form_data': {
        'customer_name': 'Musterfirma GmbH',
        'pickup_address': 'Musterstraße 1, 12345 Berlin'
    }
}).json()

Hub (XRM) API

Der Hub ist das zentrale Adressbuch der Plattform - ein erweitertes CRM/XRM für Kunden, Partner, Fahrer und Standorte.

GET /api/v1/hub/entities Alle Entitäten abrufen

Query Parameter

Parameter	Typ	Beschreibung
search	string	Volltextsuche über Name, E-Mail, etc.
role	string	Filter nach Rolle (customer, driver, partner)
type	string	Filter nach Typ (person, organization)
limit	integer	Anzahl Ergebnisse (default: 50)
offset	integer	Offset für Pagination

Response

{
  "success": true,
  "data": [
    {
      "id": "uuid-123",
      "type": "organization",
      "name": "Musterfirma GmbH",
      "email": "info@musterfirma.de",
      "phone": "+49 30 12345678",
      "roles": ["customer"],
      "locations": [
        {
          "id": "loc-1",
          "label": "Hauptsitz",
          "address": "Musterstraße 1, 12345 Berlin",
          "lat": 52.520008,
          "lng": 13.404954
        }
      ],
      "custom_fields": {},
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 150,
  "limit": 50,
  "offset": 0
}

POST /api/v1/hub/entities Neue Entität erstellen

Request Body

Parameter	Typ	Beschreibung
type*	string	"person" oder "organization"
name*	string	Name der Person/Organisation
email	string	E-Mail-Adresse
phone	string	Telefonnummer
roles	array	Rollen: ["customer", "driver", "partner"]
locations	array	Standorte mit Adresse und Koordinaten

GET /api/v1/hub/entities/{id} Einzelne Entität abrufen

Gibt alle Details einer Entität zurück, inklusive Aktivitäten-Timeline.

PUT /api/v1/hub/entities/{id} Entität aktualisieren

Aktualisiert die Daten einer bestehenden Entität.

DELETE /api/v1/hub/entities/{id} Entität löschen

Löscht eine Entität (Soft-Delete).

Hub Rollen

Entitäten können verschiedene Rollen haben, die ihr Verhalten in der Plattform bestimmen:

Rolle	Slug	Beschreibung
Kunde	`customer`	Auftraggeber, kann Aufträge erteilen
Fahrer	`driver`	Führt Aufträge aus, nutzt Pilot-App
Partner	`partner`	Subunternehmer, erhält weitergeleitete Aufträge
Lieferant	`supplier`	Warenlieferant

Flows API

Flows sind aktive Aufträge, die sich in Bearbeitung befinden. Sie werden aus Drafts erstellt und durchlaufen verschiedene Status.

GET /api/v1/flows Alle aktiven Flows abrufen

Query Parameter

Parameter	Typ	Beschreibung
status	string	pending, in_progress, completed, cancelled
driver_id	uuid	Filter nach zugewiesenem Fahrer
date_from	date	Startdatum (YYYY-MM-DD)
date_to	date	Enddatum (YYYY-MM-DD)

Response

{
  "success": true,
  "data": [
    {
      "id": "flow-uuid-123",
      "status": "in_progress",
      "template_id": "transport-standard",
      "assigned_driver": {
        "id": "driver-1",
        "name": "Max Fahrer"
      },
      "stops": [
        {
          "type": "pickup",
          "address": "Musterstraße 1, Berlin",
          "scheduled_at": "2024-12-31T09:00:00Z",
          "completed_at": null
        },
        {
          "type": "delivery",
          "address": "Beispielweg 2, München",
          "scheduled_at": "2024-12-31T15:00:00Z",
          "completed_at": null
        }
      ],
      "values": {
        "customer_name": "Musterfirma GmbH",
        "packages": 3
      },
      "created_at": "2024-12-30T14:00:00Z"
    }
  ]
}

POST /api/v1/flows Neuen Flow erstellen

Erstellt einen neuen Flow direkt (ohne Draft-Zwischenschritt).

POST /api/v1/flows/{id}/start Flow starten

Startet einen Flow und setzt den Status auf "in_progress".

POST /api/v1/flows/{id}/complete Flow abschließen

Markiert einen Flow als abgeschlossen.

POST /api/v1/flows/{id}/cancel Flow stornieren

Storniert einen Flow mit optionalem Grund.

Drafts API

Drafts sind Auftragsentwürfe, die noch nicht aktiviert wurden. Sie können aus dem Inbox bearbeitet und bestätigt werden.

GET /api/v1/drafts Alle Drafts abrufen

Response

{
  "success": true,
  "count": 5,
  "drafts": [
    {
      "id": "draft-uuid-123",
      "status": "draft",
      "template_id": "transport-standard",
      "template_name": "Transport-Auftrag",
      "form_data": {
        "customer_name": "Musterfirma GmbH",
        "pickup_address": "Berlin",
        "delivery_address": "München"
      },
      "source": "manual",
      "created_at": "2024-12-30T10:00:00Z"
    }
  ]
}

POST /api/v1/drafts Neuen Draft erstellen

Request Body

Parameter	Typ	Beschreibung
template_id	string	ID der Workflow-Vorlage
template_name	string	Name der Vorlage
form_data*	object	Formulardaten gemäß Template-Schema
source	string	Quelle: manual, email, api, ai
status	string	draft, confirmed

POST /api/v1/draft/{uuid}/finalize Draft finalisieren

Wandelt einen Draft in einen aktiven Flow um.

Vehicles API

Verwaltung der Fahrzeugflotte mit Telemetrie-Daten und Fahrer-Zuweisungen.

GET /api/v1/vehicles Alle Fahrzeuge abrufen

Response

{
  "success": true,
  "data": [
    {
      "id": "vehicle-1",
      "license_plate": "B-FL 1234",
      "type": "van",
      "brand": "Mercedes",
      "model": "Sprinter",
      "status": "active",
      "current_driver": {
        "id": "driver-1",
        "name": "Max Fahrer"
      },
      "last_position": {
        "lat": 52.520008,
        "lng": 13.404954,
        "timestamp": "2024-12-31T10:30:00Z"
      }
    }
  ]
}

POST /api/v1/vehicles/{id}/assign-driver Fahrer zuweisen

Request Body

{
  "driver_id": "driver-uuid"
}

Drivers API

Fahrer-Verwaltung und -Authentifizierung für die Pilot-App.

GET /api/v1/drivers Alle Fahrer abrufen

Listet alle registrierten Fahrer mit Status und zugewiesenem Fahrzeug.

GET /api/v1/drivers/free Verfügbare Fahrer

Listet alle Fahrer, die aktuell keinem Auftrag zugewiesen sind.

POST /api/v1/driver/location Position melden

Meldet die aktuelle GPS-Position des Fahrers (von der Pilot-App).

Request Body

{
  "lat": 52.520008,
  "lng": 13.404954,
  "accuracy": 10,
  "speed": 45,
  "heading": 180
}

Telemetry API

Echtzeit-Positionsdaten und Fahrzeug-Tracking.

GET /api/v1/telemetry/positions Aktuelle Positionen

Gibt die aktuellen Positionen aller aktiven Fahrzeuge zurück.

GET /api/v1/telemetry/history/{vehicleId} Positionshistorie

Gibt die Positionshistorie eines Fahrzeugs für einen Zeitraum zurück.

GET /api/v1/live/stream Live-Stream (SSE)

Server-Sent Events Stream für Echtzeit-Updates.

Workflow Templates API

Verwaltung von Auftragsmasken und Workflow-Definitionen.

GET /api/v1/templates Alle Templates abrufen

Response

{
  "success": true,
  "data": [
    {
      "id": "template-1",
      "name": "Transport-Auftrag",
      "description": "Standard-Vorlage für Transportaufträge",
      "is_default": true,
      "version": 3,
      "blueprint": { ... },
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-12-30T15:00:00Z"
    }
  ]
}

GET /api/v1/templates/available-fields Verfügbare Feldtypen

Listet alle verfügbaren Feldtypen für den Workflow Designer.

POST /api/v1/templates/{id}/publish Template veröffentlichen

Veröffentlicht eine neue Version des Templates.

Workflow Blueprint Schema v1.0

Das Workflow Blueprint Schema definiert das Schema für Workflow-Templates. Es beschreibt, welche Felder ein Auftrag haben kann und wie sie dargestellt werden.

Blueprint-Struktur

{
  "version": "1.0",
  "name": "Transport-Auftrag",
  "description": "Standard-Vorlage für Transportaufträge",
  "roles": {
    "cockpit": {
      "fields": [
        {
          "key": "customer_name",
          "type": "text",
          "label": "Kundenname",
          "required": true,
          "editable": true,
          "visible": true
        },
        {
          "key": "pickup_address",
          "type": "address",
          "label": "Abholadresse",
          "required": true
        },
        {
          "key": "delivery_address",
          "type": "address",
          "label": "Lieferadresse",
          "required": true
        }
      ]
    },
    "pilot": {
      "fields": [
        {
          "key": "signature",
          "type": "signature",
          "label": "Unterschrift Empfänger",
          "required": true
        },
        {
          "key": "delivery_photo",
          "type": "photo",
          "label": "Abliefernachweis"
        }
      ]
    }
  }
}

Feldtypen

Verfügbare Feldtypen für Workflow-Templates:

Typ	Beschreibung	Optionen
`text`	Einzeiliges Textfeld	placeholder, maxLength
`textarea`	Mehrzeiliges Textfeld	placeholder, rows
`number`	Numerisches Feld	min, max, step
`select`	Dropdown-Auswahl	options[]
`multiselect`	Mehrfachauswahl	options[]
`date`	Datumsauswahl	minDate, maxDate
`time_range`	Zeitfenster (von-bis)	-
`datetime`	Datum und Uhrzeit	-
`boolean`	Ja/Nein Checkbox	-
`address`	Adresse mit Geocoding	-
`phone`	Telefonnummer	-
`email`	E-Mail-Adresse	-
`photo`	Foto-Upload	maxCount, quality
`signature`	Unterschrift-Pad	-
`barcode`	Barcode-Scanner	formats[]
`package_capture`	Packstück-Erfassung	allowMultiple
`contact`	Hub-Kontakt-Auswahl	roles[]
`location`	GPS-Position	-

KI-Integration

Die Plattform nutzt Google Gemini für verschiedene KI-Funktionen.

POST /api/v1/document/process Dokument analysieren

Analysiert ein hochgeladenes Dokument (PDF, Bild) und extrahiert Auftragsdaten.

Request (multipart/form-data)

Parameter	Typ	Beschreibung
file*	file	PDF oder Bild-Datei
template_id	string	Ziel-Template für Extraktion

Response

{
  "success": true,
  "document_type": "delivery_note",
  "confidence": 0.92,
  "extracted_fields": {
    "customer_name": "Musterfirma GmbH",
    "pickup_address": "Musterstraße 1, 12345 Berlin",
    "delivery_address": "Beispielweg 2, 54321 München",
    "packages": 3,
    "weight": "150 kg"
  },
  "suggested_template": "transport-standard"
}

POST /api/v1/fleet/settings/blueprint/mutate KI-Workflow-Mutation

Ändert ein Workflow-Template basierend auf natürlichsprachlichen Anweisungen.

Request Body

{
  "instruction": "Füge ein Pflichtfeld für Temperatur hinzu, nur sichtbar für Fahrer"
}

Kundenportal API

Endpunkte für das Kunden-Self-Service-Portal.

POST /api/v1/customer/auth/login Kunden-Login

Authentifiziert einen Kunden für das Self-Service-Portal.

GET /api/v1/customer/orders Eigene Aufträge

Listet alle Aufträge des eingeloggten Kunden.

POST /api/v1/customer/orders Auftrag erstellen

Erstellt einen neuen Auftrag über das Kundenportal.

Datenmodelle

Übersicht der wichtigsten Datenbank-Entitäten:

User

Feld	Typ	Beschreibung
id	uuid	Primärschlüssel
name	string	Vollständiger Name
email	string	E-Mail (unique)
role	enum	admin, dispatcher, viewer
fleet_id	uuid	Zugehörige Flotte

HubEntity

Feld	Typ	Beschreibung
id	uuid	Primärschlüssel
type	enum	person, organization
name	string	Name
email	string	E-Mail
phone	string	Telefon
custom_fields	json	Rollenspezifische Felder

Flow

Feld	Typ	Beschreibung
id	uuid	Primärschlüssel
status	enum	pending, in_progress, completed, cancelled
template_id	uuid	Workflow-Template
assigned_driver_id	uuid	Zugewiesener Fahrer
values	json	Formulardaten

Vehicle

Feld	Typ	Beschreibung
id	uuid	Primärschlüssel
license_plate	string	Kennzeichen
type	enum	car, van, truck
brand	string	Marke
model	string	Modell
status	enum	active, maintenance, inactive

Fehlercodes

Standard HTTP-Statuscodes und API-spezifische Fehlermeldungen:

Code	Bedeutung	Beschreibung
200	OK	Anfrage erfolgreich
201	Created	Ressource erstellt
400	Bad Request	Ungültige Anfrage
401	Unauthorized	Nicht authentifiziert
403	Forbidden	Keine Berechtigung
404	Not Found	Ressource nicht gefunden
405	Method Not Allowed	HTTP-Methode nicht erlaubt
422	Unprocessable Entity	Validierungsfehler
429	Too Many Requests	Rate Limit erreicht
500	Server Error	Interner Serverfehler

Fehler-Response Format

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Die Eingabe ist ungültig.",
    "details": {
      "email": ["Das E-Mail-Format ist ungültig."],
      "password": ["Das Passwort muss mindestens 8 Zeichen haben."]
    }
  }
}

Rate Limits

Die API hat folgende Ratenbegrenzungen:

Endpunkt-Typ	Limit	Zeitfenster
Standard-Endpunkte	60 Requests	pro Minute
Auth-Endpunkte	10 Requests	pro Minute
Upload-Endpunkte	20 Requests	pro Minute
KI-Endpunkte	10 Requests	pro Minute

Bei Überschreitung wird ein 429 Too Many Requests zurückgegeben. Die Response-Header enthalten:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1704067200

Changelog

v1.0.0 - 31.12.2024

Vollständige API-Dokumentation erstellt
Hub (XRM) API dokumentiert
Flows & Drafts API dokumentiert
Fleet Management API dokumentiert
Workflow Templates & Workflow Blueprint Schema dokumentiert
KI-Integration dokumentiert
Kundenportal API dokumentiert
Code-Beispiele in cURL, JavaScript, PHP, Python