🔌 Integrations API

SonicJS Gateway - Unified API für alle externen Dienste
Stand: 2025-12-30 | Version: 0.3.0 | Agent: G100

---

Übersicht

Diese API aggregiert alle externen Integrationen über einen einheitlichen Gateway.

Kategorien

Kategorie	APIs	Endpunkte
💼 Buchhaltung	sevDesk	15
⚡ Energie	evcc, ista	17
📧 Office	MS Graph, Adobe Express	16
🏠 Portale	ImmoScout24, Booking.com, mobile.de	45
📋 Projektmanagement	plane.so	8
🏦 Banking	Targo/PSD2	10
🖨️ Print	FLYERALARM etc.	12
⛓️ Blockchain	Ethereum, Polygon	10

Status-Übersicht

API	Endpunkte	Cache TTL	Rate Limit	Status
sevDesk	15	5-60 min	100/min	✅ Production
evcc	10	10-300s	60/min	✅ Production
MS Graph	8	5-15 min	1000/h	🟡 OAuth Required
ista	7	24h	10/min	🔴 Scraping
plane.so	8	5-30 min	60/min	🟢 Ready
ImmoScout24	25	5-60 min	100/min	🟢 Ready
Booking.com	15	5-30 min	1000/h	🟡 Partner
mobile.de	15	15 min-24h	100/min	🟢 Ready
Adobe Express	8	1-24h	500/Tag	🟡 Dev Account
Banking/PSD2	10	5-15 min	4/Tag	🔴 Consent
Print-on-Demand	12	1-24h	100/h	🟡 B2B
Blockchain RPC	10	15s-5 min	100k/Tag	🟢 Ready

Gesamt: 133 Endpunkte

---

Cache-Strategie

┌─────────────────────────────────────────────────────────────────┐
│  Client Request                                                   │
│      ↓                                                           │
│  ┌─────────────────┐                                             │
│  │  Memory Cache   │ ← L1: 1000 items, LRU, ~1ms                 │
│  │  (Worker-local) │                                             │
│  └────────┬────────┘                                             │
│           ↓ MISS                                                  │
│  ┌─────────────────┐                                             │
│  │  KV/D1 Cache    │ ← L2: Persistent, ~10ms                     │
│  │  (Edge-global)  │                                             │
│  └────────┬────────┘                                             │
│           ↓ MISS                                                  │
│  ┌─────────────────┐                                             │
│  │  Origin API     │ ← L3: sevDesk/evcc/Graph, ~200-1000ms       │
│  └─────────────────┘                                             │
└─────────────────────────────────────────────────────────────────┘

---

sevDesk

Buchhaltung & Rechnungswesen
Basis-URL: https://my.sevdesk.de/api/v1

Endpunkte

Methode	Endpunkt	Beschreibung	Cache TTL
GET	/api/sevdesk/invoices	Alle Rechnungen	5 min
GET	/api/sevdesk/invoices/:id	Einzelne Rechnung	5 min
POST	/api/sevdesk/invoices	Rechnung erstellen	-
PUT	/api/sevdesk/invoices/:id/status	Status ändern	-
GET	/api/sevdesk/contacts	Alle Kontakte	15 min
GET	/api/sevdesk/contacts/:id	Einzelner Kontakt	15 min
POST	/api/sevdesk/contacts	Kontakt erstellen	-
PUT	/api/sevdesk/contacts/:id	Kontakt aktualisieren	-
GET	/api/sevdesk/vouchers	Alle Belege	10 min
POST	/api/sevdesk/vouchers	Beleg erstellen	-
GET	/api/sevdesk/accounts	Konten	60 min
GET	/api/sevdesk/categories	Kategorien	60 min
GET	/api/sevdesk/reports/profit	Gewinnreport	30 min
GET	/api/sevdesk/reports/revenue	Umsatzreport	30 min
GET	/api/sevdesk/health	API Health Check	1 min

Request-Beispiel

