Die Structify-API

Überblick

Die Structify-API ist eine REST-Schnittstelle: Sie senden HTTPS-Anfragen und erhalten JSON zurück. Jeder API-Schlüssel gehört zu genau einer Organisation und erreicht ausschließlich deren Daten.

Protokoll

HTTPS, Anfragen und Antworten als JSON (UTF-8)

Version

v1 – steht im Pfad jeder Anfrage

Anmeldung

API-Schlüssel im Kopfzeilenfeld X-Api-Key

Bereiche

Projekte, Mängel, Protokolle, Angaben zu Projektdateien, Webhooks; dazu Alteinträge des früheren Bautagebuchs

Grenze

1.000 Anfragen pro Stunde je Schlüssel

Zugang & Berechtigungen

Für die Anbindung brauchen Sie einen API-Schlüssel, den Ihre Geschäftsführung in der Web-App anlegt: Einstellungen → Integrationen → API & Drittanbieter.

Rechte eines Schlüssels

Beim Anlegen wählen Sie, was der Schlüssel darf. Der Server prüft diese Rechte bei jeder Anfrage:

Die in der Oberfläche angebotene Auswahl „Rechnungen exportieren“ schaltet heute keinen Endpunkt frei.

Authentifizierung

Senden Sie den Schlüssel bei jeder Anfrage im Kopfzeilenfeld X-Api-Key. Alternativ nimmt die API ihn als Bearer-Token im Feld Authorization an.

X-Api-Key: <IHR_API_SCHLUESSEL>

Authorization: Bearer <IHR_API_SCHLUESSEL>

• Schlüssel beginnen mit sk_. Structify zeigt einen Schlüssel nur einmal – direkt nach dem Anlegen. Kopieren Sie ihn dann sofort.
• Gespeichert werden nur ein Prüfwert (SHA-256) und die ersten Zeichen zur Wiedererkennung, nicht der Schlüssel selbst. Deshalb kann ihn niemand nachträglich vollständig anzeigen; bei Verlust legen Sie einen neuen an und deaktivieren den alten.
• Deaktivieren Sie einen Schlüssel in den Einstellungen, ist er sofort ungültig.

Basis-URL

Alle Pfade auf dieser Seite hängen Sie an diese Basis-URL an:

https://api.structify.solutions/functions/v1/public-api

• Beispiel: …/public-api/v1/projekte
• Nur HTTPS. Die Version (v1) steht im Pfad.
• Kennungen (id) sind UUIDs; Zeitpunkte stehen im ISO-8601-Format mit Zeitzone, Datumsfelder als JJJJ-MM-TT.
• Feldnamen und Feldwerte übernimmt die API aus Structify; Fehlermeldungen sind deutsch. Ausnahme: Scheitert das Registrieren eines Webhooks an der Datenbank, kann die Meldung englischen Datenbanktext enthalten.

Beispielanfrage

So rufen Sie die ersten zwei Projekte Ihrer Organisation ab:

curl "https://api.structify.solutions/functions/v1/public-api/v1/projekte?limit=2" \
  -H "X-Api-Key: <IHR_API_SCHLUESSEL>"

const response = await fetch(
  "https://api.structify.solutions/functions/v1/public-api/v1/projekte?limit=2",
  { headers: { "X-Api-Key": process.env.STRUCTIFY_API_KEY } }
);
const body = await response.json();
if (!response.ok) throw new Error(`${body.status}: ${body.error}`);
const { data, total } = body;

{
  "data": [
    {
      "id": "<PROJEKT_ID>",
      "project_name": "Neubau Bürogebäude Musterstraße",
      "project_number": "2026-014",
      "client_id": "<KUNDEN_ID>",
      "clients": {
        "name": "Muster GmbH"
      },
      "project_type": "Neubau",
      "current_phase": "LP5",
      "status": "aktiv",
      "priority": "normal",
      "construction_start": "2026-03-02",
      "construction_end": "2027-06-30",
      "created_at": "2026-01-15T09:12:44.512+00:00"
    }
  ],
  "total": 12,
  "limit": 2,
  "offset": 0
}

Listen liefern data (Einträge), total (Gesamtzahl der Treffer), limit und offset – mit einer Ausnahme: GET /v1/webhooks liefert nur data. Einzelabrufe liefern data mit allen Feldern des Datensatzes.

