API-Funktion Projekterstellung V1

Übersicht

Die addProject Funktion ist eine API-Funktion, die es externen Systemen ermöglicht, neue Projekte über eine HTTP-Schnittstelle zu importieren. Diese Funktion wird hauptsächlich verwendet, um Projektdaten von externen Quellen (z. B. Websites, Partner-Systemen) automatisiert zu übernehmen.

Zweck

Die Funktion ermöglicht:

Das Erstellen neuer Projekte mit Gebäude- und Kontaktdaten über eine REST-API
Die sichere Authentifizierung mittels JWT-Token
Die automatische Validierung von Pflichtfeldern
Die Verwendung von Projektvorlagen (Templates)
Die automatische E-Mail-Benachrichtigung bei Fehlern

Authentifizierung

JWT-Token

Die Funktion verwendet JWT (JSON Web Token) zur Authentifizierung. Das Token wird als Query-Parameter token übergeben.

Token-Freischaltung

Wichtig: Die Freischaltung eines Tokens kann über den Support ermöglicht werden.

Das Token kann nach Freischaltung hier generiert werden: https://app.grundsteine.com/settings?tab=privacy

API-Endpunkt

Der Endpunkt ist https://eba-api.azurewebsites.net/addProject?token=MEIN_TOKEN.

HTTP-Methode

POST

URL-Parameter

token (erforderlich): JWT-Token zur Authentifizierung

Request Body

Der Request Body muss ein JSON-Objekt mit dem Feld data enthalten.

Parameter-Übersicht

`data` (oberste Ebene)

Parameter

Typ

Pflicht

Standard

Beschreibung

`client`	Objekt	nein	–	Kontaktdaten des Kunden (siehe `client`-Parameter)
`building`	Objekt	ja	–	Gebäudedaten (siehe `building`-Parameter)
`reference`	string	nein	`"WEBSITE"`	Freie Referenz, z. B. zur Identifikation der Import-Quelle
`note`	string	nein	`"Importiert via Website"`	Interne Notiz zum Projekt
`state`	enum	nein	`"ACTIVE"`	Status des Projekts (siehe Enum `ProjectState`)
`type`	string	nein	`"Anfrage/Angebot"`	Projekttyp; überschreibt den Template-Typ, wenn `templateId` angegeben ist. Ohne Angabe von `type` und `templateId` wird `"Anfrage/Angebot"` verwendet
`templateId`	string	nein	–	UUID einer Projektvorlage, deren Struktur und Einstellungen übernommen werden

`client` (Kontaktdaten)

Parameter

Typ

Pflicht

Beschreibung

`firstName`	string	nein	Vorname des Kunden
`lastName`	string	ja	Nachname des Kunden
`email`	string	nein	E-Mail-Adresse
`phone`	string	nein	Telefonnummer
`type`	enum	nein	Kontakttyp (siehe Enum `ContactType`)
`companyName`	string	nein	Firmenname (relevant bei `type: "COMPANY"`)
`representedBy`	string	nein	Vertreten durch
`title`	string	nein	Akademischer Titel, z. B. `"Dr."`, `"Prof."`, `"Prof. Dr."`
`salutation`	string	nein	Anrede, z. B. `"Hallo"`, `"Sehr geehrte"`, `"Sehr geehrter"`, `"Guten Tag"`
`address.street`	string	nein	Straße
`address.houseNumber`	string	nein	Hausnummer
`address.zip`	string	nein	Postleitzahl
`address.city`	string	nein	Stadt

`building` (Gebäudedaten)

Parameter

Typ

Pflicht

Beschreibung

`address.street`	string	ja	Straße des Gebäudes
`address.houseNumber`	string	ja	Hausnummer des Gebäudes
`address.zip`	string	ja	Postleitzahl des Gebäudes
`address.city`	string	ja	Stadt des Gebäudes
`yearOfCompletion`	number	nein	Baujahr des Gebäudes (z. B. `1990`)
`numberOfPartiesInBuilding`	number	nein	Anzahl der Wohneinheiten im Gebäude
`numberOfFloors`	number	nein	Anzahl der Stockwerke
`usageType`	enum	nein	Primärer Gebäudetyp (siehe Enum `BuildingType`)
`usageKind`	enum	nein	Nutzungsart des Gebäudes (siehe Enum `UsageKindType`)
`latitude`	string	nein	Breitengrad (z. B. `"52.520008"`)
`longitude`	string	nein	Längengrad (z. B. `"13.404954"`)

Enum-Werte

Enum `ProjectState` (Feld: `state`)

Wert

Bedeutung

Frontend-Label (sichtbar)

`ACTIVE`	Aktives Projekt (Standard)	`Aktiv (wartend und in Arbeit)`
`ARCHIVED`	Archiviert	`Abgeschlossen` (teilweise auch `Archiviert` je nach Ansicht)
`CANCELED`	Storniert	`Abgebrochen`