// GET /api/sevdesk/invoices
const response = await fetch('/api/sevdesk/invoices?status=100&limit=50');
const data = await response.json();

// Response
{
  "objects": [
    {
      "id": "12345",
      "invoiceNumber": "RE-2024-0001",
      "contact": { "id": "789", "name": "Mustermann GmbH" },
      "invoiceDate": "2024-01-15",
      "status": 100,
      "sumNet": "1000.00",
      "sumGross": "1190.00"
    }
  ],
  "total": 150,
  "cached": true,
  "cacheAge": 45000
}

TypeScript Types

interface SevDeskInvoice {
  id: string;
  invoiceNumber: string;
  contact: { id: string; name: string };
  invoiceDate: string;
  status: 100 | 200 | 1000; // Draft | Open | Paid
  sumNet: string;
  sumGross: string;
  taxRate: number;
  currency: string;
}

interface SevDeskContact {
  id: string;
  name: string;
  customerNumber: string;
  email: string;
  phone: string;
  addresses: SevDeskAddress[];
}

---

evcc

Solar & Elektromobilität
Basis-URL: http://evcc.local:7070/api

Endpunkte

Methode	Endpunkt	Beschreibung	Cache TTL
GET	/api/evcc/state	Gesamtstatus	10s
GET	/api/evcc/loadpoints	Alle Ladepunkte	10s
GET	/api/evcc/loadpoints/:id	Einzelner Ladepunkt	10s
POST	/api/evcc/loadpoints/:id/mode	Lademodus setzen	-
POST	/api/evcc/loadpoints/:id/target	Ziel-SoC setzen	-
GET	/api/evcc/vehicles	Alle Fahrzeuge	60s
GET	/api/evcc/vehicles/:id	Einzelnes Fahrzeug	60s
GET	/api/evcc/site	Site-Konfiguration	300s
GET	/api/evcc/tariff	Stromtarif	300s
GET	/api/evcc/health	Health Check	10s

Request-Beispiel

// GET /api/evcc/state
const response = await fetch('/api/evcc/state');
const data = await response.json();

// Response
{
  "siteTitle": "Haus Muster",
  "gridPower": -2500,      // Negativ = Einspeisung
  "pvPower": 8500,         // PV-Produktion
  "batteryPower": 1500,    // Positiv = Laden
  "batterySoc": 75,        // Batterie %
  "homePower": 4500,       // Hausverbrauch
  "loadpoints": [
    {
      "title": "Garage",
      "mode": "pv",
      "connected": true,
      "charging": true,
      "chargePower": 7400,
      "vehicleSoc": 65
    }
  ],
  "cached": true,
  "cacheAge": 5000
}

TypeScript Types

interface EvccState {
  siteTitle: string;
  gridPower: number;      // W (negativ = Export)
  pvPower: number;        // W
  batteryPower: number;   // W (negativ = Entladen)
  batterySoc: number;     // %
  homePower: number;      // W
  loadpoints: EvccLoadpoint[];
}

interface EvccLoadpoint {
  title: string;
  mode: 'off' | 'now' | 'minpv' | 'pv';
  connected: boolean;
  charging: boolean;
  chargePower: number;
  vehicleSoc: number;
  vehicleRange: number;
  targetSoc: number;
}

---

MS Graph

Microsoft 365 Integration
Basis-URL: https://graph.microsoft.com/v1.0

⚠️ Status: OAuth erforderlich - Benötigt Azure AD App Registration

Endpunkte

Methode	Endpunkt	Beschreibung	Cache TTL
GET	/api/graph/me	Aktueller User	15 min
GET	/api/graph/users	Alle User	15 min
GET	/api/graph/calendar/events	Kalender-Events	5 min
POST	/api/graph/calendar/events	Event erstellen	-
GET	/api/graph/mail/messages	E-Mails	5 min
POST	/api/graph/mail/send	E-Mail senden	-
GET	/api/graph/drive/files	OneDrive Dateien	10 min
GET	/api/graph/health	Health Check	1 min

