FEDEO/push-server/docs/instance-client.md

Selfhost-Instanz an FEDEO Central Services anbinden

1. Instanz im Admin-Dashboard anlegen.
2. instanceId und den einmalig angezeigten clientSecret in der Selfhost-Instanz speichern.
3. Im Instanzdetail die benötigten Dienste ai und/oder banking freischalten und Limits festlegen.
4. Selfhost-Instanz sendet regelmäßig POST /v1/instances/heartbeat.
5. Geräte werden über POST /v1/devices registriert; weitere Dienste liegen unter /v1/services.

Umgebungsvariablen der Selfhost-Instanz

FEDEO_CENTRAL_SERVICES_ENABLED=true
PUSH_SERVER_URL=https://services.fedeo.de
PUSH_SERVER_INSTANCE_ID=inst_...
PUSH_SERVER_SECRET=fps_...
FEDEO_CENTRAL_HEARTBEAT_INTERVAL_MS=300000

Das Selfhost-Backend sendet direkt beim Start und anschließend standardmäßig alle fünf Minuten einen signierten Heartbeat. Im Backend-Log erscheinen erfolgreiche Meldungen als Central Services Heartbeat: inst_... (active); Verbindungs-, Signatur- oder Freischaltungsfehler werden mit ihrer zentralen Fehlermeldung protokolliert. Werte unter 30 Sekunden werden aus Sicherheitsgründen ignoriert.

Wenn FEDEO_CENTRAL_SERVICES_ENABLED=false bleibt, verwendet FEDEO wie bisher direkt konfigurierte OpenAI- und GoCardless-Zugangsdaten. Damit bleibt ein vollständig unabhängiger Betrieb möglich.

Minimaler Push-Auftrag

{
  "idempotencyKey": "notification-item-id:dev_...",
  "devices": ["dev_..."],
  "priority": "normal",
  "ttlSeconds": 3600,
  "collapseKey": "communication.message.new",
  "notification": {
    "title": "Neue FEDEO-Benachrichtigung",
    "body": "Öffne FEDEO, um die Details anzusehen."
  },
  "data": {
    "notificationId": "lokale-notification-id",
    "link": "/communication"
  }
}