Enum `ContactType` (Feld: `client.type`)

Wert

Bedeutung

Frontend-Label (sichtbar)

`PERSON`	Natürliche Person	`Privatperson`
`COMPANY`	Unternehmen / juristische Person	`Unternehmen`
`OBJECT`	Objekt	`Eigentümer` (nur sichtbar, wenn der Kontakt diesen Typ bereits aus der Hottgenroth-Synchronisation gesetzt hat; im Frontend nicht manuell auswählbar)
`WEG`	Wohnungseigentümergemeinschaft	`WEG`

Enum `BuildingType` (Feld: `building.usageType`)

Wert

Bedeutung

Frontend-Label (sichtbar)

`RESIDENTIAL`	Wohngebäude	`Wohngebäude`
`NONRESIDENTIAL`	Nichtwohngebäude	`Nicht-Wohngebäude`
`MIXED`	Mischgebäude (Wohn- und Nichtwohnnutzung)	`Mischgebäude`

Enum `UsageKindType` (Feld: `building.usageKind`)

Wert

Bedeutung

Frontend-Label (sichtbar)

`LEASED_BUILDING`	Vermietung	`Vermietung (ausschließlich)`
`OWNER_OCCUPIED_BUILDING`	Eigennutzung	`Eigennutzung (ausschließlich)`
`MIXED_SELFUSE_LEASED`	Gemischte Nutzung (Eigennutzung und Vermietung)	`Eigennutzung und Vermietung`

Pflichtfelder

Die folgenden Felder sind zwingend erforderlich:

client.lastName
building.address.street
building.address.houseNumber
building.address.zip
building.address.city

Wenn templateId angegeben wird, muss es im UUID-Format vorliegen (z. B. 123e4567-e89b-12d3-a456-426614174000).

Beispiel-Request-Body

{
  "data": {
    "client": {
      "firstName": "Max",
      "lastName": "Mustermann",
      "email": "[email protected]",
      "phone": "+49 123 456789",
      "type": "PERSON",
      "salutation": "Sehr geehrter"
    },
    "building": {
      "address": {
        "street": "Musterstraße",
        "houseNumber": "42",
        "zip": "12345",
        "city": "Berlin"
      },
      "yearOfCompletion": 1990,
      "numberOfFloors": 3,
      "usageType": "RESIDENTIAL",
      "usageKind": "OWNER_OCCUPIED_BUILDING",
      "latitude": "52.520008",
      "longitude": "13.404954"
    },
    "reference": "WEBSITE",
    "note": "Importiert via Website",
    "state": "ACTIVE",
    "templateId": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Response

Erfolgreiche Antwort (HTTP 200)

{
  "message": "Project added successfully"
}

Fehlerhafte Authentifizierung (HTTP 401)

{
  "error": "Unauthorized"
}

Fehlende oder ungültige Daten (HTTP 400)

{
  "error": {
    "message": "Missing or invalid mandatory fields: client.lastName, building.address.street, ..."
  }
}

Fehler beim Import (HTTP 500)

{
  "error": "Reference: WEBSITE, Error: [Fehlermeldung]"
}

Technische Details

Funktionsablauf

Token-Validierung
- Das JWT-Token wird aus den Query-Parametern extrahiert
- Die Funktion decodeJwt() verifiziert das Token mit dem APP_SECRET
- Bei ungültigem Token wird ein 401-Fehler zurückgegeben
Projekttyp-Bestimmung
- Die Funktion determineProjectType() bestimmt den Projekttyp nach folgender Priorität:
  1. Explizit angegebener data.type
  2. Typ aus der Vorlage (Template), falls templateId angegeben
  3. Standardwert: Anfrage/Angebot
Validierung der Pflichtfelder
- Alle Pflichtfelder werden überprüft
- Die templateId wird auf gültiges UUID-Format geprüft
- Bei fehlenden Feldern wird eine detaillierte Fehlermeldung mit allen fehlenden Feldern zurückgegeben
Projekt-Import
- Die Daten werden in das interne Format transformiert
- Die Funktion importProjects() erstellt das Projekt, den Kontakt und das Gebäude in der Datenbank
- Wenn eine templateId angegeben ist, werden die Projektstruktur und Einstellungen von der Vorlage kopiert
Fehlerbehandlung und E-Mail-Benachrichtigung
- Bei Fehlern während des Imports wird eine E-Mail an den zugehörigen Benutzer gesendet
- Die E-Mail enthält:
  - Detaillierte Fehlermeldung
  - Die übermittelten Projektdaten (zur Fehlerbehebung)
  - Hinweis auf den Support-Chat
- Die Fehlerbenachrichtigung wird in die Warteschlange für transaktionale E-Mails eingereiht

Beispiel-Aufruf

curl -X POST "https://eba-api.azurewebsites.net/addProject?token=eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "client": {
        "firstName": "Max",
        "lastName": "Mustermann",
        "email": "[email protected]",
        "phone": "+49 123 456789",
        "type": "PERSON",
        "salutation": "Sehr geehrter"
      },
      "building": {
        "address": {
          "street": "Musterstraße",
          "houseNumber": "42",
          "zip": "12345",
          "city": "Berlin"
        },
        "yearOfCompletion": 1990,
        "numberOfFloors": 3,
        "usageType": "RESIDENTIAL",
        "usageKind": "OWNER_OCCUPIED_BUILDING",
        "latitude": "52.520008",
        "longitude": "13.404954"
      },
      "note": "Import von Website-Formular",
      "reference": "WEB-2024-001",
      "state": "ACTIVE"
    }
  }'