OAuth Flow

┌─────────────────────────────────────────────────────────────────┐
│  1. User klickt "Mit Microsoft anmelden"                         │
│      ↓                                                           │
│  2. Redirect zu Azure AD Login                                   │
│      ↓                                                           │
│  3. User authentifiziert sich                                    │
│      ↓                                                           │
│  4. Azure AD sendet Authorization Code                           │
│      ↓                                                           │
│  5. Backend tauscht Code gegen Access Token                      │
│      ↓                                                           │
│  6. Token wird in D1 gespeichert (verschlüsselt)                 │
│      ↓                                                           │
│  7. Refresh Token für automatische Erneuerung                    │
└─────────────────────────────────────────────────────────────────┘

TypeScript Types

interface GraphUser {
  id: string;
  displayName: string;
  mail: string;
  userPrincipalName: string;
  jobTitle: string;
}

interface GraphCalendarEvent {
  id: string;
  subject: string;
  start: { dateTime: string; timeZone: string };
  end: { dateTime: string; timeZone: string };
  location: { displayName: string };
  attendees: { emailAddress: { address: string } }[];
}

---

ista

Heizkostenabrechnung
Basis-URL: https://meine.ista.de (Scraping)

⚠️ Status: Scraping - Keine offizielle API, Session-basiert

Endpunkte

Methode	Endpunkt	Beschreibung	Cache TTL
GET	/api/ista/consumptions	Verbrauchsdaten	24h
GET	/api/ista/consumptions/:propertyId	Verbrauch pro Liegenschaft	24h
GET	/api/ista/properties	Alle Liegenschaften	24h
GET	/api/ista/properties/:id	Einzelne Liegenschaft	24h
GET	/api/ista/bills	Abrechnungen	24h
GET	/api/ista/bills/:id/pdf	Abrechnung PDF	-
GET	/api/ista/health	Session Status	1h

Request-Beispiel

// GET /api/ista/consumptions
const response = await fetch('/api/ista/consumptions?year=2024');
const data = await response.json();

// Response
{
  "properties": [
    {
      "id": "prop-123",
      "name": "Musterstraße 1",
      "consumptions": {
        "heating": { "value": 12500, "unit": "kWh", "cost": 1875.00 },
        "hotWater": { "value": 45, "unit": "m³", "cost": 315.00 },
        "coldWater": { "value": 78, "unit": "m³", "cost": 156.00 }
      },
      "period": "2024-01-01/2024-12-31"
    }
  ],
  "cached": true,
  "cacheAge": 43200000
}

TypeScript Types

interface IstaConsumption {
  propertyId: string;
  propertyName: string;
  heating: { value: number; unit: 'kWh'; cost: number };
  hotWater: { value: number; unit: 'm³'; cost: number };
  coldWater: { value: number; unit: 'm³'; cost: number };
  period: string; // ISO 8601 interval
}

interface IstaProperty {
  id: string;
  name: string;
  address: string;
  units: number;
  lastSync: string;
}

---

plane.so

Projekt- & Issue-Tracking
Basis-URL: https://api.plane.so/api/v1

Endpunkte

Methode	Endpunkt	Beschreibung	Cache TTL
GET	/api/plane/workspaces	Alle Workspaces	30 min
GET	/api/plane/projects	Alle Projekte	15 min
GET	/api/plane/projects/:id	Einzelnes Projekt	15 min
GET	/api/plane/issues	Alle Issues	5 min
GET	/api/plane/issues/:id	Einzelnes Issue	5 min
POST	/api/plane/issues	Issue erstellen	-
PUT	/api/plane/issues/:id	Issue aktualisieren	-
GET	/api/plane/health	Health Check	1 min

Request-Beispiel

// GET /api/plane/issues
const response = await fetch('/api/plane/issues?project=proj-123&state=backlog');
const data = await response.json();

