Crear presupuesto

POST /v1/budgets

Un presupuesto define cuánto y en qué puede gastarse, por método de pago.

El nombre es único por empresa

Si creas un presupuesto con un name que ya existe, la API responde 409. Para reutilizar presupuestos entre viajes, lista los existentes antes de crear uno nuevo. Ver el flujo completo.

Cuerpo de la solicitud

Campo	Tipo	Req.	Descripción
name	string	✅	Nombre del presupuesto.
payment_method_configs	array	✅	Al menos una configuración por método de pago (ver Métodos de pago).
frequency	WEEKLY | MONTHLY	–	Cada cuánto se renueva el límite. Si se omite, no se renueva (ver Renovación).
route_id	string (UUID)	–	Ruta asociada, si aplica.

payment_method_configs[]

Campo	Tipo	Req.	Descripción
payment_method_type	CARD | CASH | TOLLS_TAG	✅	Medio de pago al que aplica este límite. Ver Métodos de pago.
conditions_group	objeto	✅	Cómo se reparte el límite de gasto (global o por categoría). Ver Grupos de condiciones.
cash_dispersion_method	ATM_WITHDRAWAL | CASH_ON_HAND	condicional	Obligatorio si payment_method_type es CASH. Ver Dispersión de efectivo.
ecommerce_enabled	boolean	–	Si es true, permite compras en línea (e-commerce) con la tarjeta. Aplica a CARD.
temporal_restrictions	objeto	–	Ventana de días/horas en que se permite gastar. Ver Restricciones horarias.

Métodos de pago

El payment_method_type indica sobre qué medio se aplica el límite de gasto:

Valor	Qué controla
CARD	Compras hechas con la tarjeta Uvicuo (física o virtual) del empleado. Es el método más común.
CASH	Efectivo entregado al empleado. Requiere indicar cómo se entrega con cash_dispersion_method.
TOLLS_TAG	Pago de casetas mediante el TAG (tag de peaje) asociado al vehículo.

Cada elemento de payment_method_configs configura un método de pago. Si quieres límites para varios medios a la vez (por ejemplo, tarjeta y efectivo), incluye un objeto por cada uno.

Dispersión de efectivo (cash_dispersion_method)

Obligatorio cuando payment_method_type es CASH. Define cómo recibe el efectivo el empleado:

Valor	Significado
ATM_WITHDRAWAL	Retiro en cajero automático. Requiere que el empleado tenga tarjeta (el retiro se hace con la tarjeta) → si no la tiene, da 422 no_card_for_employee.
CASH_ON_HAND	Efectivo en mano. No requiere tarjeta; al activar, el plan queda en IN_FULFILLMENT hasta confirmar la entrega (ver Activar).

Restricciones horarias (temporal_restrictions)

Opcional. Limita la ventana de días y horas en que se permite gastar con este método de pago. Todos los campos son opcionales: incluye solo los que quieras restringir.

{
  "from_hours": "08:00",
  "to_hours": "18:00",
  "week_days": ["MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY"],
  "timezone": "America/Mexico_City"
}

Campo	Tipo	Descripción
from_hours	string	Hora de inicio en formato HH:mm (24 h).
to_hours	string	Hora de fin en formato HH:mm (24 h).
week_days	array	Días permitidos: MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY.
timezone	string	Zona horaria IANA (por ejemplo, America/Mexico_City).

El ejemplo anterior permite gastar solo de lunes a viernes, de 8:00 a 18:00, hora de Ciudad de México.

Renovación (frequency)

Controla si el límite del presupuesto se restablece periódicamente:

Valor	Comportamiento
WEEKLY	El límite se renueva cada semana.
MONTHLY	El límite se renueva cada mes.
(se omite el campo)	No se renueva. El presupuesto es de un solo uso: una vez consumido el límite, no vuelve a estar disponible automáticamente.

Grupos de condiciones (conditions_group)

Define cuánto se puede gastar y en qué categorías. Hay dos variantes, según cómo quieras repartir los límites.

El límite global solo aplica a tarjeta

Solo payment_method_type: CARD admite el límite global (GLOBAL). Para CASH y TOLLS_TAG únicamente se permite el límite por categoría (PER_CATEGORY); si envías un GLOBAL para esos métodos, la API responde 400 validation_error.

Montos (monetaryAmount) — cada importe se expresa como { "amount": 1000.00, "currency": "MXN" }: amount es la cantidad (≥ 0, con punto decimal) y currency el código de moneda ISO de 3 letras.

a) Límite global

Un único tope compartido entre varias categorías: el gasto de todas ellas suma contra el mismo límite.

{
  "condition_type": "GLOBAL",
  "max_amount": { "amount": 10000.00, "currency": "MXN" },
  "categories": ["CARD_GASOLINE", "CARD_FOOD_AND_DRINKS"]
}

Ejemplo: das $10,000 MXN para gasolina y comida combinadas. Si el empleado gasta $7,000 en gasolina, le quedan $3,000 para comida (o para más gasolina). El tope es compartido.

b) Límite por categoría

Un tope independiente por cada categoría: lo que sobra en una no se puede usar en otra.

{
  "condition_type": "PER_CATEGORY",
  "conditions": [
    { "category": "CARD_GASOLINE", "amount": { "amount": 6000.00, "currency": "MXN" } },
    { "category": "CARD_FOOD_AND_DRINKS", "amount": { "amount": 4000.00, "currency": "MXN" } }
  ]
}

Ejemplo: das $6,000 MXN solo para gasolina y $4,000 MXN solo para comida. Si gasta los $6,000 de gasolina, no puede usar el sobrante de comida para repostar: cada categoría tiene su propia bolsa.

Consulta el listado completo de categorías válidas en Categorías de gasto.

Ejemplo

curl -X POST https://api.sandbox.partner.uvicuo.com/v1/budgets \
  -H "X-API-Key: $UVICUO_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "name": "Presupuesto Flota Q1",
    "frequency": "MONTHLY",
    "payment_method_configs": [
      {
        "payment_method_type": "CARD",
        "ecommerce_enabled": false,
        "conditions_group": {
          "condition_type": "GLOBAL",
          "max_amount": { "amount": 10000.00, "currency": "MXN" },
          "categories": ["CARD_GASOLINE", "CARD_FOOD_AND_DRINKS"]
        }
      }
    ]
  }'

Respuesta

201 Created

{
  "id": "c9bdaa14-264e-8f36-e60a-7eb9b73fbeea",
  "name": "Presupuesto Flota Q1",
  "state": "ACTIVE",
  "payment_method_configs": [
    {
      "payment_method_type": "CARD",
      "conditions_group": {
        "condition_type": "GLOBAL",
        "max_amount": { "amount": 10000.00, "currency": "MXN" },
        "categories": ["CARD_GASOLINE", "CARD_FOOD_AND_DRINKS"]
      },
      "cash_dispersion_method": null,
      "ecommerce_enabled": false,
      "temporal_restrictions": null
    }
  ],
  "created_at": "2026-06-04T14:02:31.617Z",
  "updated_at": "2026-06-04T14:02:31.617Z"
}

Nota

Guarda el id del presupuesto: lo necesitarás como budget_id al crear un plan de gasto.

Errores comunes

HTTP / code	Situación	Cómo evitarlo
409	Ya existe un presupuesto con ese name (es único por empresa).	Lista los presupuestos y reutiliza, o usa otro nombre.
400 validation_error	Payload inválido. Ej.: falta cash_dispersion_method cuando un método es CASH, o categories vacío.	Revisa los campos en error.details.

Ver Errores para el formato de la respuesta.