===== Fonio API Dokumentation =====

Willkommen bei der Fonio API für ET360. Diese Dokumentation beschreibt, wie Sie als Kunde über Fonio mit unserem Server kommunizieren können.

== Einführung ==

Die Fonio API ermöglicht es Ihnen, als KI-Sprachassistent mit unserem ET360-System zu interagieren. Sie können:

* **Fallinformationen abfragen** - Holen Sie sich Details zu Fahrzeugen über das Kennzeichen
* **Anrufdaten übermitteln** - Senden Sie Transkripte und Kontextdaten von Telefonkonversationen
* **Fallzuordnung durchführen** - Verknüpfen Sie Anrufe mit bestehenden Fällen im System

== Authentifizierung ==

Alle API-Endpunkte verwenden **Basic Authentication**. Sie benötigen einen API-Hash, der Ihnen von ET360 bereitgestellt wurde.

=== Header-Informationen ===

Fügen Sie diesen Header zu allen Ihren API-Anfragen hinzu:

<code>
Authorization: Basic <Ihr-API-Hash>
Content-Type: application/json
</code>

Der Parametername für die Authentifizierung ist: ''PHONE_FONIO_INCOMING_REQUEST_HASH''

== API-Endpunkte ==

=== 1. Fallinformationen nach Kennzeichen abfragen ===

**Endpunkt:** ''GET /ai/fonio/case-information-by-license-plate/{kennzeichen}''

**Beschreibung:** Rufen Sie Informationen zu einem Fall ab, indem Sie das Fahrzeugkennzeichen angeben.

**URL-Parameter:**

| Parameter | Typ | Beschreibung | Beispiel |
| kennzeichen | String | Das deutsche Kfz-Kennzeichen (mit oder ohne Sonderzeichen) | MTK-C-72, MTK C 72, MTK:C:72 |

**Beispielanfrage:**
<url>GET https://your-server.com/ai/fonio/case-information-by-license-plate/MTK-C-72</url>

**Beispielantwort:**
<json>
{
  "type": "object",
  "properties": {
    "LicensePlate": {
      "type": "string",
      "description": "Nummernschild des Fahrzeuges",
      "value": "MTK C 72"
    },
    "Location": {
      "type": "string",
      "description": "Standort des Fahrzeugs",
      "value": "Frankfurt am Main"
    },
    "OpeningHours": {
      "type": "string",
      "description": "Öffnungszeiten der Filiale",
      "value": "Mo-Fr 08:00-18:00"
    },
    "Price": {
      "type": "string",
      "description": "Preis für den Service",
      "value": "€150,00"
    },
    "DriverName": {
      "type": "string",
      "description": "Name des zugewiesenen Fahrers",
      "value": "Max Mustermann"
    },
    "DriverETA": {
      "type": "string",
      "description": "Geschätzte Ankunftszeit des Fahrers",
      "value": "15 Minuten"
    },
    "DriverDistance": {
      "type": "string",
      "description": "Entfernung des Fahrers zum Fahrzeug",
      "value": "5 km"
    }
  }
}
</json>

**Hinweise:**
* Das Kennzeichen kann mit oder ohne Sonderzeichen (-, :, Leerzeichen) übermittelt werden
* Die API normalisiert das Kennzeichen automatisch
* Wenn kein Fall gefunden wird, wird ''null'' zurückgegeben

=== 2. Anrufdaten übermitteln ===

**Endpunkt:** ''PATCH /ai/fonio/cases-by-phonenumber''

**Beschreibung:** Senden Sie Transkripte und Metadaten von Telefonkonversationen. Das System versucht automatisch, den Anruf mit einem bestehenden Fall über die Telefonnummer zu verknüpfen.

**HTTP-Methode:** PATCH

**Content-Type:** application/json

**Anfrage-Body:**

<json>
{
  "summary": "Kurze Zusammenfassung des Anrufs",
  "fromNumber": "+491234567890",
  "toNumber": "+499876543210",
  "direction": "inbound",
  "duration": 120,
  "startTimestamp": "2024-01-15T10:30:00Z",
  "endTimestamp": "2024-01-15T10:32:00Z",
  "audioLink": "https://example.com/audio-recording.mp3",
  "transcript": [
    {
      "id": "msg-001",
      "index": 0,
      "role": "user",
      "content": "Guten Tag, ich benötige Hilfe mit meinem Fahrzeug",
      "createdAt": "2024-01-15T10:30:15Z"
    },
    {
      "id": "msg-002",
      "index": 1,
      "role": "assistant",
      "content": "Gerne helfe ich Ihnen. Was ist Ihr Fahrzeugkennzeichen?",
      "createdAt": "2024-01-15T10:30:20Z"
    },
    {
      "id": "msg-003",
      "index": 2,
      "role": "user",
      "content": "Das Kennzeichen ist MTK C 72",
      "createdAt": "2024-01-15T10:30:35Z"
    }
  ],
  "context": {
    "Name": "Max Mustermann",
    "LicensePlate": "MTK C 72",
    "Summary": "Kunde fordert Abschleppservice für beschädigtes Fahrzeug"
  },
  "disconnectReason": "Call completed successfully"
}
</json>

