Referência da API

Controle orçamentário

Se pedidos e solicitações são verificados contra os orçamentos dos centros de custo, e como está cada orçamento.

Mais sobre este recurso

Um espaço de trabalho comprador pode verificar cada pedido de compra e cada solicitação de compra contra o orçamento do seu centro de custo para o mês, trimestre ou ano corrente. No modo warn, um pedido acima do orçamento segue em frente com um aviso; no modo block, ele é recusado com 409 over_budget. O gasto comprometido são os pedidos aprovados que ainda não foram faturados, e o gasto real são as faturas aprovadas. Os orçamentos em si são definidos por centro de custo na Pleaxy.

Obter controle orçamentário

Obtém se os orçamentos são verificados e em qual período.

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

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Retorna a configuração de controle orçamentário do espaço de trabalho: off, warn ou block, e o período que os orçamentos cobrem.

Qualquer membro do espaço de trabalho comprador, seja qual for seu papel de compras.

Campos da resposta

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

    off: os orçamentos não são verificados. warn: um pedido ou uma solicitação acima do orçamento do seu centro de custo segue em frente com um aviso. block: é recusado com 409 over_budget.

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

    O período que um orçamento cobre e no qual os gastos são contados.

Erros

  • 401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
  • 403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.
GET /v1/workspaces/{regionId}/budget-control
Requisição
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/budget-control" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Resposta · 200 OK
{
   "mode": "off" | "warn" | "block",
   "period": "month" | "quarter" | "year",
   "updatedAt": "string",
   "updatedBy": "string"
}

Atualizar controle orçamentário

Altera se os orçamentos são verificados e em qual período.

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

Corpo

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

    Opcional. Se os orçamentos são verificados, e se ultrapassá-los avisa ou bloqueia.

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

    Opcional. O período que um orçamento cobre.

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Altera a configuração de controle orçamentário. Vale para pedidos e solicitações enviados ou aprovados a partir de então.

Somente sessão conectada, com acesso 'edit' às configurações de aprovação ou às faturas. Uma chave de API recebe 403 HUMAN_SESSION_REQUIRED.

Campos da resposta

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

    off: os orçamentos não são verificados. warn: um pedido ou uma solicitação acima do orçamento do seu centro de custo segue em frente com um aviso. block: é recusado com 409 over_budget.

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

    O período que um orçamento cobre e no qual os gastos são contados.

Erros

  • 400 Bad Request - mode ou period não é um dos valores listados.
  • 403 Forbidden - Código HUMAN_SESSION_REQUIRED. Quem chama não é uma pessoa conectada (por exemplo, uma chave de API). Nada é salvo.
  • 401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
  • 403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.
PATCH /v1/workspaces/{regionId}/budget-control
Requisição
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"
}
Resposta · 200 OK
{
   "mode": "off" | "warn" | "block",
   "period": "month" | "quarter" | "year",
   "updatedAt": "string",
   "updatedBy": "string"
}

Obter situação do orçamento

Obtém o orçamento e os gastos comprometido, real e restante por centro de custo.

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

Parâmetros

  • costCenterstring

    Só este centro de custo. Todos os centros de custo orçados quando ausente.

  • datestring

    Um dia (YYYY-MM-DD) do período a consultar. Hoje quando ausente.

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Retorna, para o período corrente, o orçamento de cada centro de custo orçado, o gasto comprometido (pedidos aprovados ainda não faturados), o gasto real (faturas aprovadas) e o que resta. O gasto sem centro de custo é informado à parte, como unassigned.

Precisa de acesso 'view' aos pedidos de compra.

Campos da resposta

  • costCenters[].committednumber

    Pedidos de compra aprovados, menos o que já foi faturado contra eles.

  • costCenters[].actualnumber

    Faturas aprovadas no período.

  • costCenters[].remainingnumber

    O orçamento menos os gastos comprometido e real.

  • costCenters[].pendingnumber

    Gasto que ainda aguarda aprovação. Não reduz remaining.

  • costCenters[].unconvertednumber

    Sempre 0; mantido para clientes antigos.

  • unassignedobject

    O gasto do período que não indica centro de custo, na moeda do espaço de trabalho; unassignedByCurrency tem uma entrada por moeda.

Erros

  • 400 Bad Request - date não é um dia escrito como YYYY-MM-DD.
  • 401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
  • 403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.
GET /v1/workspaces/{regionId}/budget-control/status
Requisição
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/budget-control/status" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Resposta · 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 } ]
}

Verificar orçamento

Mostra antecipadamente a verificação de orçamento de um valor em um centro de custo.

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

Corpo

  • amountnumberObrigatório

    O valor a verificar.

  • currencystringObrigatório

    O código da moeda do valor.

  • costCenterstring

    O centro de custo em que o valor seria lançado.

  • excludeOrderIdstring

    Um pedido de compra a deixar fora do gasto comprometido, ao verificar uma alteração nesse pedido.

  • blanketboolean

    true: verificar como pedido aberto, que reserva expectedMonthly para cada mês do período até validUntil.

  • expectedMonthlynumber

    Com blanket: o que se espera que o pedido gaste a cada mês.

  • validUntilstring

    Com blanket: o último dia do pedido (YYYY-MM-DD).

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Diz o que a verificação de orçamento responderia para um valor em um centro de custo, contra o orçamento desse centro de custo na moeda do valor. Não grava nada e nunca recusa: um valor acima do orçamento volta com outcome over, com 200.

Qualquer membro do espaço de trabalho comprador, seja qual for seu papel de compras.

Campos da resposta

  • outcomestring

    within: o valor cabe no orçamento. over: ultrapassa o que resta, em overBy. no_budget: o centro de custo não tem orçamento nesta moeda. no_rate: não há taxa de câmbio para verificá-lo. off: os orçamentos não são verificados.

Erros

  • 400 Bad Request - amount ou currency está ausente ou é inválido.
  • 401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
  • 403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.
POST /v1/workspaces/{regionId}/budget-control/check
Requisição
POST /v1/workspaces/reg_01k5x8p9j3q7vn2mhb4tzc6rde.buyer/budget-control/check
{
   "costCenter": "CC-1000",
   "amount": 12000,
   "currency": "USD"
}
Resposta · 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"
}
Fale conosco