Verfügbare Endpunkte

Diese Endpunkte funktionieren heute. Pfade relativ zur Basis-URL; {id} steht für die Kennung des Datensatzes.

Grundbegriffe

Organisation

Jeder Schlüssel gehört zu genau einer Organisation. Datensätze anderer Organisationen sind nicht sichtbar: Einzelabrufe mit einer fremden Kennung beantwortet die API mit 404.

Seitenweise abrufen

limit legt die Anzahl je Antwort fest, offset die Zahl der übersprungenen Einträge. total nennt die Gesamtzahl – so blättern Sie, bis offset + limit ≥ total.

Sortierung

Listen sind fest sortiert: neueste zuerst (früheres Bautagebuch nach Datum absteigend; Webhooks ohne feste Reihenfolge). Eine eigene Sortierung bietet die API nicht.

Filter

Filter vergleichen auf exakte Gleichheit. Ein Wert, den es nicht gibt, liefert eine leere Liste; eine ungültige Kennung in einem Filter liefert 400.

Antworten

Liste: data, total, limit, offset (Webhooks: nur data) · Einzelabruf: data · Anlegen und Ändern: data und message · Löschen: message.

Methoden

Protokolle, das frühere Bautagebuch und Projektdateien sind nur lesbar. Senden Sie dorthin nur GET: Andere Methoden weist die API dort heute nicht ab, sondern beantwortet sie wie GET mit der Liste – angelegt oder geändert wird dabei nichts.

Ratenbegrenzung

Je Schlüssel sind 1.000 Anfragen pro Stunde möglich. Gezählt wird über die jeweils letzten 60 Minuten – auch Anfragen, die in einem Endpunkt mit einem Fehler enden (zum Beispiel 400 oder 404).

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997

Ist die Grenze erreicht, antwortet die API mit Status 429:

{
  "error": "Rate Limit überschritten (1000/h)",
  "status": 429
}

Fehler & Statuscodes

Fehler, die die API selbst feststellt, beantwortet sie mit einem passenden HTTP-Status und diesem JSON:

{
  "error": "API-Key fehlt. Header: X-Api-Key: sk_...",
  "status": 401
}

Maßgeblich ist der Statuscode. Der Meldungstext ist deutsch und kann sich ändern – werten Sie ihn nicht maschinell aus.

Bei Störungen im Betrieb, etwa 502 oder 504 nach einer Zeitüberschreitung, kann die Antwort ein anderes oder gar kein JSON enthalten. Werten Sie dann nur den Status aus und versuchen Sie es später erneut. Prüfen Sie vor einem erneuten POST /v1/tickets per GET, ob der Mangel nicht doch schon angelegt wurde.

Webhooks

Ein Webhook meldet Ihrem System ein Ereignis per HTTP-POST an eine von Ihnen festgelegte Adresse. Heute versendet Structify genau zwei Ereignisse:

Aufbau einer Nachricht

data enthält den gespeicherten Datensatz des Mangels mit allen Feldern (hier gekürzt; dazu gehören auch Kontakt-E-Mail, zuständige Firma und Notizen), timestamp den Zeitpunkt des Versands.

POST /structify-webhook HTTP/1.1
Host: ihre-firma.example
Content-Type: application/json
X-Structify-Signature: sha256=<HEX>

{
  "event": "ticket.status_geaendert",
  "data": {
    "id": "<MANGEL_ID>",
    "organization_id": "<ORGANISATIONS_ID>",
    "project_id": "<PROJEKT_ID>",
    "defect_number": "M-ERP-001",
    "building_location": "2. OG, Raum 2.14",
    "description": "Brandschutzklappe ohne Revisionsöffnung",
    "status": "behoben",
    "severity": "erheblich",
    "discipline": "Lüftung",
    "remediation_deadline": "2026-11-15",
    "created_at": "2026-10-08T07:41:03.118+00:00"
  },
  "timestamp": "2026-10-09T13:05:12.402Z"
}

Zustellung

