Référence de l’API

Contrôle budgétaire

Si les commandes et les demandes sont comparées aux budgets des centres de coûts, et où en est chaque budget.

En savoir plus sur cette ressource

Un espace de travail acheteur peut comparer chaque bon de commande et chaque demande d’achat au budget de son centre de coûts pour le mois, le trimestre ou l’année en cours. En mode warn, une commande qui dépasse le budget se poursuit avec un avertissement ; en mode block, elle est refusée avec 409 over_budget. Les dépenses engagées sont les commandes approuvées qui ne sont pas encore facturées, et les dépenses réelles sont les factures approuvées. Les budgets eux-mêmes se définissent par centre de coûts dans Pleaxy.

Obtenir le contrôle budgétaire

Obtient si les budgets sont contrôlés, et sur quelle période.

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

Retour

200 OK avec l’objet présenté dans la réponse.

Plus de détails

Renvoie le réglage de contrôle budgétaire de l’espace de travail : off, warn ou block, et la période que couvrent les budgets.

Tout membre de l’espace de travail acheteur, quel que soit son rôle achats.

Champs de la réponse

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

    off : les budgets ne sont pas contrôlés. warn : une commande ou une demande qui dépasse le budget de son centre de coûts se poursuit avec un avertissement. block : elle est refusée avec 409 over_budget.

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

    La période que couvre un budget et sur laquelle les dépenses sont comptées.

Erreurs

  • 401 Unauthorized - Aucun identifiant n’a été fourni, ou la valeur du jeton Bearer / de X-Api-Key est manquante, invalide, expirée ou révoquée.
  • 403 Forbidden - Le jeton Bearer ou la clé API de l’appelant ne donne pas accès à cet espace de travail (regionId), ou n’a pas le rôle requis.
GET /v1/workspaces/{regionId}/budget-control
Requête
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/budget-control" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Réponse · 200 OK
{
   "mode": "off" | "warn" | "block",
   "period": "month" | "quarter" | "year",
   "updatedAt": "string",
   "updatedBy": "string"
}

Mettre à jour le contrôle budgétaire

Modifie si les budgets sont contrôlés, et sur quelle période.

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

Corps

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

    Facultatif. Si les budgets sont contrôlés, et si un dépassement avertit ou bloque.

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

    Facultatif. La période que couvre un budget.

Retour

200 OK avec l’objet présenté dans la réponse.

Plus de détails

Modifie le réglage de contrôle budgétaire. Il s’applique aux commandes et aux demandes soumises ou approuvées à partir de ce moment.

Session connectée uniquement, avec l’accès 'edit' aux paramètres d’approbation ou aux factures. Une clé API reçoit 403 HUMAN_SESSION_REQUIRED.

Champs de la réponse

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

    off : les budgets ne sont pas contrôlés. warn : une commande ou une demande qui dépasse le budget de son centre de coûts se poursuit avec un avertissement. block : elle est refusée avec 409 over_budget.

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

    La période que couvre un budget et sur laquelle les dépenses sont comptées.

Erreurs

  • 400 Bad Request - mode ou period n’est pas l’une des valeurs indiquées.
  • 403 Forbidden - Code HUMAN_SESSION_REQUIRED. L’appelant n’est pas une personne connectée (par exemple, une clé API). Rien n’est enregistré.
  • 401 Unauthorized - Aucun identifiant n’a été fourni, ou la valeur du jeton Bearer / de X-Api-Key est manquante, invalide, expirée ou révoquée.
  • 403 Forbidden - Le jeton Bearer ou la clé API de l’appelant ne donne pas accès à cet espace de travail (regionId), ou n’a pas le rôle requis.
PATCH /v1/workspaces/{regionId}/budget-control
Requête
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"
}
Réponse · 200 OK
{
   "mode": "off" | "warn" | "block",
   "period": "month" | "quarter" | "year",
   "updatedAt": "string",
   "updatedBy": "string"
}

Obtenir l’état du budget

Obtient le budget et les dépenses engagées, réelles et restantes par centre de coûts.

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