**Feldbeschreibungen:**

| Feld | Typ | Erforderlich | Beschreibung |
| summary | String | Nein | KI-generierte Zusammenfassung des Anrufs |
| fromNumber | String | Ja | Telefonnummer des Anrufers (E.164-Format) |
| toNumber | String | Ja | Telefonnummer des Empfängers (E.164-Format) |
| direction | String | Ja | "inbound" (eingehend) oder "outbound" (ausgehend) |
| duration | Integer | Ja | Anrufdauer in Sekunden |
| startTimestamp | String | Ja | Anrufstartzeit (ISO 8601 Format) |
| endTimestamp | String | Ja | Anrufendzeit (ISO 8601 Format) |
| audioLink | String | Nein | URL zur Audioaufnahme |
| transcript | Array | Ja | Zeitgestempelte Konversationstranskripte |
| transcript[].id | String | Ja | Eindeutige Nachrichten-ID |
| transcript[].index | Integer | Ja | Nachrichten-Sequenznummer |
| transcript[].role | String | Ja | "user" oder "assistant" |
| transcript[].content | String | Ja | Nachrichtentext |
| transcript[].createdAt | String | Ja | Zeitstempel (ISO 8601) |
| context | Object | Nein | Extrahierte strukturierte Daten |
| context.Name | String | Nein | Kundenname |
| context.LicensePlate | String | Nein | Fahrzeugkennzeichen |
| context.Summary | String | Nein | Zusammenfassung |
| disconnectReason | String | Nein | Grund für Anrufbeendigung |

**Beispielantwort:**

Bei erfolgreicher Verarbeitung wird die Anfrage akzeptiert (HTTP 200). Das System:
1. Sucht nach einem passenden Fall basierend auf der Telefonnummer
2. Verknüpft die Anrufdaten mit dem gefundenen Fall
3. Speichert Transkript und Kontextinformationen

**Fehlerantworten:**

| HTTP-Status | Beschreibung |
| 401 | Authentifizierung fehlgeschlagen - Überprüfen Sie Ihren API-Hash |
| 400 | Ungültiges Anfrageformat - Überprüfen Sie die JSON-Struktur |
| 404 | Kein passender Fall gefunden - Die Telefonnummer ist nicht im System |
| 500 | Serverfehler - Bitte kontaktieren Sie den Support |

== Telefonnummern-Formatierung ==

Alle Telefonnummern sollten im **E.164-Format** übermittelt werden:

<code>
+491234567890
+49 123 4567890
</code>

Das System akzeptiert verschiedene Formate und normalisiert sie automatisch:
* ''+491234567890'' ✓
* ''+49 123 4567890'' ✓
* ''0123 4567890'' ✓ (wird automatisch konvertiert)

== Beispiel-Implementierung ==

=== cURL Beispiel ===

<code>
# Fallinformationen abfragen
curl -X GET \
  https://your-server.com/ai/fonio/case-information-by-license-plate/MTK-C-72 \
  -H "Authorization: Basic your-api-hash" \
  -H "Content-Type: application/json"

# Anrufdaten übermitteln
curl -X PATCH \
  https://your-server.com/ai/fonio/cases-by-phonenumber \
  -H "Authorization: Basic your-api-hash" \
  -H "Content-Type: application/json" \
  -d '{
    "fromNumber": "+491234567890",
    "toNumber": "+499876543210",
    "direction": "inbound",
    "duration": 120,
    "startTimestamp": "2024-01-15T10:30:00Z",
    "endTimestamp": "2024-01-15T10:32:00Z",
    "transcript": [
      {
        "id": "msg-001",
        "index": 0,
        "role": "user",
        "content": "Ich brauche Hilfe",
        "createdAt": "2024-01-15T10:30:15Z"
      }
    ],
    "context": {
      "Name": "Max Mustermann",
      "LicensePlate": "MTK C 72"
    }
  }'
</code>

=== Python Beispiel ===

<python>
import requests
import json

# Konfiguration
BASE_URL = "https://your-server.com"
API_HASH = "your-api-hash"

headers = {
    "Authorization": f"Basic {API_HASH}",
    "Content-Type": "application/json"
}

# Fallinformationen abfragen
def get_case_by_license_plate(license_plate):
    url = f"{BASE_URL}/ai/fonio/case-information-by-license-plate/{license_plate}"
    response = requests.get(url, headers=headers)
    return response.json()