Fehlerbehandlung

Häufige Fehlerszenarien

Ungültiges Token: Überprüfen Sie, ob das Token korrekt generiert wurde und nicht abgelaufen ist
Fehlende Pflichtfelder: Stellen Sie sicher, dass alle erforderlichen Felder vorhanden sind
Ungültiges UUID-Format: Die templateId muss im korrekten UUID-Format vorliegen
Template nicht gefunden: Die angegebene templateId existiert nicht in der Organisation
Datenbankfehler: Prüfen Sie die Logs für Details zu Datenbankproblemen

E-Mail-Benachrichtigung bei Fehlern

Bei Importfehlern wird automatisch eine E-Mail an den Benutzer gesendet, der mit dem Token verknüpft ist. Diese E-Mail enthält:

Eine benutzerfreundliche Fehlerbeschreibung
Die vollständigen übermittelten Daten zur Fehleranalyse
Kontaktinformationen für den Support

Integration

Diese Funktion ist ideal für:

Website-Formulare zur Projekterfassung
Partner-Systeme, die Projekte automatisch anlegen möchten
Externe Datenimporte von CRM- oder ERP-Systemen
Mobile Apps für die Projekterfassung

Wartung und Support

Bei Fragen zur Integration oder Problemen mit der API-Funktion wenden Sie sich bitte an:

Technischer Support: Über den Chat
Token-Freischaltung: Kann über den Support aktiviert werden

Hilfe Center

Hilfe Center

API-Funktion Projekterstellung V1

Diese Funktion stellt die Projekterstellung (addProject) via Schnittstelle (API) bereit. Hierbei handelt es sich um die v1.

Übersicht

Zweck

Authentifizierung

JWT-Token

Token-Freischaltung

API-Endpunkt

HTTP-Methode

URL-Parameter

Request Body

Parameter-Übersicht

`data` (oberste Ebene)

`client` (Kontaktdaten)

`building` (Gebäudedaten)

Enum-Werte

Enum `ProjectState` (Feld: `state`)

Enum `ContactType` (Feld: `client.type`)

Enum `BuildingType` (Feld: `building.usageType`)

Enum `UsageKindType` (Feld: `building.usageKind`)

Pflichtfelder

Beispiel-Request-Body

Response

Erfolgreiche Antwort (HTTP 200)

Fehlerhafte Authentifizierung (HTTP 401)

Fehlende oder ungültige Daten (HTTP 400)

Fehler beim Import (HTTP 500)

Technische Details

Funktionsablauf

Beispiel-Aufruf

Fehlerbehandlung

Häufige Fehlerszenarien

E-Mail-Benachrichtigung bei Fehlern

Integration

Wartung und Support

Hilfe Center

Hilfe Center

API-Funktion Projekterstellung V1

Diese Funktion stellt die Projekterstellung (addProject) via Schnittstelle (API) bereit. Hierbei handelt es sich um die v1.

Übersicht

Zweck

Authentifizierung

JWT-Token

Token-Freischaltung

API-Endpunkt

HTTP-Methode

URL-Parameter

Request Body

Parameter-Übersicht

data (oberste Ebene)

client (Kontaktdaten)

building (Gebäudedaten)

Enum-Werte

Enum ProjectState (Feld: state)

Enum ContactType (Feld: client.type)

Enum BuildingType (Feld: building.usageType)

Enum UsageKindType (Feld: building.usageKind)

Pflichtfelder

Beispiel-Request-Body

Response

Erfolgreiche Antwort (HTTP 200)

Fehlerhafte Authentifizierung (HTTP 401)

Fehlende oder ungültige Daten (HTTP 400)

Fehler beim Import (HTTP 500)

Technische Details

Funktionsablauf

Beispiel-Aufruf

Fehlerbehandlung

Häufige Fehlerszenarien

E-Mail-Benachrichtigung bei Fehlern

Integration

Wartung und Support

`data` (oberste Ebene)

`client` (Kontaktdaten)

`building` (Gebäudedaten)

Enum `ProjectState` (Feld: `state`)

Enum `ContactType` (Feld: `client.type`)

Enum `BuildingType` (Feld: `building.usageType`)

Enum `UsageKindType` (Feld: `building.usageKind`)