curl --request POST \
--url https://api.comstruct.com/v1/project-regions \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
[
{
"title": "North Region",
"number": "REG-NORTH"
}
]
'[
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"title": "North Region",
"number": "REG-NORTH",
"description": "Nordregion mit Lagern A und B",
"tenant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"legal_entity_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"parent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
]Projektregionen erstellen/aktualisieren
Erforderliche Berechtigungen: project_regions:write
Erstellt oder aktualisiert eine oder mehrere Projektregionen für den aktuellen Mandanten.
Verwendet das number-Feld zum Abgleich bestehender Projektregionen für Aktualisierungen.
titlewird bei bestehenden Projektregionen immer überschrieben.descriptionist optional: Weglassen behält die gespeicherte Beschreibung, eine Zeichenkette ersetzt sie undnulllöscht sie.legal_entity_idundparent_idsind optional und werden bei bestehenden Projektregionen nur aktualisiert, wenn jeder Eintrag der Anfrage das jeweilige Feld enthält. Ein Wert ersetzt die Zuordnung,nullentfernt sie.legal_entity_idmuss ein Buchungskreis des Mandanten sein und erfordert die Funktion „Buchungskreise mit Regionen verknüpfen“. Ist sie nicht aktiviert, wird die Anfrage mit403 Forbiddenabgelehnt.parent_idmuss eine bestehende Projektregion des Mandanten sein. Unbekannte IDs und Zuordnungen, die einen Zyklus in der Hierarchie erzeugen würden, werden mit400 Bad Requestabgelehnt.- Enthält die Anfrage dieselbe
numbermehrfach, wird nur der erste Eintrag übernommen. - Felder, die nicht im Schema definiert sind, werden mit
400 Bad Requestabgelehnt.
curl --request POST \
--url https://api.comstruct.com/v1/project-regions \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
[
{
"title": "North Region",
"number": "REG-NORTH"
}
]
'[
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"title": "North Region",
"number": "REG-NORTH",
"description": "Nordregion mit Lagern A und B",
"tenant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"legal_entity_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"parent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
]Übersicht
Dieser Endpunkt erstellt neue Projektregionen oder aktualisiert bestehende. Projektregionen helfen dabei, Projekte nach geografischen oder organisatorischen Grenzen zu organisieren. Bestehende Projektregionen werden übernumber abgeglichen.
Feld Region Description
Das Felddescription ist ein optionales Freitextfeld, das zusätzlichen Kontext über die Projektregion bietet. Es ist nützlich für:
- Dokumentation der geografischen Abdeckung (z. B. ‘Nordregion mit Lagern A und B’)
- Organisatorische Hinweise (z. B. ‘Regionalbüro Hamburg, Team Nord’)
- Besondere Bearbeitungshinweise für die Region
number erneut mit der neuen description. Wird description weggelassen, bleibt der gespeicherte Wert erhalten; null löscht ihn.Beispiel: Region mit Description erstellen
[
{
"title": "Nord",
"number": "REG-001",
"description": "Nordregion mit Lagern A und B"
}
]
Beispiel: Region ohne Description erstellen
[
{
"title": "Süd",
"number": "REG-002"
}
]
Beispiel: Description entfernen
[
{
"title": "Nord",
"number": "REG-001",
"description": null
}
]
Übergeordnete Region und Buchungskreis
Mitparent_id ordnen Sie eine Projektregion einer bestehenden übergeordneten Projektregion des Mandanten zu und bilden so eine Hierarchie. Mit legal_entity_id verknüpfen Sie die Projektregion mit einem Buchungskreis des Mandanten (siehe GET /legal-entities).
- Beide Felder sind optional,
nullentfernt die Zuordnung. Bei bestehenden Projektregionen wird ein Feld nur aktualisiert, wenn jeder Eintrag der Anfrage es enthält. Fehlt es in mindestens einem Eintrag, bleiben die gespeicherten Werte aller Einträge unverändert. - Die IDs müssen zum Mandanten gehören. Unbekannte IDs werden mit
400 Bad Requestabgelehnt. - Zuordnungen, die einen Zyklus in der Hierarchie erzeugen würden, werden mit
400 Bad Requestabgelehnt.
legal_entity_id erfordert die Funktion „Buchungskreise mit Regionen verknüpfen“. Ist sie für Ihren Mandanten nicht aktiviert, wird die Anfrage mit 403 Forbidden abgelehnt.Beispiel: Region mit übergeordneter Region und Buchungskreis
[
{
"title": "München",
"number": "REG-MUC",
"parent_id": "22222222-2222-4222-8222-222222222222",
"legal_entity_id": "11111111-1111-4111-8111-111111111111"
}
]
Autorisierungen
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
Body
Der Titel der Projektregion. Wird bei bestehenden Projektregionen immer überschrieben.
"North Region"
Die Nummer/der Code der Projektregion. Eindeutig pro Mandant und Abgleichsschlüssel für Aktualisierungen.
"REG-NORTH"
Optionale Freitext-Beschreibung. Weglassen behält den gespeicherten Wert, null löscht ihn.
"Nordregion mit Lagern A und B"
Die ID eines Buchungskreises des Mandanten (siehe GET /legal-entities), der der Projektregion zugeordnet wird. Erfordert die Funktion „Buchungskreise mit Regionen verknüpfen“; andernfalls wird die Anfrage mit 403 Forbidden abgelehnt. null entfernt die Zuordnung. Wird bei bestehenden Projektregionen nur aktualisiert, wenn alle Einträge der Anfrage das Feld enthalten.
"11111111-1111-4111-8111-111111111111"
Die ID einer bestehenden übergeordneten Projektregion des Mandanten. null entfernt die Zuordnung. Wird bei bestehenden Projektregionen nur aktualisiert, wenn alle Einträge der Anfrage das Feld enthalten. Zyklen in der Hierarchie werden mit 400 Bad Request abgelehnt.
"22222222-2222-4222-8222-222222222222"
Antwort
Projektregionen erfolgreich erstellt oder aktualisiert
Die eindeutige Kennung der Projektregion
Der Titel der Projektregion
"North Region"
Die Nummer/der Code der Projektregion
"REG-NORTH"
Freitext-Beschreibung der Projektregion
"Nordregion mit Lagern A und B"
Die Mandanten-ID
Die ID des zugeordneten Buchungskreises, falls vorhanden
Die ID der übergeordneten Projektregion, falls vorhanden