API-Referenz

Budgetkontrolle

Ob Bestellungen und Anforderungen gegen Kostenstellenbudgets geprüft werden und wie jedes Budget steht.

Mehr zu dieser Ressource

Ein Käufer-Workspace kann jede Bestellung und jede Bestellanforderung gegen das Budget ihrer Kostenstelle für den laufenden Monat, das laufende Quartal oder Jahr prüfen. Im Modus warn läuft eine Bestellung über dem Budget mit einer Warnung weiter; im Modus block wird sie mit 409 over_budget abgelehnt. Gebundene Ausgaben sind freigegebene Bestellungen, die noch nicht berechnet wurden, und tatsächliche Ausgaben sind freigegebene Rechnungen. Die Budgets selbst werden in Pleaxy je Kostenstelle festgelegt.

Budgetkontrolle abrufen

Ruft ab, ob Budgets geprüft werden und über welchen Zeitraum.

GET/v1/workspaces/{regionId}/budget-control

Rückgabe

200 OK mit dem in der Antwort gezeigten Objekt.

Weitere Details

Gibt die Budgetkontroll-Einstellung des Workspace zurück: off, warn oder block, und den Zeitraum, den Budgets abdecken.

Jedes Mitglied des Käufer-Workspace, unabhängig von seiner Einkaufsrolle.

Antwortfelder

  • mode"off" | "warn" | "block"

    off: Budgets werden nicht geprüft. warn: Eine Bestellung oder Anforderung über dem Budget ihrer Kostenstelle läuft mit einer Warnung weiter. block: Sie wird mit 409 over_budget abgelehnt.

  • period"month" | "quarter" | "year"

    Der Zeitraum, den ein Budget abdeckt und über den Ausgaben gezählt werden.

Fehler

  • 401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.
  • 403 Forbidden - Der Bearer-Token oder API-Schlüssel des Aufrufers gewährt keinen Zugriff auf diesen Workspace (regionId) oder hat nicht die erforderliche Rolle.
GET /v1/workspaces/{regionId}/budget-control
Anfrage
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/budget-control" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Antwort · 200 OK
{
   "mode": "off" | "warn" | "block",
   "period": "month" | "quarter" | "year",
   "updatedAt": "string",
   "updatedBy": "string"
}

Budgetkontrolle aktualisieren

Ändert, ob Budgets geprüft werden und über welchen Zeitraum.

PATCH/v1/workspaces/{regionId}/budget-control

Body

  • mode"off" | "warn" | "block"

    Optional. Ob Budgets geprüft werden und ob eine Überschreitung warnt oder blockiert.

  • period"month" | "quarter" | "year"

    Optional. Der Zeitraum, den ein Budget abdeckt.

Rückgabe

200 OK mit dem in der Antwort gezeigten Objekt.

Weitere Details

Ändert die Budgetkontroll-Einstellung. Sie gilt für Bestellungen und Anforderungen, die von da an eingereicht oder freigegeben werden.

Nur angemeldete Sitzung, mit 'edit'-Zugriff auf die Freigabeeinstellungen oder auf Rechnungen. Ein API-Schlüssel erhält 403 HUMAN_SESSION_REQUIRED.

Antwortfelder

  • mode"off" | "warn" | "block"

    off: Budgets werden nicht geprüft. warn: Eine Bestellung oder Anforderung über dem Budget ihrer Kostenstelle läuft mit einer Warnung weiter. block: Sie wird mit 409 over_budget abgelehnt.

  • period"month" | "quarter" | "year"

    Der Zeitraum, den ein Budget abdeckt und über den Ausgaben gezählt werden.

Fehler

  • 400 Bad Request - mode oder period ist keiner der aufgeführten Werte.
  • 403 Forbidden - Code HUMAN_SESSION_REQUIRED. Der Aufrufer ist keine angemeldete Person (zum Beispiel ein API-Schlüssel). Nichts wird gespeichert.
  • 401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.
  • 403 Forbidden - Der Bearer-Token oder API-Schlüssel des Aufrufers gewährt keinen Zugriff auf diesen Workspace (regionId) oder hat nicht die erforderliche Rolle.
PATCH /v1/workspaces/{regionId}/budget-control
Anfrage
curl -X PATCH "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/budget-control" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
body.json
{
   "mode": "off" | "warn" | "block",
   "period": "month" | "quarter" | "year"
}
Antwort · 200 OK
{
   "mode": "off" | "warn" | "block",
   "period": "month" | "quarter" | "year",
   "updatedAt": "string",
   "updatedBy": "string"
}

Budgetstand abrufen

Ruft Budget sowie gebundene, tatsächliche und verbleibende Ausgaben je Kostenstelle ab.

GET/v1/workspaces/{regionId}/budget-control/status

Parameter

  • costCenterstring

    Nur diese Kostenstelle. Fehlt sie, alle budgetierten Kostenstellen.

  • datestring

    Ein Tag (YYYY-MM-DD) im Zeitraum, der ausgewertet werden soll. Fehlt er, heute.

Rückgabe

200 OK mit dem in der Antwort gezeigten Objekt.

Weitere Details

