--- title: "API-Funktion Projekterstellung V1" description: "Diese Funktion stellt die Projekterstellung (addProject) via Schnittstelle (API) bereit. Hierbei handelt es sich um die v1." url: https://support.grundsteine.com/de/articles/108-api-funktion-projekterstellung-v1 collection: "Vor dem Projekt" updated: 2026-09-01 language: de --- # API-Funktion Projekterstellung V1 Diese Funktion stellt die Projekterstellung (addProject) via Schnittstelle (API) bereit. Hierbei handelt es sich um die 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 ```json { "data": { "client": { "firstName": "Max", "lastName": "Mustermann", "email": "max@beispiel.de", "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) ```json { "message": "Project added successfully" } ``` ### Fehlerhafte Authentifizierung (HTTP 401) ```json { "error": "Unauthorized" } ``` ### Fehlende oder ungültige Daten (HTTP 400) ```json { "error": { "message": "Missing or invalid mandatory fields: client.lastName, building.address.street, ..." } } ``` ### Fehler beim Import (HTTP 500) ```json { "error": "Reference: WEBSITE, Error: [Fehlermeldung]" } ``` ## Technische Details ### Funktionsablauf 1. **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 2. **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` 3. **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 4. **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 5. **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 ```bash curl -X POST "https://eba-api.azurewebsites.net/addProject?token=eyJhbGc..." \ -H "Content-Type: application/json" \ -d '{ "data": { "client": { "firstName": "Max", "lastName": "Mustermann", "email": "max@beispiel.de", "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 1. **Ungültiges Token**: Überprüfen Sie, ob das Token korrekt generiert wurde und nicht abgelaufen ist 2. **Fehlende Pflichtfelder**: Stellen Sie sicher, dass alle erforderlichen Felder vorhanden sind 3. **Ungültiges UUID-Format**: Die `templateId` muss im korrekten UUID-Format vorliegen 4. **Template nicht gefunden**: Die angegebene `templateId` existiert nicht in der Organisation 5. **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