curl --request POST \
  --url https://api.comstruct.com/v1/projects \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "title": "Highway Construction Project",
  "project_number": "HCP-2024-001",
  "external_id": "EXT-2024-001",
  "description": "Construction of highway section A1-A2",
  "region": "Bavaria",
  "active": true
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "external_id": "EXT-001",
  "title": "Example Site",
  "project_number": "23423420",
  "description": "<string>",
  "region": "Bavaria",
  "project_region_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "active": true,
  "latitude": 48.1351,
  "longitude": 11.582,
  "alternative_project_number": "<string>",
  "status": "<string>",
  "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "address": {
    "address": "<string>",
    "city": "<string>",
    "country": "<string>",
    "house_number": "<string>",
    "zip": "<string>"
  },
  "legal_entity": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "title": "<string>",
    "number": "<string>"
  },
  "project_invites": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "email": "jsmith@example.com",
      "role": "<string>",
      "role_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "tenant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ]
}

Projekte

Projekt erstellen oder aktualisieren

Erforderliche Berechtigungen: projects:write, users:read, roles:read, tenant_settings:read

Erstellt ein neues Projekt oder aktualisiert ein bestehendes Projekt. Dieser Endpunkt führt eine Upsert-Operation basierend auf dem external_id-Feld (falls vorhanden) oder der project_number durch.

Hauptfunktionen:

Upsert-Logik: Wenn external_id angegeben ist und ein Projekt mit dieser ID existiert, wird es aktualisiert. Andernfalls wird project_number für den Abgleich verwendet. Wenn keine Übereinstimmung gefunden wird, wird ein neues Projekt erstellt.
Benutzerverwaltung: Behandelt automatisch Benutzereinladungen und Rollenzuweisungen für Projektteammitglieder.
Regionszuordnung: Das region-Feld kann verwendet werden, um das Projekt einer Projektregion zuzuordnen.
Buchungskreis-Zuordnung: Das legal_entity_number-Feld kann verwendet werden, um das Projekt einem Buchungskreis zuzuordnen.
Koordinaten: Optionale latitude und longitude setzen den geografischen Standort. Weglassen belässt den gespeicherten Wert; null löscht ihn.
Validierung: Alle erforderlichen Felder (title, project_number) werden vor der Verarbeitung validiert.

Best Practices:

Geben Sie external_id für zuverlässige Upsert-Operationen an
Verwenden Sie region oder project_region_id für die Projektregionszuordnung
Verwenden Sie legal_entity_number oder legal_entity_id für die Buchungskreis-Zuordnung
Fügen Sie vollständige Adressinformationen hinzu, wenn verfügbar, für besseres Projektmanagement
Übergeben Sie latitude und longitude gemeinsam, wenn der Standort bekannt ist
Stellen Sie sicher, dass Rollennamen in project_invites mit bestehenden Rollen in Ihrem Mandanten übereinstimmen

POST

projects

curl --request POST \
  --url https://api.comstruct.com/v1/projects \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "title": "Highway Construction Project",
  "project_number": "HCP-2024-001",
  "external_id": "EXT-2024-001",
  "description": "Construction of highway section A1-A2",
  "region": "Bavaria",
  "active": true
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "external_id": "EXT-001",
  "title": "Example Site",
  "project_number": "23423420",
  "description": "<string>",
  "region": "Bavaria",
  "project_region_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "active": true,
  "latitude": 48.1351,
  "longitude": 11.582,
  "alternative_project_number": "<string>",
  "status": "<string>",
  "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "address": {
    "address": "<string>",
    "city": "<string>",
    "country": "<string>",
    "house_number": "<string>",
    "zip": "<string>"
  },
  "legal_entity": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "title": "<string>",
    "number": "<string>"
  },
  "project_invites": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "email": "jsmith@example.com",
      "role": "<string>",
      "role_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "tenant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ]
}

Autorisierungen

X-API-Key