# Anrufdaten übermitteln
def submit_call_data(call_data):
    url = f"{BASE_URL}/ai/fonio/cases-by-phonenumber"
    response = requests.patch(url, headers=headers, json=call_data)
    return response.status_code

# Beispielverwendung
if __name__ == "__main__":
    # Fall abfragen
    result = get_case_by_license_plate("MTK-C-72")
    print(json.dumps(result, indent=2))
    
    # Anrufdaten senden
    call_data = {
        "fromNumber": "+491234567890",
        "toNumber": "+499876543210",
        "direction": "inbound",
        "duration": 120,
        "startTimestamp": "2024-01-15T10:30:00Z",
        "endTimestamp": "2024-01-15T10:32:00Z",
        "transcript": [
            {
                "id": "msg-001",
                "index": 0,
                "role": "user",
                "content": "Guten Tag",
                "createdAt": "2024-01-15T10:30:15Z"
            }
        ],
        "context": {
            "Name": "Max Mustermann",
            "LicensePlate": "MTK C 72"
        }
    }
    
    status = submit_call_data(call_data)
    print(f"Status: {status}")
</python>

=== JavaScript/Node.js Beispiel ===

<javascript>
const axios = require('axios');

const BASE_URL = 'https://your-server.com';
const API_HASH = 'your-api-hash';

const headers = {
    'Authorization': `Basic ${API_HASH}`,
    'Content-Type': 'application/json'
};

// Fallinformationen abfragen
async function getCaseByLicensePlate(licensePlate) {
    const response = await axios.get(
        `${BASE_URL}/ai/fonio/case-information-by-license-plate/${licensePlate}`,
        { headers }
    );
    return response.data;
}

// Anrufdaten übermitteln
async function submitCallData(callData) {
    const response = await axios.patch(
        `${BASE_URL}/ai/fonio/cases-by-phonenumber`,
        callData,
        { headers }
    );
    return response.status;
}

// Beispielverwendung
(async () => {
    try {
        // Fall abfragen
        const result = await getCaseByLicensePlate('MTK-C-72');
        console.log(JSON.stringify(result, null, 2));
        
        // Anrufdaten senden
        const callData = {
            fromNumber: '+491234567890',
            toNumber: '+499876543210',
            direction: 'inbound',
            duration: 120,
            startTimestamp: '2024-01-15T10:30:00Z',
            endTimestamp: '2024-01-15T10:32:00Z',
            transcript: [
                {
                    id: 'msg-001',
                    index: 0,
                    role: 'user',
                    content: 'Guten Tag',
                    createdAt: '2024-01-15T10:30:15Z'
                }
            ],
            context: {
                Name: 'Max Mustermann',
                LicensePlate: 'MTK C 72'
            }
        };
        
        const status = await submitCallData(callData);
        console.log(`Status: ${status}`);
    } catch (error) {
        console.error('Fehler:', error.response?.data || error.message);
    }
})();
</javascript>

== Best Practices ==

=== Datenqualität ===

* **Transkripte:** Senden Sie Transkripte so schnell wie möglich nach Anrufende
* **Zeitstempel:** Verwenden Sie immer UTC-Zeit im ISO 8601 Format
* **Telefonnummern:** Formatieren Sie Nummern im E.164-Standard
* **Kontextdaten:** Extrahieren Sie relevante Informationen (Name, Kennzeichen) für bessere Fallzuordnung

=== Fehlerbehandlung ===

* Implementieren Sie Retry-Logik bei HTTP 500 Fehlern
* Protokollieren Sie alle API-Antworten zur Fehleranalyse
* Validieren Sie Ihre Anfragen vor dem Senden

=== Sicherheit ===

* Bewahren Sie Ihren API-Hash sicher auf
* Verwenden Sie HTTPS für alle API-Anfragen
* Rotieren Sie API-Hashes regelmäßig

== Fehlerbehebung ==

=== Häufige Probleme ===

**401 Unauthorized**
* Überprüfen Sie, ob der API-Hash korrekt ist
* Stellen Sie sicher, dass Sie "Basic " vor dem Hash verwenden

**400 Bad Request**
* Validieren Sie Ihre JSON-Struktur
* Stellen Sie sicher, dass alle erforderlichen Felder vorhanden sind
* Überprüfen Sie das Datentypen (Strings, Integers, Arrays)

**404 Not Found**
* Die Telefonnummer existiert nicht im System
* Überprüfen Sie das Telefonnummernformat
* Kontaktieren Sie den Kunden, um die richtige Nummer zu bestätigen

**500 Internal Server Error**
* Temporärer Serverfehler
* Versuchen Sie es später erneut
* Bei anhaltenden Problemen: Kontaktieren Sie den ET360-Support