Referencia de la API

Control presupuestario

Si las órdenes y solicitudes se comparan con los presupuestos de los centros de costo, y cómo va cada presupuesto.

Más sobre este recurso

Un espacio de trabajo comprador puede comparar cada orden de compra y cada solicitud de compra con el presupuesto de su centro de costo para el mes, trimestre o año en curso. En modo warn, una orden que supera el presupuesto sigue adelante con un aviso; en modo block se rechaza con 409 over_budget. El gasto comprometido son las órdenes aprobadas que aún no se han facturado, y el gasto real son las facturas aprobadas. Los presupuestos se definen por centro de costo en Pleaxy.

Obtener control presupuestario

Obtiene si se comprueban los presupuestos y sobre qué periodo.

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

Devuelve

200 OK con el objeto que se muestra en la respuesta.

Más detalles

Devuelve la configuración de control presupuestario del espacio de trabajo: off, warn o block, y el periodo que cubren los presupuestos.

Cualquier miembro del espacio de trabajo comprador, sea cual sea su rol de compras.

Campos de la respuesta

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

    off: los presupuestos no se comprueban. warn: una orden o solicitud que supera el presupuesto de su centro de costo sigue adelante con un aviso. block: se rechaza con 409 over_budget.

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

    El periodo que cubre un presupuesto y sobre el que se cuenta el gasto.

Errores

  • 401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
  • 403 Forbidden - El token Bearer o la clave de API del llamador no da acceso a este espacio de trabajo (regionId), o no tiene el rol requerido.
GET /v1/workspaces/{regionId}/budget-control
Solicitud
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/budget-control" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Respuesta · 200 OK
{
   "mode": "off" | "warn" | "block",
   "period": "month" | "quarter" | "year",
   "updatedAt": "string",
   "updatedBy": "string"
}

Actualizar control presupuestario

Cambia si se comprueban los presupuestos y sobre qué periodo.

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

Cuerpo

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

    Opcional. Si se comprueban los presupuestos, y si superarlos avisa o bloquea.

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

    Opcional. El periodo que cubre un presupuesto.

Devuelve

200 OK con el objeto que se muestra en la respuesta.

Más detalles

Cambia la configuración de control presupuestario. Se aplica a las órdenes y solicitudes enviadas o aprobadas a partir de ese momento.

Solo sesión iniciada, con acceso 'edit' a la configuración de aprobaciones o a las facturas. Una clave de API recibe 403 HUMAN_SESSION_REQUIRED.

Campos de la respuesta

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

    off: los presupuestos no se comprueban. warn: una orden o solicitud que supera el presupuesto de su centro de costo sigue adelante con un aviso. block: se rechaza con 409 over_budget.

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

    El periodo que cubre un presupuesto y sobre el que se cuenta el gasto.

Errores

  • 400 Bad Request - mode o period no es uno de los valores indicados.
  • 403 Forbidden - Código HUMAN_SESSION_REQUIRED. El llamador no es una persona con sesión iniciada (por ejemplo, una clave de API). No se guarda nada.
  • 401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
  • 403 Forbidden - El token Bearer o la clave de API del llamador no da acceso a este espacio de trabajo (regionId), o no tiene el rol requerido.
PATCH /v1/workspaces/{regionId}/budget-control
Solicitud
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"
}
Respuesta · 200 OK
{
   "mode": "off" | "warn" | "block",
   "period": "month" | "quarter" | "year",
   "updatedAt": "string",
   "updatedBy": "string"
}

Obtener estado del presupuesto

Obtiene el presupuesto y el gasto comprometido, real y restante por centro de costo.

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

Parámetros

  • costCenterstring

    Solo este centro de costo. Todos los centros de costo presupuestados si no aparece.

  • datestring

    Un día (YYYY-MM-DD) del periodo que se quiere consultar. Hoy si no aparece.

Devuelve

200 OK con el objeto que se muestra en la respuesta.

Más detalles

Devuelve, para el periodo en curso, el presupuesto de cada centro de costo presupuestado, el gasto comprometido (órdenes aprobadas aún sin facturar), el gasto real (facturas aprobadas) y lo que queda. El gasto sin centro de costo se informa aparte, como unassigned.

Necesita acceso 'view' a las órdenes de compra.

Campos de la respuesta

  • costCenters[].committednumber

    Órdenes de compra aprobadas, menos lo que ya se ha facturado contra ellas.

  • costCenters[].actualnumber

    Facturas aprobadas en el periodo.

  • costCenters[].remainingnumber

    El presupuesto menos el gasto comprometido y el real.

  • costCenters[].pendingnumber

    Gasto que aún espera aprobación. No reduce remaining.

  • costCenters[].unconvertednumber

    Siempre 0; se mantiene para clientes antiguos.

  • unassignedobject

    El gasto del periodo que no indica centro de costo, en la moneda del espacio de trabajo; unassignedByCurrency tiene una entrada por moneda.

Errores

  • 400 Bad Request - date no es un día escrito como YYYY-MM-DD.
  • 401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
  • 403 Forbidden - El token Bearer o la clave de API del llamador no da acceso a este espacio de trabajo (regionId), o no tiene el rol requerido.
GET /v1/workspaces/{regionId}/budget-control/status
Solicitud
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/budget-control/status" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Respuesta · 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 } ]
}

Comprobar presupuesto

Muestra por adelantado la comprobación de presupuesto de un importe en un centro de costo.

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

Cuerpo

  • amountnumberObligatorio

    El importe que se quiere comprobar.

  • currencystringObligatorio

    El código de moneda del importe.

  • costCenterstring

    El centro de costo al que se imputaría el importe.

  • excludeOrderIdstring

    Una orden de compra que se deja fuera del gasto comprometido, al comprobar un cambio en esa orden.

  • blanketboolean

    true: comprobar como orden abierta, que reserva expectedMonthly por cada mes del periodo hasta validUntil.

  • expectedMonthlynumber

    Con blanket: lo que se espera que la orden gaste cada mes.

  • validUntilstring

    Con blanket: el último día de la orden (YYYY-MM-DD).

Devuelve

200 OK con el objeto que se muestra en la respuesta.

Más detalles

Indica qué respondería la comprobación de presupuesto para un importe en un centro de costo, frente al presupuesto de ese centro de costo en la moneda del importe. No escribe nada y nunca rechaza: un importe que supera el presupuesto vuelve con outcome over, con 200.

Cualquier miembro del espacio de trabajo comprador, sea cual sea su rol de compras.

Campos de la respuesta

  • outcomestring

    within: el importe cabe en el presupuesto. over: supera lo que queda, en overBy. no_budget: el centro de costo no tiene presupuesto en esta moneda. no_rate: no hay tipo de cambio para comprobarlo. off: los presupuestos no se comprueban.

Errores

  • 400 Bad Request - Falta amount o currency, o no es válido.
  • 401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
  • 403 Forbidden - El token Bearer o la clave de API del llamador no da acceso a este espacio de trabajo (regionId), o no tiene el rol requerido.
POST /v1/workspaces/{regionId}/budget-control/check
Solicitud
POST /v1/workspaces/reg_01k5x8p9j3q7vn2mhb4tzc6rde.buyer/budget-control/check
{
   "costCenter": "CC-1000",
   "amount": 12000,
   "currency": "USD"
}
Respuesta · 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"
}
Habla con nosotros