Crear plan de gasto

POST /v1/spending-plans

Un plan de gasto asigna un presupuesto a un empleado (y opcionalmente a un vehículo o viaje).

No necesitas el id de la tarjeta

Uvicuo resuelve automáticamente 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.

La tarjeta se asigna al plan al crearlo y se habilita (se desbloquea) recién al activar el plan — antes de eso está bloqueada. Por eso no importa el estado de la tarjeta al crear: solo debe existir una tarjeta asignada al empleado.

Cuerpo de la solicitud

Campo	Tipo	Req.	Descripción
budget_id	string (UUID)	✅	Presupuesto a aplicar (el id devuelto al crear el presupuesto).
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.
cash_dispersion_method	ATM_WITHDRAWAL | CASH_ON_HAND	–	Cómo se entrega el efectivo, si el presupuesto incluye efectivo.

Ejemplo

curl -X POST https://api.sandbox.partner.uvicuo.com/v1/spending-plans \
  -H "X-API-Key: $UVICUO_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "budget_id": "c9bdaa14-264e-8f36-e60a-7eb9b73fbeea",
    "employee_id": 42,
    "vehicle_id": "7b3e0a2c-1f44-4d8e-9c0a-2b6f5e1d9a10"
  }'

Respuesta

201 Created

Devuelve el plan de gasto creado, incluyendo su id y los datos asociados (empleado, presupuesto y medios de pago resueltos).

El plan nace inactivo

El plan se crea en estado NOT_STARTED: queda configurado pero el medio de pago todavía no está habilitado. Para activarlo, llama a Activar un plan de gasto con el id que devuelve esta respuesta.

Guarda el id (o usa tu trip_id)

Necesitarás el id del plan para activarlo o agregarle gastos de emergencia. Guárdalo en tu ERP al crearlo. Como alternativa, envía tu propio identificador de viaje en trip_id y luego reencuentra el plan con GET /v1/spending-plans?trip_id=….

Errores comunes

Situación	HTTP	code	Cómo evitarlo
El presupuesto usa CARD (o efectivo con cash_dispersion_method: ATM_WITHDRAWAL) y el empleado no tiene ninguna tarjeta asignada en Uvicuo.	422	no_card_for_employee	Asigna una tarjeta al empleado en Uvicuo (búscalo en Empleados). Para efectivo sin tarjeta, usa CASH_ON_HAND.
El budget_id no existe (o no es de tu empresa).	404	not_found	Usa un id válido de Listar presupuestos.
Payload inválido (employee_id/budget_id mal formados, etc.).	400	validation_error	Revisa error.details.

Regla: un empleado solo puede tener un plan de gasto ACTIVO a la vez. Puedes crear varios planes, pero al activarlos solo uno puede estar activo por empleado.

Ver Errores para el formato de la respuesta.