Gibt für den laufenden Zeitraum das Budget jeder budgetierten Kostenstelle zurück, die gebundenen Ausgaben (freigegebene, noch nicht berechnete Bestellungen), die tatsächlichen Ausgaben (freigegebene Rechnungen) und was verbleibt. Ausgaben ohne Kostenstelle werden getrennt als unassigned ausgewiesen.

Braucht 'view'-Zugriff auf Bestellungen.

Antwortfelder

  • costCenters[].committednumber

    Freigegebene Bestellungen, abzüglich dessen, was bereits gegen sie berechnet wurde.

  • costCenters[].actualnumber

    Freigegebene Rechnungen im Zeitraum.

  • costCenters[].remainingnumber

    Das Budget abzüglich der gebundenen und der tatsächlichen Ausgaben.

  • costCenters[].pendingnumber

    Ausgaben, die noch auf Freigabe warten. Sie verringern remaining nicht.

  • costCenters[].unconvertednumber

    Immer 0; bleibt für ältere Clients erhalten.

  • unassignedobject

    Die Ausgaben des Zeitraums, die keine Kostenstelle nennen, in der Währung des Workspace; unassignedByCurrency hat einen Eintrag je Währung.

Fehler

  • 400 Bad Request - date ist kein Tag in der Schreibweise YYYY-MM-DD.
  • 401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.
  • 403 Forbidden - Der Bearer-Token oder API-Schlüssel des Aufrufers gewährt keinen Zugriff auf diesen Workspace (regionId) oder hat nicht die erforderliche Rolle.
GET /v1/workspaces/{regionId}/budget-control/status
Anfrage
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/budget-control/status" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Antwort · 200 OK
{
   "settings": {
      "mode": "off" | "warn" | "block",
      "period": "month" | "quarter" | "year",
      "updatedAt": "string",
      "updatedBy": "string"
   },
   "period": { "kind": "month" | "quarter" | "year", "start": "string", "end": "string", "fiscalYear": number },
   "currency": "string",
   "costCenters": [
      {
         "costCenter": "string",
         "costCenterName": "string",
         "period": { "kind": "month" | "quarter" | "year", "start": "string", "end": "string" },
         "currency": "string",
         "budget": number,
         "committed": number,
         "actual": number,
         "remaining": number,
         "pending": number,
         "unconverted": number
      }
   ],
   "unassigned": { "committed": number, "actual": number, "pending": number, "unconverted": number },
   "unassignedByCurrency": [ { "currency": "string", "committed": number, "actual": number, "pending": number, "unconverted": number } ]
}

Budget prüfen

Zeigt vorab die Budgetprüfung für einen Betrag auf einer Kostenstelle.

POST/v1/workspaces/{regionId}/budget-control/check

Body

  • amountnumberPflicht

    Der zu prüfende Betrag.

  • currencystringPflicht

    Der Währungscode des Betrags.

  • costCenterstring

    Die Kostenstelle, auf die der Betrag gebucht würde.

  • excludeOrderIdstring

    Eine Bestellung, die bei den gebundenen Ausgaben außen vor bleibt, wenn eine Änderung an dieser Bestellung geprüft wird.

  • blanketboolean

    true: als Rahmenbestellung prüfen, die expectedMonthly für jeden Monat des Zeitraums bis validUntil reserviert.

  • expectedMonthlynumber

    Mit blanket: was die Bestellung voraussichtlich pro Monat ausgibt.

  • validUntilstring

    Mit blanket: der letzte Tag der Bestellung (YYYY-MM-DD).

Rückgabe

200 OK mit dem in der Antwort gezeigten Objekt.

Weitere Details

Sagt, was die Budgetprüfung für einen Betrag auf einer Kostenstelle ergeben würde, gegen das Budget dieser Kostenstelle in der Währung des Betrags. Schreibt nichts und lehnt nie ab: Ein Betrag über dem Budget kommt mit outcome over und 200 zurück.

Jedes Mitglied des Käufer-Workspace, unabhängig von seiner Einkaufsrolle.

Antwortfelder

  • outcomestring

    within: Der Betrag passt ins Budget. over: Er übersteigt den Rest um overBy. no_budget: Die Kostenstelle hat kein Budget in dieser Währung. no_rate: Es gibt keinen Wechselkurs für die Prüfung. off: Budgets werden nicht geprüft.

Fehler

  • 400 Bad Request - amount oder currency fehlt oder ist ungültig.
  • 401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.
  • 403 Forbidden - Der Bearer-Token oder API-Schlüssel des Aufrufers gewährt keinen Zugriff auf diesen Workspace (regionId) oder hat nicht die erforderliche Rolle.
POST /v1/workspaces/{regionId}/budget-control/check
Anfrage
POST /v1/workspaces/reg_01k5x8p9j3q7vn2mhb4tzc6rde.buyer/budget-control/check
{
   "costCenter": "CC-1000",
   "amount": 12000,
   "currency": "USD"
}
Antwort · 200 OK
{
   "outcome": "over",
   "mode": "warn",
   "period": { "kind": "quarter", "start": "2026-10-01", "end": "2026-12-31" },
   "costCenter": "CC-1000",
   "currency": "USD",
   "budget": 50000,
   "committed": 31000,
   "actual": 10500,
   "remaining": 8500,
   "amount": 12000,
   "overBy": 3500,
   "checkedAt": "2026-11-11T15:04:05.000Z"
}
Kontakt aufnehmen