// Response
{
  "issues": [
    {
      "id": "issue-456",
      "name": "Implement Cache Layer",
      "description": "Add three-tier caching...",
      "state": "backlog",
      "priority": "high",
      "assignees": ["user-789"],
      "labels": ["backend", "performance"],
      "estimate_point": 8,
      "created_at": "2024-01-15T10:00:00Z"
    }
  ],
  "total": 42,
  "cached": true,
  "cacheAge": 120000
}

TypeScript Types

interface PlaneIssue {
  id: string;
  name: string;
  description: string;
  state: 'backlog' | 'todo' | 'in_progress' | 'done' | 'cancelled';
  priority: 'urgent' | 'high' | 'medium' | 'low' | 'none';
  assignees: string[];
  labels: string[];
  estimate_point: number;
  created_at: string;
  updated_at: string;
}

interface PlaneProject {
  id: string;
  name: string;
  description: string;
  workspace: string;
  identifier: string;
  issue_count: number;
}

---

Rate Limiting

Alle Endpunkte implementieren Rate Limiting pro API:

API	Limit	Window	Burst
sevDesk	100	1 min	20
evcc	60	1 min	10
MS Graph	1000	1 h	50
ista	10	1 min	2
plane.so	60	1 min	10

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704067200
X-Cache-Status: HIT
X-Cache-Age: 45000

---

Error Handling

Alle APIs verwenden einheitliche Error-Responses:

interface ApiError {
  error: {
    code: string;
    message: string;
    details?: Record<string, unknown>;
    retryAfter?: number;
  };
  status: number;
  timestamp: string;
  requestId: string;
}

Error Codes

Code	HTTP Status	Beschreibung
RATE_LIMIT_EXCEEDED	429	Rate Limit überschritten
UPSTREAM_ERROR	502	Fehler von externer API
UPSTREAM_TIMEOUT	504	Timeout bei externer API
AUTH_REQUIRED	401	Authentifizierung erforderlich
AUTH_EXPIRED	401	Token abgelaufen
VALIDATION_ERROR	400	Ungültige Parameter
NOT_FOUND	404	Ressource nicht gefunden

---

Authentifizierung

API Key (sevDesk, evcc, plane.so)

Authorization: Bearer <API_KEY>

OAuth 2.0 (MS Graph)

Authorization: Bearer <ACCESS_TOKEN>

Session-basiert (ista)

Cookie: JSESSIONID=<SESSION_ID>

---

Caching

Cache Control

Cache-Control: max-age=300, stale-while-revalidate=60
X-Cache-Status: HIT | MISS | STALE
X-Cache-Age: <milliseconds>

Cache Invalidierung

// POST /api/cache/invalidate
{
  "pattern": "sevdesk:invoices:*",
  "reason": "Manual refresh"
}

---

Monitoring

Health Check Aggregiert

// GET /api/health
{
  "status": "healthy",
  "services": {
    "sevdesk": { "status": "up", "latency": 120 },
    "evcc": { "status": "up", "latency": 45 },
    "msgraph": { "status": "degraded", "latency": 850 },
    "ista": { "status": "up", "latency": 200 },
    "plane": { "status": "up", "latency": 180 }
  },
  "cache": {
    "memory": { "size": 850, "hitRate": 0.92 },
    "kv": { "hitRate": 0.78 }
  },
  "uptime": 86400
}

---

D1 Sync Status

// GET /api/sync/status
{
  "apis": {
    "sevdesk": {
      "lastSync": "2024-12-30T12:00:00Z",
      "recordsTotal": 1250,
      "recordsPending": 0,
      "status": "synced"
    },
    "evcc": {
      "lastSync": "2024-12-30T12:54:00Z",
      "recordsTotal": 8640,
      "recordsPending": 0,
      "status": "synced"
    }
  },
  "nextScheduledSync": "2024-12-30T13:00:00Z"
}

---

Dokumentation generiert von Agent G100 am 2024-12-30