• Structify sendet die Nachricht, während die auslösende API-Anfrage verarbeitet wird. Ein langsamer Empfänger verzögert deshalb deren Antwort.
• Zeitlimit 5 Sekunden je Empfänger; höchstens 10 Webhooks je Ereignis. Sind für ein Ereignis mehr als 10 Webhooks registriert, ist nicht festgelegt, welche 10 beliefert werden.
• Keine Wiederholung bei Fehlern. Zeitpunkt und HTTP-Status des letzten Versuchs zeigt GET /v1/webhooks (letzter_versuch, letzte_antwort; 0 bedeutet: keine Antwort).
• Verwenden Sie für die Zieladresse HTTPS.

Signatur prüfen

Die Kopfzeile X-Structify-Signature enthält sha256= und den HMAC-SHA256 des unveränderten Anfragekörpers, gebildet mit dem Signaturschlüssel des Webhooks. Vergleichen Sie zeitkonstant:

import crypto from "node:crypto";

// rawBody: der unveränderte Anfragekörper, nicht neu serialisiert
export function isValidSignature(rawBody, signatureHeader, signingSecret) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", signingSecret)
    .update(rawBody)
    .digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(signatureHeader ?? "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Die Signatur enthält keinen Zeitstempel. Wenn Sie wiederholt eingespielte Nachrichten abweisen möchten, prüfen Sie zusätzlich das Feld timestamp.

Anleitungen

Erster Abruf in fünf Schritten

1. Melden Sie sich als Mitglied der Geschäftsführung in der Web-App an und öffnen Sie Einstellungen → Integrationen → API & Drittanbieter.
2. Legen Sie einen Schlüssel mit einer sprechenden Bezeichnung an (zum Beispiel „ERP-Anbindung“) und wählen Sie nur die Rechte, die Ihr System braucht.
3. Kopieren Sie den Schlüssel sofort – er wird nur einmal angezeigt – und hinterlegen Sie ihn auf Ihrem Server, zum Beispiel als Umgebungsvariable STRUCTIFY_API_KEY.
4. Rufen Sie GET /v1/projekte auf, wie im Abschnitt Beispielanfrage gezeigt.
5. Prüfen Sie die Antwort: Status 200, Ihre Projekte in data und die verbleibenden Anfragen in X-RateLimit-Remaining.

Mängel aus Ihrem System anlegen und nachführen

Voraussetzung ist ein Schlüssel mit dem Recht Tickets schreiben. Legen Sie den Mangel an und merken Sie sich die zurückgegebene id:

curl -X POST "https://api.structify.solutions/functions/v1/public-api/v1/tickets" \
  -H "X-Api-Key: <IHR_API_SCHLUESSEL>" \
  -H "Content-Type: application/json" \
  -d '{"project_id":"<PROJEKT_ID>","defect_number":"M-ERP-001","building_location":"2. OG, Raum 2.14","description":"Brandschutzklappe ohne Revisionsöffnung","severity":"erheblich","discipline":"Lüftung","remediation_deadline":"2026-11-15"}'

{
  "data": {
    "id": "<MANGEL_ID>",
    "organization_id": "<ORGANISATIONS_ID>",
    "project_id": "<PROJEKT_ID>",
    "defect_number": "M-ERP-001",
    "building_location": "2. OG, Raum 2.14",
    "description": "Brandschutzklappe ohne Revisionsöffnung",
    "status": "offen",
    "severity": "erheblich",
    "discipline": "Lüftung",
    "remediation_deadline": "2026-11-15",
    "created_at": "2026-10-08T07:41:03.118+00:00"
  },
  "message": "Ticket erstellt"
}

Später setzen Sie den Status – das löst das Ereignis ticket.status_geaendert aus:

curl -X PUT "https://api.structify.solutions/functions/v1/public-api/v1/tickets/<MANGEL_ID>" \
  -H "X-Api-Key: <IHR_API_SCHLUESSEL>" \
  -H "Content-Type: application/json" \
  -d '{"status":"behoben"}'

Offene Mängel eines Projekts rufen Sie gefiltert und seitenweise ab:

curl "https://api.structify.solutions/functions/v1/public-api/v1/tickets?projekt_id=<PROJEKT_ID>&status=offen&limit=50&offset=0" \
  -H "X-Api-Key: <IHR_API_SCHLUESSEL>"

{
  "data": [
    {
      "id": "<MANGEL_ID>",
      "defect_number": "M-ERP-001",
      "building_location": "2. OG, Raum 2.14",
      "description": "Brandschutzklappe ohne Revisionsöffnung",
      "status": "offen",
      "severity": "erheblich",
      "discipline": "Lüftung",
      "remediation_deadline": "2026-11-15",
      "project_id": "<PROJEKT_ID>",
      "created_at": "2026-10-08T07:41:03.118+00:00",
      "projects": {
        "project_name": "Neubau Bürogebäude Musterstraße"
      }
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Webhook einrichten und Signatur prüfen

Registrieren Sie den Webhook über die API und speichern Sie signing_secret aus der Antwort sicher auf Ihrem Server:

curl -X POST "https://api.structify.solutions/functions/v1/public-api/v1/webhooks" \
  -H "X-Api-Key: <IHR_API_SCHLUESSEL>" \
  -H "Content-Type: application/json" \
  -d '{"name":"ERP-Anbindung","url":"https://ihre-firma.example/structify-webhook","events":["ticket.erstellt","ticket.status_geaendert"]}'

{
  "data": {
    "id": "<WEBHOOK_ID>",
    "name": "ERP-Anbindung",
    "url": "https://ihre-firma.example/structify-webhook",
    "events": [
      "ticket.erstellt",
      "ticket.status_geaendert"
    ],
    "ist_aktiv": true
  },
  "message": "Webhook registriert",
  "signing_secret": "<SIGNATURSCHLUESSEL>"
}

Prüfen Sie bei jeder eingehenden Nachricht die Signatur (siehe Abschnitt Webhooks) und antworten Sie innerhalb von 5 Sekunden mit einem 2xx-Status.

Was die API heute nicht kann

Damit Sie verlässlich planen können, nennen wir offen, was die Schnittstelle heute nicht bietet:

• Einträge aus „Projekttickets“ und Gewährleistungsmängel aus „Gewährleistungsmangel“ abrufen oder schreiben.
• Bautagebuch-Einträge abrufen oder schreiben, die Sie heute als Projektticket der Art „Bautagebuch-Eintrag“ anlegen. GET /v1/bautagebuch liefert nur Alteinträge des früheren Bautagebuch-Bereichs.
• Dokumente aus Vorlagen im Projektbereich „Protokolle und Formulare“ (zum Beispiel Mängelanzeige, Behinderungsanzeige oder Protokolle) sowie Gesprächsprotokolle aus „Grundlagenermittlung“, „Planungsgespräch“ und „Baustellengespräch“ abrufen.
• Mangelnummern automatisch vergeben.
• Projekte anlegen oder ändern – Projekte sind nur lesbar.
• Eine projektübergreifende Volltextsuche.
• Dateien herunter- oder hochladen; Fotos, Pläne und Anhänge übertragen.
• Angaben zu Plänen und zu Fotos aus der Fotogalerie abrufen – /v1/dokumente liefert nur die Dokumentdatenbank.
• Protokolle, Einträge des früheren Bautagebuchs und Dateiangaben anlegen oder ändern.
• Nutzer, Rollen und Mitglieder abrufen; Kontakte, Rechnungen, Honorarermittlung, Vergabe und Nachträge als eigene Bereiche abrufen. Honorar-, Budget- und Abrechnungsangaben sowie Ansprechpartner, die im Projekt selbst gespeichert sind, liefert der Einzelabruf eines Projekts dagegen mit.
• Webhooks für Änderungen in der Web-App oder in Structify auf iPhone & Android; erneute Zustellung fehlgeschlagener Webhooks.
• Anmeldung per OAuth, persönliche Zugriffstoken oder Schlüssel, die auf einzelne Projekte beschränkt sind.
• Eine Testumgebung, eine maschinenlesbare Schnittstellenbeschreibung (OpenAPI) oder fertige Programmbibliotheken.

Änderungsprotokoll

1. 08.10.2026 In der Web-App verwaltet nur noch die Geschäftsführung API-Schlüssel und Webhooks. Ein Schlüssel gilt nur, solange die Person, die ihn angelegt hat, aktives Mitglied der Geschäftsführung ist.
2. 06.10.2026 Neue Basis-URL https://api.structify.solutions/functions/v1/public-api nach dem Umzug des Betriebs zu Hetzner in Deutschland. Die frühere Adresse ist nicht mehr erreichbar.