Paramètres

  • costCenterstring

    Uniquement ce centre de coûts. Tous les centres de coûts budgétés en son absence.

  • datestring

    Un jour (YYYY-MM-DD) de la période à consulter. Aujourd’hui en son absence.

Retour

200 OK avec l’objet présenté dans la réponse.

Plus de détails

Renvoie, pour la période en cours, le budget de chaque centre de coûts budgété, les dépenses engagées (commandes approuvées pas encore facturées), les dépenses réelles (factures approuvées) et ce qui reste. Les dépenses sans centre de coûts sont indiquées à part, dans unassigned.

Nécessite l’accès 'view' aux bons de commande.

Champs de la réponse

  • costCenters[].committednumber

    Les bons de commande approuvés, moins ce qui a déjà été facturé sur eux.

  • costCenters[].actualnumber

    Les factures approuvées sur la période.

  • costCenters[].remainingnumber

    Le budget moins les dépenses engagées et réelles.

  • costCenters[].pendingnumber

    Les dépenses encore en attente d’approbation. Elles ne réduisent pas remaining.

  • costCenters[].unconvertednumber

    Toujours 0 ; conservé pour les anciens clients.

  • unassignedobject

    Les dépenses de la période qui n’indiquent aucun centre de coûts, dans la devise de l’espace de travail ; unassignedByCurrency a une entrée par devise.

Erreurs

  • 400 Bad Request - date n’est pas un jour écrit sous la forme YYYY-MM-DD.
  • 401 Unauthorized - Aucun identifiant n’a été fourni, ou la valeur du jeton Bearer / de X-Api-Key est manquante, invalide, expirée ou révoquée.
  • 403 Forbidden - Le jeton Bearer ou la clé API de l’appelant ne donne pas accès à cet espace de travail (regionId), ou n’a pas le rôle requis.
GET /v1/workspaces/{regionId}/budget-control/status
Requête
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/budget-control/status" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Réponse · 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 } ]
}

Vérifier le budget

Donne un aperçu du contrôle budgétaire pour un montant sur un centre de coûts.

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

Corps

  • amountnumberObligatoire

    Le montant à vérifier.

  • currencystringObligatoire

    Le code de devise du montant.

  • costCenterstring

    Le centre de coûts sur lequel le montant serait imputé.

  • excludeOrderIdstring

    Un bon de commande à exclure des dépenses engagées, pour vérifier une modification de cette commande.

  • blanketboolean

    true : vérifier comme une commande ouverte, qui réserve expectedMonthly pour chaque mois de la période jusqu’à validUntil.

  • expectedMonthlynumber

    Avec blanket : ce que la commande devrait dépenser chaque mois.

  • validUntilstring

    Avec blanket : le dernier jour de la commande (YYYY-MM-DD).

Retour

200 OK avec l’objet présenté dans la réponse.

Plus de détails

Indique ce que répondrait le contrôle budgétaire pour un montant sur un centre de coûts, par rapport au budget de ce centre de coûts dans la devise du montant. Il n’écrit rien et ne refuse jamais : un montant qui dépasse le budget revient avec outcome over, avec 200.

Tout membre de l’espace de travail acheteur, quel que soit son rôle achats.

Champs de la réponse

  • outcomestring

    within : le montant tient dans le budget. over : il dépasse ce qui reste, de overBy. no_budget : le centre de coûts n’a pas de budget dans cette devise. no_rate : il n’y a pas de taux de change pour le vérifier. off : les budgets ne sont pas contrôlés.

Erreurs

  • 400 Bad Request - amount ou currency est absent ou invalide.
  • 401 Unauthorized - Aucun identifiant n’a été fourni, ou la valeur du jeton Bearer / de X-Api-Key est manquante, invalide, expirée ou révoquée.
  • 403 Forbidden - Le jeton Bearer ou la clé API de l’appelant ne donne pas accès à cet espace de travail (regionId), ou n’a pas le rôle requis.
POST /v1/workspaces/{regionId}/budget-control/check
Requête
POST /v1/workspaces/reg_01k5x8p9j3q7vn2mhb4tzc6rde.buyer/budget-control/check
{
   "costCenter": "CC-1000",
   "amount": 12000,
   "currency": "USD"
}
Réponse · 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"
}
Nous contacter