string

header

erforderlich

API-Schlüssel zur Authentifizierung. Kontaktieren Sie Ihren Customer Success Manager, um einen API-Schlüssel zu erhalten.

Jeder Endpunkt erfordert spezifische Berechtigungen (Scopes); die erforderlichen Scopes werden pro Endpunkt angezeigt.

Scopes

projects:write

users:read

roles:read

tenant_settings:read

Body

application/json

title

string

erforderlich

Der Titel des Projekts

Beispiel:

"Example Site"

project_number

string

erforderlich

Die Projektnummer (erforderlich)

Beispiel:

"23423420"

external_id

string

Die externe Kennung des Projekts. Muss innerhalb des Kunden eindeutig sein. Wird für Upsert-Operationen verwendet.

Beispiel:

"EXT-001"

description

string

Eine Beschreibung des Projekts

region

string

Die Regionsnummer, in der sich das Projekt befindet, wird für Filterung und Projektregionssuche verwendet

Beispiel:

"Bavaria"

project_region_id

string<uuid>

Direkte Referenz auf eine Projektregions-ID (Alternative zur Regionssuche)

legal_entity_id

string<uuid>

Direkte Referenz auf eine Buchungskreis-ID

legal_entity_number

string

Buchungskreisnummer zum Nachschlagen und Verknüpfen des Buchungskreises

alternative_project_number

string

Alternative Projektnummer zur Referenz

active

boolean

Steuert, ob das Projekt aktiv ist

latitude

number | null

Geografische Breite des Projektstandorts. Weglassen belässt den gespeicherten Wert; null löscht ihn.

Erforderlicher Bereich: -90 <= x <= 90

Beispiel:

48.1351

longitude

number | null

Geografische Länge des Projektstandorts. Weglassen belässt den gespeicherten Wert; null löscht ihn.

Erforderlicher Bereich: -180 <= x <= 180

Beispiel:

11.582

address

object

Die Adressdetails des Projekts

Show child attributes

project_invites

object[]

Benutzereinladungen für das Projekt

Show child attributes

Antwort

Projekt erfolgreich erstellt oder aktualisiert

string<uuid>

Die eindeutige Kennung des Projekts

external_id

string

Die externe Kennung des Projekts

Beispiel:

"EXT-001"

title

string

Der Titel des Projekts

Beispiel:

"Example Site"

project_number

string | null

Die Projektnummer

Beispiel:

"23423420"

description

string

Eine Beschreibung des Projekts

region

string | null

Titel der verknüpften Projektregion. Ohne Verknüpfung der gespeicherte Regionstext, sonst null.

Beispiel:

"Bavaria"

project_region_id

string<uuid> | null

Die ID der verknüpften Projektregion

active

boolean | null

Steuert, ob das Projekt aktiv ist

latitude

number | null

Geografische Breite des Projektstandorts

Erforderlicher Bereich: -90 <= x <= 90

Beispiel:

48.1351

longitude

number | null

Geografische Länge des Projektstandorts

Erforderlicher Bereich: -180 <= x <= 180

Beispiel:

11.582

alternative_project_number

string | null

Alternative Projektnummer zur Referenz, z. B. aus SAP

status

string

Der Status des Projekts

customer_id

string<uuid>

Die eindeutige Kennung des Kunden

address

object

Die Adressdetails des Projekts

Show child attributes

legal_entity

object | null

Der dem Projekt zugeordnete Buchungskreis

Show child attributes

project_invites

object[]

Dem Projekt zugewiesene Benutzereinladungen

Show child attributes

Übersicht

Projekte

Lieferungen

Rechnungen

Rechnungs-Dimensionen

Lieferanten

Bestellungen

Bestellungen (Lieferanten)

Stammdaten

Q-Point Integration

Workflows

Kalender

IDS Aufträge

Projekt erstellen oder aktualisieren

Autorisierungen

Scopes

Body

Antwort