Riferimento API

Controllo del budget

Se ordini e richieste vengono verificati rispetto ai budget dei centri di costo, e a che punto è ogni budget.

Altro su questa risorsa

Un workspace acquirente può verificare ogni ordine d’acquisto e ogni richiesta d’acquisto rispetto al budget del suo centro di costo per il mese, il trimestre o l’anno in corso. In modalità warn un ordine oltre il budget prosegue con un avviso; in modalità block viene rifiutato con 409 over_budget. La spesa impegnata sono gli ordini approvati non ancora fatturati, e la spesa effettiva sono le fatture approvate. I budget stessi si impostano per centro di costo in Pleaxy.

Ottenere il controllo del budget

Ottiene se i budget vengono verificati e su quale periodo.

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

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Restituisce l’impostazione di controllo del budget del workspace: off, warn o block, e il periodo coperto dai budget.

Qualsiasi membro del workspace acquirente, qualunque sia il suo ruolo negli acquisti.

Campi della risposta

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

    off: i budget non vengono verificati. warn: un ordine o una richiesta oltre il budget del suo centro di costo prosegue con un avviso. block: viene rifiutato con 409 over_budget.

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

    Il periodo coperto da un budget e su cui si conta la spesa.

Errori

  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
GET /v1/workspaces/{regionId}/budget-control
Richiesta
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/budget-control" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Risposta · 200 OK
{
   "mode": "off" | "warn" | "block",
   "period": "month" | "quarter" | "year",
   "updatedAt": "string",
   "updatedBy": "string"
}

Aggiornare il controllo del budget

Modifica se i budget vengono verificati e su quale periodo.

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

Corpo

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

    Facoltativo. Se i budget vengono verificati, e se il superamento avvisa o blocca.

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

    Facoltativo. Il periodo coperto da un budget.

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Modifica l’impostazione di controllo del budget. Vale per gli ordini e le richieste inviati o approvati da quel momento in poi.

Solo sessione con accesso effettuato, con accesso 'edit' alle impostazioni di approvazione o alle fatture. Una chiave API riceve 403 HUMAN_SESSION_REQUIRED.

Campi della risposta

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

    off: i budget non vengono verificati. warn: un ordine o una richiesta oltre il budget del suo centro di costo prosegue con un avviso. block: viene rifiutato con 409 over_budget.

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

    Il periodo coperto da un budget e su cui si conta la spesa.

Errori

  • 400 Bad Request - mode o period non è uno dei valori elencati.
  • 403 Forbidden - Codice HUMAN_SESSION_REQUIRED. Il chiamante non è una persona che ha effettuato l’accesso (per esempio, una chiave API). Non viene salvato nulla.
  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
PATCH /v1/workspaces/{regionId}/budget-control
Richiesta
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"
}
Risposta · 200 OK
{
   "mode": "off" | "warn" | "block",
   "period": "month" | "quarter" | "year",
   "updatedAt": "string",
   "updatedBy": "string"
}

Ottenere lo stato del budget

Ottiene budget e spesa impegnata, effettiva e residua per centro di costo.

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

Parametri

  • costCenterstring

    Solo questo centro di costo. Tutti i centri di costo con budget se assente.

  • datestring

    Un giorno (YYYY-MM-DD) del periodo da consultare. Oggi se assente.

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Restituisce, per il periodo in corso, il budget di ogni centro di costo con budget, la spesa impegnata (ordini approvati non ancora fatturati), la spesa effettiva (fatture approvate) e quanto resta. La spesa senza centro di costo è riportata a parte, come unassigned.

Richiede l’accesso 'view' agli ordini d’acquisto.

Campi della risposta

  • costCenters[].committednumber

    Gli ordini d’acquisto approvati, meno quanto è già stato fatturato su di essi.

  • costCenters[].actualnumber

    Le fatture approvate nel periodo.

  • costCenters[].remainingnumber

    Il budget meno la spesa impegnata e quella effettiva.

  • costCenters[].pendingnumber

    La spesa ancora in attesa di approvazione. Non riduce remaining.

  • costCenters[].unconvertednumber

    Sempre 0; resta per i client meno recenti.

  • unassignedobject

    La spesa del periodo che non indica un centro di costo, nella valuta del workspace; unassignedByCurrency ha una voce per valuta.

Errori

  • 400 Bad Request - date non è un giorno scritto come YYYY-MM-DD.
  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
GET /v1/workspaces/{regionId}/budget-control/status
Richiesta
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/budget-control/status" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Risposta · 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 } ]
}

Verificare il budget

Mostra in anteprima la verifica del budget per un importo su un centro di costo.

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

Corpo

  • amountnumberObbligatorio

    L’importo da verificare.

  • currencystringObbligatorio

    Il codice della valuta dell’importo.

  • costCenterstring

    Il centro di costo a cui l’importo verrebbe imputato.

  • excludeOrderIdstring

    Un ordine d’acquisto da escludere dalla spesa impegnata, quando si verifica una modifica a quell’ordine.

  • blanketboolean

    true: verificare come ordine aperto, che riserva expectedMonthly per ogni mese del periodo fino a validUntil.

  • expectedMonthlynumber

    Con blanket: quanto ci si aspetta che l’ordine spenda ogni mese.

  • validUntilstring

    Con blanket: l’ultimo giorno dell’ordine (YYYY-MM-DD).

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Dice che cosa risponderebbe la verifica del budget per un importo su un centro di costo, rispetto al budget di quel centro di costo nella valuta dell’importo. Non scrive nulla e non rifiuta mai: un importo oltre il budget torna con outcome over, con 200.

Qualsiasi membro del workspace acquirente, qualunque sia il suo ruolo negli acquisti.

Campi della risposta

  • outcomestring

    within: l’importo rientra nel budget. over: supera quanto resta, di overBy. no_budget: il centro di costo non ha un budget in questa valuta. no_rate: non c’è un tasso di cambio per verificarlo. off: i budget non vengono verificati.

Errori

  • 400 Bad Request - amount o currency manca o non è valido.
  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
POST /v1/workspaces/{regionId}/budget-control/check
Richiesta
POST /v1/workspaces/reg_01k5x8p9j3q7vn2mhb4tzc6rde.buyer/budget-control/check
{
   "costCenter": "CC-1000",
   "amount": 12000,
   "currency": "USD"
}
Risposta · 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"
}
Contattaci