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

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

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

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

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

Der Parametername für die Authentifizierung ist: PHONE_FONIO_INCOMING_REQUEST_HASH

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:

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

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:

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:

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

+491234567890
+49 123 4567890

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

# 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"
    }
  }'

<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> 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>

* 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

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

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

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