Kostenstellen-Admin-API
Verwalten Sie die gültigen Projektcodes eines Tenants und den Schalter zur Kostenstellenvalidierung.
Bereich
Admin-API zum Verwalten der gültigen Projektcodes eines Mandanten und des Schalters zur Kostenstellenvalidierung: wie man sich authentifiziert, die CRUD-Endpunkte für Einzelcode und Batch, Massenimport per CSV/JSON mit Trockenlauf-Vorschau, Wertvalidierung und den Konfigurationsschalter.
Die Referenz pro Endpunkt ist hier absichtlich komprimiert. Die stets aktuelle Live-Referenz finden Sie unter analytics.theblockbrain.ai/docs (Scalar, automatisch aus der OpenAPI-Spezifikation gerendert). Diese Seite behandelt die Beschreibung, das Authentifizierungsmodell sowie Anfrage-/Antwortbeispiele.
Überblick
Die Cost Center Admin API verwaltet die Liste gültiger Projektcodes und den Schalter zur Kostenstellenvalidierung. Codes gelangen über den REST-Einzelcode-Endpunkt, die JSON-Batch-Endpunkte oder einen Massenimport per CSV/JSON hinein, und jeder mögliche Wert kann gegen die aktiven Codes des Mandanten geprüft werden.
Basis-URL: https://analytics.theblockbrain.ai
Basispfad: /api/v1/admin/cb-limit/cost-center
Basispfad
/api/v1/admin/cb-limit/cost-center
Host
https://analytics.theblockbrain.ai
Authentifizierung
Bearer JWT oder API-Schlüssel (sk-), Rolle admin. Der betroffene Mandant wird aus dem Token abgeleitet.
Wann wird Validierung erzwungen? Nur wenn der Validierungsschalter des Mandanten aktiviert ist (siehe
PUT /config) und mindestens ein aktiver Code konfiguriert ist. Andernfalls wird jeder Wert akzeptiert. Jeder JSON-Batch-Endpunkt akzeptiert bis zu 10,000 Codes pro Anfrage. Verwenden Sie/importfür größere Datenmengen.
API-Zusammenfassung
Jeder Endpunkt, den die Cost Center Admin API bereitstellt. Die Pfade sind relativ zum Basispfad /api/v1/admin/cb-limit/cost-center. Die vollständigen Anfrage- und Antwortdetails finden Sie in Scalar.
Codes
GET
/codes
Listet die Projektcodes des Mandanten auf (seitengesteuert, durchsuchbar, sortierbar).
Codes
POST
/codes
Einen einzelnen Projektcode hinzufügen oder aktualisieren (idempotentes Upsert).
Codes
DELETE
/codes
Einen Projektcode anhand seines Werts löschen.
Codes
POST
/codes/batch
Viele Codes in einer Anfrage hinzufügen oder aktualisieren.
Codes
POST
/codes/batch-set-active
Viele Codes aktivieren oder deaktivieren (pausieren oder fortsetzen).
Codes
POST
/codes/batch-delete
Viele Codes in einer Anfrage löschen.
Validierung
POST
/validate
Einen Wert gegen die aktiven Codes des Mandanten prüfen.
Import
POST
/import
Codes massenhaft aus einer CSV- oder JSON-Datei importieren.
Import
POST
/import/preview
Einen Import als Trockenlauf ausführen und jede Zeile klassifizieren.
Konfiguration
GET
/config
Den Validierungsschalter lesen.
Konfiguration
PUT
/config
Den Validierungsschalter ein- oder ausschalten.
Authentifizierung
Jeder Endpunkt erwartet ein Bearer-Token im Authorization -Header:
Es werden zwei Arten von Anmeldedaten akzeptiert, und beide laufen über denselben Header:
Zitadel JWT
ein JWT (header.payload.signature)
Gegen Zitadel verifiziert (JWKS, mit Token-Introspektion als Fallback). Dies ist der bestehende Access-Token-Pfad.
API-Schlüssel
sk- präfixierter Schlüssel
Per Introspektion über Blocky geprüft. Der Schlüssel autorisiert über seine eigene Rolle, daher muss er die admin Rolle tragen, dieselbe Hürde, die auch ein Benutzer-Token nehmen muss.
Jedes folgende Beispiel verwendet
$TOKEN, der beide Anmeldedaten enthalten kann. Ein fehlendes oder fehlerhaftes Token gibt401, und ein Token, dessen Rolle unter admin gibt zurück403.
Gemeinsame Schemas
ProjectCode
Bezeichnung ist nullable. Quelle ist eines von rest-api, csv-import, json-import, admin-manual. Codes stimmen unabhängig von der Groß-/Kleinschreibung überein (getrimmt, kleingeschrieben), und die angezeigte Schreibweise ist die zuletzt gespeicherte.
Problem (422, application/problem+json)
Wird nur zurückgegeben von POST /validate wenn der Wert keinem aktiven Code entspricht. Alle anderen Fehler geben einen einfachen { "error": "…" } JSON-Body zurück.
Codes
GET /codes
Listet die Projektcodes des Mandanten auf. Seitengesteuerte Liste mit Gesamtanzahl. Die Admin-Ansicht zeigt auch pausierte Codes. Standardmäßig wird zuerst nach den neuesten sortiert.
Query-Parameter
search
string
Nein
Groß-/Kleinschreibung-unabhängige Teilzeichenfolgenübereinstimmung auf Code oder Bezeichnung. Mindestlänge 1.
activeOnly
"true" | "false"
Nein
false
Übergeben Sie true um pausierte Codes auszublenden (das macht das Dropdown).
von
Datum (ISO)
Nein
Inklusive untere Grenze für createdAt.
bis
Datum (ISO)
Nein
Exklusive obere Grenze für createdAt.
page
Ganzzahl ≥ 1
Nein
1
Seitennummer ab 1.
pageSize
Ganzzahl 1..100
Nein
25
Zeilen pro Seite. Werte über 100 liefern 400 zurück.
sortBy
code | createdAt | active
Nein
createdAt
Sortierspalte.
sortOrder
asc | desc
Nein
desc
Sortierreihenfolge.
Antworten
200
{ items, totalCount, page, pageSize }
Seitengesteuerte Projektcodes.
400
{ error }
Ungültige Query-Parameter.
401
Fehlendes oder ungültiges Token.
403
Die Berechtigung cost-controls fehlt.
Anfrage
Antwort (200)
POST /codes
Einen einzelnen Projektcode hinzufügen oder aktualisieren. Idempotentes Upsert für den Code ohne Berücksichtigung der Groß-/Kleinschreibung. Dies ist der Endpunkt, den die Automatisierung eines Clients aufruft, um Codes synchron zu halten: beim Projektstart anlegen, mit active: falsepausieren. Das erneute Hinzufügen eines Codes aktualisiert seine Schreibweise, Bezeichnung und sein Active-Flag, behält aber seine ID und Audit-Spalten bei.
Das Weglassen von
activesetzt es zurück auftrue, sodass ein erneutes Hinzufügen einen pausierten Code reaktiviert.
Body · application/json
code
string 1..256
Ja
Der Projektcode. Vor dem Speichern getrimmt.
Bezeichnung
string ≤ 512
Nein
Menschenlesbare Bezeichnung. Standardmäßig null.
active
boolean
Nein
Standardmäßig true. Setzen Sie false auf, um zu pausieren, ohne zu löschen.
Antworten
200
ProjectCode
Der per Upsert gespeicherte Code.
400
{ error }
Code fehlt, ist leer oder zu lang.
401 / 403
Nicht autorisiert oder verboten.
Anfrage
Antwort (200)
DELETE /codes
Einen Projektcode löschen. Löscht den passenden Code für den aufrufenden Mandanten hart (case-insensitive). Die Automatisierung des Clients ruft dies auf, wenn ein Projekt abgeschlossen wird. code Der zu löschende Codewert. Mindestlänge 1.
Query-Parameter
code
string
Ja
{ "deleted": true }
Antworten
200
Eine Zeile wurde entfernt.
Eine Zeile wurde entfernt.
400
{ error }
Der code Query-Parameter fehlt.
404
{ error }
Kein Code stimmte überein.
401 / 403
Nicht autorisiert oder verboten.
Anfrage
POST /codes/batch
Projektcodes in Batch hinzufügen oder aktualisieren. Das Mehrfach-Code-Pendant zu POST /codes. Upsertet viele Codes in einer einzigen JSON-Anfrage (idempotent, ohne Berücksichtigung der Groß-/Kleinschreibung). Jeder Eintrag trägt seine eigene Bezeichnung und active (Standard ist true). der erste gewinnt (genauso wie beim Dateiimport). Gibt die Anzahl der geschriebenen eindeutigen Codes zurück. Verwenden Sie /import für sehr große Dateiladungen.
Body · application/json
codes
Array 1..10000
Ja
Nicht leeres Array von Code-Einträgen.
codes[].code
string 1..256
Ja
Der Projektcode.
codes[].label
string ≤ 512
Nein
Menschenlesbare Bezeichnung.
codes[].active
boolean
Nein
Standardmäßig true.
Antworten
200
{ "upserted": number }
Anzahl der geschriebenen eindeutigen Codes.
400
{ error }
Leeres Array, mehr als 10.000 Einträge oder ein leerer/zu großer Code.
401 / 403
Nicht autorisiert oder verboten.
Anfrage
Antwort (200)
POST /codes/batch-set-active
Projektcodes in Batch aktivieren oder deaktivieren. Ändert nur das active Flag jedes aufgelisteten Codes (case-insensitive). Im Gegensatz zu POST /codesschreibt es niemals Bezeichnung oder Quelle neu, sodass ein Mehrfachauswahl-Pausieren oder -Fortsetzen die Anzeigemetadaten jedes Codes unverändert lässt. Durch Deaktivieren werden Codes pausiert: Sie hören auf zu validieren und bleiben im Dropdown, ohne gelöscht zu werden. Gibt die Anzahl der aktualisierten vorhandenen Codes zurück (nicht vorhandene Codes werden ignoriert).
Body · application/json
codes
Array[] 1..10000
Ja
Nicht leeres Array von Codewerten, jeweils 1..256 Zeichen.
active
boolean
Ja
true zum Aktivieren, false zum Pausieren.
Antworten
200
{ "updated": number }
Anzahl der aktualisierten vorhandenen Codes.
400
{ error }
Leeres Array, fehlender oder nicht-boolescher activeWert oder ein zu großer Code.
401 / 403
Nicht autorisiert oder verboten.
Anfrage
Antwort (200)
POST /codes/batch-delete
Projektcodes in Batch löschen. Löscht jeden aufgelisteten Code (case-insensitive) in einer Anfrage hart. Unterstützt das Mehrfachauswahl-Löschen der Admin-Oberfläche. Gibt die Anzahl der tatsächlich entfernten Codes zurück, die geringer sein kann als angefordert, wenn einige Codes nicht existierten.
Body · application/json
codes
Array[] 1..10000
Ja
Nicht leeres Array von Codewerten, jeweils 1..256 Zeichen.
Antworten
200
{ "deleted": number }
Anzahl der tatsächlich entfernten Codes.
400
{ error }
Leeres Array, mehr als 10.000 Einträge oder ein zu großer Code.
401 / 403
Nicht autorisiert oder verboten.
Anfrage
Antwort (200)
Validierung
POST /validate
Einen Projektcode validieren. Gibt { "valid": true } zurück, wenn der Wert einem der aktiven Codes des Mandanten entspricht. Die Übereinstimmung ist nicht case-sensitiv und trimmt Leerzeichen. Ein pausierter Code gilt als ungültig.
Body · application/json
Wert
string
Ja
Der zu prüfende Wert. Mindestlänge nach dem Trimmen 1.
Feld
string
Nein
Im Vertrag vorhanden. Derzeit wird nur project-code validiert.
Antworten
200
{ "valid": true }
Der Wert entspricht einem aktiven Code.
400
{ error }
Wert fehlt oder ist leer.
422
Problem (problem+json)
Der Wert ist kein gültiger Projektcode.
401 / 403
Nicht autorisiert oder verboten.
Anfrage
Antwort (422)
Import
POST /import
Projektcodes aus einer CSV- oder JSON-Datei importieren. Multipart-Upload. Codes werden getrimmt, leere Zeilen übersprungen und doppelte Einträge in der Datei case-insensitive zusammengeführt (der erste gewinnt). Jeder Code wird per Upsert gespeichert, sodass ein erneuter Import idempotent ist. Importierte Codes werden immer aktiviert. Eine Zeile, deren Code länger als 256 Zeichen ist oder deren Bezeichnung länger als 512 Zeichen ist, wird als Fehlerzeile gemeldet und nicht geschrieben (entspricht den API-Feldgrenzen). Maximal 5 MB und 200.000 Zeilen.
Body · multipart/form-data
Datei
binär
Ja
CSV (Kopfzeile mit einer code Spalte, optional Bezeichnung) oder JSON.
Format
"csv" | "json"
Ja
Wie die Datei geparst werden soll.
Akzeptierte JSON-Strukturen
Antworten
200
{ imported, duplicatesInFile, errors[] }
Importzusammenfassung. Jeder Fehler enthält { row, code, reason }.
400
{ error }
Datei fehlt, falsches Format oder nicht parsbar (keine code Spalte, ungültiges JSON, falsche Struktur).
413
{ error }
Die Datei überschreitet das Größen- oder Zeilenlimit.
401 / 403
Nicht autorisiert oder verboten.
Anfrage
Antwort (200)
POST /import/preview
Vorschau eines CSV/JSON-Imports, ohne etwas zu schreiben. Analysiert die Datei und klassifiziert jede Zeile in Dateireihenfolge (neu, Aktualisierung, Duplikat, Fehler) damit der Admin vor dem Import prüfen kann. Eine Zeile ist ein Fehler wenn ihr Code leer ist oder ihr Code/Label die Feldgrenzen überschreitet (256 / 512). Aktualisierung gegenüber neu wird gegen die vorhandenen Codes des Mandanten aufgelöst. Schreibt nichts. Die Einträge Array ist auf 2000 Zeilen begrenzt, aber die Zusammenfassung zählt jede Zeile.
Body · multipart/form-data
Datei
binär
Ja
Gleiche Dateistrukturen wie /import.
Format
"csv" | "json"
Ja
Wie die Datei geparst werden soll.
Antworten
200
{ entries[], totalRows, truncated, summary }
Klassifizierung pro Zeile plus eine Zusammenfassung über alle Zeilen.
400
{ error }
Datei fehlt, falsches Format oder nicht analysierbar.
413
{ error }
Die Datei überschreitet das Größen- oder Zeilenlimit.
401 / 403
Nicht autorisiert oder verboten.
Antwort (200)
Konfiguration
GET /config
Ruft den Schalter zur Kostenstellenvalidierung des Mandanten ab. Gibt zurück, ob die Validierung für den aufrufenden Mandanten aktiviert ist. Ein Mandant ohne Einstellungsdatensatz meldet false.
Antworten
200
{ "validationEnabled": boolean }
Schalterzustand.
401 / 403
Nicht autorisiert oder verboten.
Anfrage
Antwort (200)
PUT /config
Setzt den Schalter zur Kostenstellenvalidierung des Mandanten. Schaltet die Validierung ein oder aus. Wenn sie erstmals aktiviert wird, wird aus der Systemvorgabe ein Einstellungsdatensatz angelegt. Beim Deaktivieren oder erneuten Aktivieren werden nur dieser Schalter und die Audit-Spalten aktualisiert und alle anderen Konfigurationen bleiben erhalten. Die Validierung greift erst, wenn der Schalter aktiviert ist und mindestens ein aktiver Code konfiguriert ist.
Body · application/json
validationEnabled
boolean
Ja
Der neue Schalterzustand.
Antworten
200
{ "validationEnabled": boolean }
Aktualisierter Schalterzustand.
400
{ error }
validationEnabled fehlt oder ist kein boolescher Wert.
401 / 403
Nicht autorisiert oder verboten.
Anfrage
Zuletzt aktualisiert