Crear plan de gasto con presupuesto

POST /v1/spending-plans/with-budget

Crea el presupuesto y el plan de gasto en una sola llamada. Útil cuando armas un presupuesto de un solo uso por viaje: en vez de crear el presupuesto, guardar su id y luego crear el plan, envías todo junto y Uvicuo crea ambos por vos.

Si en cambio querés reutilizar un presupuesto existente entre varios planes, usá el flujo normal: crear el plan con budget_id.

No necesitas el id de la tarjeta

Igual que en el create normal, Uvicuo resuelve la tarjeta del empleado (a partir de employee_id) y el TAG del vehículo (a partir de vehicle_id). Tu ERP no envía medios de pago.

Cuerpo de la solicitud

Campo	Tipo	Req.	Descripción
budget	objeto	✅	El presupuesto a crear, con la misma estructura que POST /v1/budgets (name, payment_method_configs, frequency, …).
employee_id	número entero	✅	Empleado al que se asigna. Su tarjeta se resuelve automáticamente. ¿No lo tienes? Búscalo en Empleados.
vehicle_id	string (UUID)	–	Vehículo asociado. Su TAG se deriva automáticamente. ¿No lo tienes? Búscalo en Vehículos.
trip_id	string	–	Viaje asociado (tu identificador).
cash_dispersion_method	ATM_WITHDRAWAL | CASH_ON_HAND	–	Cómo se entrega el efectivo, si el presupuesto incluye efectivo.

El objeto budget se valida exactamente igual que en Crear un presupuesto: consultá esa página para el detalle de payment_method_configs, grupos de condiciones, categorías y restricciones.

Ejemplo

curl -X POST https://api.sandbox.partner.uvicuo.com/v1/spending-plans/with-budget \
  -H "X-API-Key: $UVICUO_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "budget": {
      "name": "Viaje VIAJE-123 - Juan Pérez",
      "frequency": "MONTHLY",
      "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"]
          }
        }
      ]
    },
    "employee_id": 42,
    "trip_id": "VIAJE-123"
  }'

Respuesta

201 Created — devuelve el plan de gasto creado (igual que POST /v1/spending-plans), incluyendo su id y los datos asociados.

El plan nace inactivo

El plan se crea en estado NOT_STARTED. Para activarlo, llama a Activar un plan de gasto con el id que devuelve esta respuesta.

Errores comunes

Situación	HTTP	code	Cómo evitarlo
Ya existe un presupuesto con ese budget.name (es único por empresa).	409	—	Usa un nombre único por llamada (p. ej. incluí el trip_id), o reutiliza un presupuesto con el flujo normal.
El presupuesto usa CARD (o efectivo ATM_WITHDRAWAL) y el empleado no tiene tarjeta asignada.	422	no_card_for_employee	Asigna una tarjeta al empleado en Uvicuo. Para efectivo sin tarjeta, usa CASH_ON_HAND. El presupuesto no se crea en este caso.
Payload inválido (budget mal formado, employee_id, etc.).	400	validation_error	Revisa error.details.

Si el plan falla después de crear el presupuesto

La tarjeta se valida antes de crear el presupuesto, así que el error más común (no_card_for_employee) ocurre sin dejar nada creado. Si aun así el presupuesto se crea pero el plan falla, la respuesta de error incluye el budget_id en error.details: reutilízalo con POST /v1/spending-plans en vez de volver a crear el presupuesto (evitas el 409 por nombre duplicado).

Ver Errores para el formato de la respuesta.