Zum Inhalt

API für eigene Konnektoren (DPC1)

Mit eigenen Konnektoren bindet eine Firma eigene Systeme lesend an, zum Beispiel ein Projektportal oder ein internes Auftragssystem. Die Firma beschreibt die Schnittstelle im Kontoportal; das Portal signiert die Beschreibung im Format DPC1 und liefert sie an die Geräte der Firma aus. Diese Seite beschreibt, was die eigene Schnittstelle können muss und wie Dayprep sie nutzt.

Voraussetzungen: Premium oder Testphase, Rolle Inhaber oder Admin im Kontoportal. Bedienung im Portal: Eigene Schnittstellen.

Anforderungen an die Schnittstelle

  • REST über https mit gültigem Zertifikat, erreichbar unter einem DNS-Namen (keine IP-Adresse).
  • Lesen mit GET. Andere Methoden verwendet Dayprep nie.
  • Antwort als JSON mit einer Liste von Einträgen, höchstens 2 MB pro Antwort. Dayprep übernimmt höchstens 500 Einträge je Endpunkt.
  • Keine Weiterleitungen. Dayprep folgt ihnen nicht.
  • Authentifizierung: keine, API-Schlüssel in einem Header, Bearer-Token oder Basic. Jede Person gibt ihren Zugang selbst in der App ein.
  • Ideal ist ein Filter nach Änderungszeit, damit Dayprep nur Neues abholt.

Definition

Die Definition entsteht im Editor des Kontoportals. Sie hat diesen Aufbau (Beispiel mit fiktiver Firma):

{
  "name": "Projektportal",
  "description": "Aufgaben aus dem Projektportal",
  "base_url": "https://api.firma.example/v2",
  "auth": {"type": "api_key_header", "header": "X-API-Key"},
  "endpoints": [
    {"key": "tasks", "label": "Aufgaben",
     "path": "/tasks",
     "query": {"updated_since": "{since}", "limit": "100"},
     "items": "data.items"}
  ],
  "mapping": {"id": "id", "title": "subject", "text": "body", "time": "updated_at", "link": "web_url",
              "person": "owner.name", "project": "project.key"},
  "interval": "1h"
}
Feld Regeln
name 2 bis 60 Zeichen, keine Steuerzeichen
description bis 300 Zeichen
base_url nur https, ASCII-DNS-Name mit Punkt; keine IP-Adresse, kein localhost, kein Punycode (xn--), keine Hex- oder Oktal-Labels. Optional Port und Pfadpräfix. Ohne Benutzerangaben, Abfrage, Fragment, % oder ..
auth.type none, api_key_header, bearer oder basic
auth.header nur bei api_key_header. Gesperrt sind unter anderem Host, Cookie, Content-Length und Header, die Methode oder Adresse überschreiben (X-HTTP-Method-Override, X-HTTP-Method, X-Method-Override, X-Original-URL, X-Rewrite-URL)
endpoints 1 bis 10 Einträge, nur GET
endpoints[].key Kleinbuchstaben, Ziffern und _, beginnt mit einem Buchstaben, höchstens 32 Zeichen, eindeutig
endpoints[].path beginnt mit /; Segmente aus Buchstaben, Ziffern und . _ ~ - sowie Platzhaltern. Keine Segmente . oder .., kein %, kein //, kein ?
endpoints[].query höchstens 10 Parameter, Werte bis 200 Zeichen
endpoints[].items Punktpfad zur Liste in der Antwort; leer heisst, die Antwort ist selbst die Liste
mapping Punktpfade (höchstens 8 Segmente) für id, title (Pflicht), text, time, link, person, project
interval 15m, 1h, 4h oder 1d: höchstens so oft abgleichen

Die ganze Definition ist höchstens 16 KB gross. Pro Firma gibt es höchstens 50 Definitionen.

Platzhalter

Nur diese festen Werte, eingesetzt von der App, nie aus Eingaben:

Platzhalter Wert
{since} letzter Abgleich minus Überlappung, beim ersten Mal 14 Tage zurück; ISO 8601 in UTC, zum Beispiel 2026-10-26T07:00:00Z
{since_date} Datum davon, zum Beispiel 2026-10-26
{now} jetzt, ISO 8601 in UTC

Im Pfad werden die Werte prozentkodiert (: wird zu %3A).

Feldzuordnung

JSON-Pfade sind punktgetrennte Namen bzw. Listenindizes (zum Beispiel tags.0), keine Ausdrücke und kein Code. Links übernimmt Dayprep nur mit http:// bzw. https://. Die Einträge erscheinen in Dayprep wie Tickets, in Briefing und Chat.

Signierte Definition

Das Portal signiert jede aktive Definition:

DPC1.<payload>.<signature>
  • payload: base64url (ohne =) des UTF-8-JSON
  • signature: base64url der Ed25519-Signatur über die ASCII-Bytes DPC1.<payload>
{"v": 1, "typ": "connector", "kid": "c-2026-11", "iss": "dayprep", "org": "org_…", "id": "cdef_…",
 "version": 3, "iat": 1793990000, "exp": 1796582000, "def": {"name": "Projektportal", "…": "…"}}
Feld Bedeutung
kid Schlüssel-ID; der Schlüssel ist ein eigener, getrennt vom Lizenzschlüssel
org Firma, an die die Definition ausgeliefert wird
id, version Kennung der Definition; die Version steigt bei jeder Änderung und beim Aktivieren bzw. Deaktivieren
iat, exp Auslieferung und Ablauf (30 Tage später), Unix-Sekunden
def die Definition wie oben

Genau diese Felder. Das Präfix trennt die Zwecke: Ein Lizenznachweis (DPL1) ist nie eine Definition und umgekehrt.

Auslieferung an die App

Die App holt die Definitionen beim Kontoportal:

POST https://portal.dayprep.app/api/v1/connectors
{"license": "DPL1…", "device": "<geräte-hash>"}

200 {"org": "org_…", "connectors": ["DPC1…", …]}
401 {"reason": "invalid_token"}
403 {"reason": "wrong_device|offline_token|user_removed|device_unknown|device_revoked|premium_only|payment_locked|expired|seats_full"}
503 {"reason": "not_configured"}

Das Portal verlangt einen gültigen Nachweis dieses Geräts, ein bekanntes und nicht gesperrtes Gerät, eine Person mit Platz in der Firma, Premium bzw. Testphase und keine Sperre wegen Zahlung. Die Antwort enthält alle aktiven Definitionen der eigenen Firma, nie Zugangsdaten.

Prüfung in der App

  • Holen höchstens einmal täglich und auf Knopfdruck («Jetzt holen» im Marktplatz).
  • Bei jedem Lesen der lokalen Ablage prüft die App erneut: Format, Schlüssel-ID, Signatur mit dem eingebauten Konnektor-Schlüssel, genau die Felder, Firma gleich der Firma des eigenen Nachweises, nicht abgelaufen, ganzer Inhalt nach den Regeln oben. Ungültige Definitionen werden verworfen.
  • Abfragen nur mit GET, nur an genau Host, Port und Pfadpräfix der Basisadresse, nur an die festgelegten Pfade mit den festgelegten Parametern. Der rohe Pfad enthält keine Prozentkodierung ausser %3A.
  • Die App löst den Host selbst auf, prüft alle Adressen und verbindet an genau die geprüfte Adresse. Abgelehnt werden Loopback, Link-Local, 0.0.0.0/8, ::, Multicast, reservierte und IPv4-gemappte Adressen. Private Netze sind erlaubt.
  • Zugangsdaten liegen nur im Schlüsselbund, gebunden an Ziel (https://host:port), Authentifizierung und Headername. Ändert sich eines davon, löscht die App den Zugang. Abmelden vom Konto löscht alle Zugänge.
  • Die Richtlinie connectors_disabled: ["custom"] schaltet alle eigenen Konnektoren ab.