API

Die API-Dokumentation bietet Ihnen alle notwendigen Informationen für die programmatische Integration von EASE-AI in Ihre Anwendungen. Hier finden Sie detaillierte Endpunktbeschreibungen, Authentifizierungsmethoden und Codebeispiele. Nutzen Sie diesen Bereich, wenn Sie EASE-AI in Ihre bestehenden Systeme integrieren oder automatisierte Workflows erstellen möchten.

Authentifizierung

Die Authentifizierung ist der erste Schritt für den sicheren API-Zugriff. Erfahren Sie, wie Sie API-Token generieren, verwalten und sicher einsetzen. Eine korrekte Authentifizierung ist grundlegend für alle API-Operationen.

API-Token-Authentifizierung

Die API-Token-Authentifizierung bietet eine sichere Methode für den programmatischen Zugriff. Jeder Token gewährt spezifische Zugriffsrechte und kann bei Bedarf widerrufen werden. Die Token-basierte Authentifizierung ist die empfohlene Methode für API-Zugriffe.

API-Endpunkte

Die API-Endpunkte bilden die Schnittstelle zwischen Ihrer Anwendung und EASE-AI. Jeder Endpunkt bietet spezifische Funktionalitäten für die Dokumentenverwaltung. Die Endpunkte sind RESTful und folgen modernen API-Design-Prinzipien.

Upload-Endpunkt

Der Upload-Endpunkt ermöglicht das Hochladen neuer Dokumente in das System. Sie können einzelne Dateien im PDF-, Text- oder Bildformat hochladen und optional OCR, Kategorisierung und Entitätsextraktion aktivieren. Die Antwort enthält eine Dokumenten-ID für weitere Operationen.

Anfrage:

# Form data with:
- file: The file to upload (multipart/form-data)
- extraction_options: ["ocr", "category", "entities"]

Antwort:

{
    "message": "Dokument erfolgreich zur Verarbeitung eingereiht",
    "document_id": 123,
    "status": 200
}

Update-Endpunkt

Der Update-Endpunkt ermöglicht die Änderung von Dokumentenmetadaten wie Name, Kategorie, Tags und Entitäten. Sie können einzelne Felder oder mehrere Eigenschaften gleichzeitig aktualisieren. Die Änderungen werden sofort im System wirksam.

Anfrage:

{
    "id": 123,
    "name": "neuer_name.pdf",
    "category": "rechnungen",
    "entities": "{\"entität1\": [\"wert1\", \"wert2\"], \"entität2\": [\"wert1\"]}",
    "tag": "wichtig"
}

Antwort:

{
    "message": "Dokument erfolgreich aktualisiert",
    "document_id": 123,
    "status": 200
}

Get-Endpunkt

Der Get-Endpunkt liefert detaillierte Informationen zu einem spezifischen Dokument. Die Antwort enthält den Dokumentinhalt, Metadaten, Kategorisierung und extrahierte Entitäten. Ideal für die Anzeige von Dokumentdetails oder die Integration in andere Systeme.

Antwort:

{
    "name": "beispiel.pdf",
    "content": "dokument_text_inhalt",
    "category": "rechnungen",
    "entities": {"entität1": ["wert1", "wert2"]},
    "document_id": 123,
    "tag": "wichtig",
    "created_at": "2024-03-21T10:00:00Z",
    "status": 200
}

Delete-Endpunkt

Der Delete-Endpunkt ermöglicht das Entfernen von Dokumenten aus dem System. Sie können einzelne Dokumente anhand ihrer ID löschen. Die Operation entfernt sowohl die Metadaten als auch die gespeicherten Dateien permanent.

Anfrage:

{
    "document_id": 123
}

Antwort:

{
    "message": "Dokument erfolgreich gelöscht",
    "document_id": 123,
    "status": 200
}

Suche-Endpunkt

Der Suche-Endpunkt bietet flexible Suchmöglichkeiten für Ihre Dokumente. Sie können nach Namen, Kategorie, Tags oder Entitäten suchen und die Ergebnisse nach verschiedenen Kriterien sortieren. Die Suche unterstützt Paginierung für große Ergebnislisten.

Anfrage:

# Abfrageparameter:
- search: "Suchbegriff"
- field: "name" (Optionen: name, category, entities, tag, created_at)
- sort_by: "created_at" (Optionen: category, created_at)
- sort_order: "desc" (Optionen: asc, desc)
- limit: 30 (Maximum: 100)

Antwort:

{
    "document_ids": [123, 124, 125],
    "status": 200
}

Codebeispiele

Die Codebeispiele zeigen praktische Implementierungen der API-Endpunkte in Python. Sie demonstrieren die korrekte Verwendung der Authentifizierung, Fehlerbehandlung und alle verfügbaren Operationen. Die Beispiele können als Grundlage für Ihre eigene Integration dienen.

Python-Codebeispiele

import requests
import json
import os

BASE_URL = "https://ease-ai.de"
API_TOKEN = "ihr_api_token_hier"

# Konfigurieren Sie Header mit API-Token
headers = {
    "X-API-Key": f"{API_TOKEN}"
}

# Dokument hochladen
def add_document(file_path, extraction_options):
    with open(file_path, 'rb') as f:
        file = {'file': (os.path.basename(file_path), f, 'application/pdf')}
        response = requests.post(
            f"{BASE_URL}/api/v1/document",
            headers=headers,
            files=file,
            data={"extraction_options": extraction_options}
        )
    return response.json()

# Dokumentendetails abrufen
def get_document(document_id):
    response = requests.get(
        f"{BASE_URL}/api/v1/document",
        params={"document_id": document_id},
        headers=headers
    )
    return response.json()

# Dokument aktualisieren
def update_document(document_id, update_data):
    response = requests.put(
        f"{BASE_URL}/api/v1/document",
        data=update_data,
        headers=headers
    )
    return response.json()

# Dokumente suchen
def search_documents(search, field, sort_by, sort_order, limit):
    response = requests.get(
        f"{BASE_URL}/api/v1/search_documents",
        data={
            "search": search,
            "field": field,
            "sort_by": sort_by,
            "sort_order": sort_order,
            "limit": limit
        },
        headers=headers
    )
    return response.json()

# Dokument löschen
def delete_document(document_id):
    response = requests.delete(
        f"{BASE_URL}/api/v1/document",
        data={"document_id": document_id},
        headers=headers
    )
    return response.json()

# Beispielverwendung
add_response = add_document("beispiel.pdf", ["ocr", "category", "entities"])
document_id = add_response.get("document_id")

get_response = get_document(document_id)

update_data = {
    "id": document_id,
    "name": "aktualisierter_name.pdf",
    "category": "rechnungen",
    "entities": json.dumps({"entität1": ["wert1", "wert2"]})
}
update_response = update_document(document_id, update_data)

search_response = search_documents(
    search="rechnung",
    field="name",
    sort_by="created_at",
    sort_order="desc",
    limit=10
)

delete_response = delete_document(document_id)

Fehlerbehandlung

Die Fehlerbehandlung beschreibt die möglichen Fehlerszenarien und deren Bedeutung. Jeder Fehler enthält einen beschreibenden Text und einen HTTP-Statuscode. Die Dokumentation hilft Ihnen, Fehler zu identifizieren und angemessen zu behandeln.

Fehler-Statuscodes

• 401 - Nicht authentifiziert oder ungültiges API-Token
• 403 - Ungültiges oder abgelaufenes API-Token
• 404 - Dokument nicht gefunden
• 500 - Interner Serverfehler

Fehlerformat:

{
    "error": "Fehlermeldungsbeschreibung",
    "status": status_code
}