Flujo de integración

El objetivo es dejar un plan de gasto activo para un empleado: un presupuesto (cuánto y en qué se puede gastar) aplicado a una persona, con su medio de pago habilitado.

Dos formas de crear el plan

Según si el presupuesto se reutiliza o es de un solo uso:

Presupuesto reutilizable — creas el presupuesto una vez y lo aplicas a varios planes/empleados. Son 3 pasos: crear presupuesto → crear plan → activar.
Presupuesto de un solo uso (uno por viaje) — creas el presupuesto y el plan juntos en una llamada. Son 2 pasos: crear plan + presupuesto → activar.

flowchart TD
    subgraph reuse ["Presupuesto reutilizable"]
        A1["Crear presupuesto<br/>POST /v1/budgets"] --> A2["Crear plan de gasto<br/>POST /v1/spending-plans"]
    end
    subgraph oneoff ["Presupuesto de un solo uso"]
        B1["Crear plan + presupuesto<br/>POST /v1/spending-plans/with-budget"]
    end
    A2 --> C["Activar plan<br/>PUT /v1/spending-plans/:id/activate"]
    B1 --> C
    C --> D["✅ Plan ACTIVE<br/>medio de pago habilitado"]
    D -.->|surge un imprevisto| E["Gasto de emergencia<br/>POST /v1/spending-plans/:id/emergency-expenses"]

Los pasos

1. Crear el presupuesto

POST /v1/budgets — define cuánto y en qué puede gastarse. El nombre es único por empresa; para reutilizar entre viajes, primero lista los existentes.

2. Crear el plan de gasto

POST /v1/spending-plans — asigna el presupuesto a un empleado y, opcionalmente, a un vehículo y viaje. Se crea en estado NOT_STARTED (inactivo).

3. Activar el plan

PUT /v1/spending-plans/{id}/activate — habilita el medio de pago: el plan pasa a ACTIVE y la tarjeta queda lista para usarse.

Durante el viaje: gastos de emergencia

¿Surge un imprevisto y el empleado necesita gastar fuera de lo presupuestado? Sobre un plan ya activo, agrega un gasto de emergencia con POST /v1/spending-plans/{id}/emergency-expenses — sin rehacer el presupuesto ni el plan.