Flota

Devuelve los vehículos de la empresa, ordenados por matrícula (y por id a igual matrícula).

Con una clave API la llamada actúa como el owner que creó la clave: ve toda la flota y cada vehículo trae siempre drivers (sus conductores activos, por nombre; [] en los variables).

• mine: true limita la lista a los vehículos que puede conducir el owner que creó la clave: los variables (pool) y los fijos (fixed) en los que figura como conductor.
• includeInactive: true añade los vehículos dados de baja (active: false), p. ej. para cuadrar el informe de un mes antiguo. Junto con mine: true no añade nada: un vehículo de baja no lo puede conducir nadie.
• Sin paginación: devuelve todos los vehículos en una sola respuesta.
• El cuerpo es opcional: sin cuerpo (o {}) equivale a mine: false e includeInactive: false.

Errores propios

• 422 invalid_input: el cuerpo no es un objeto JSON (sin fields); mine o includeInactive no son booleanos (fields.<campo>: invalid); clave no admitida (fields.<clave>: unexpected_field).

curl -sS -X POST "https://app.flotadoc.com/api/movimientos/flota/list" \
  -H "Authorization: Bearer $FLOTADOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "includeInactive": false
  }'

{
  "data": {
    "vehicles": [
      {
        "vehicleId": 7,
        "tenantId": 42,
        "plate": "1234ABC",
        "model": "Seat León",
        "regime": "company",
        "energy": "combustion",
        "assignmentMode": "fixed",
        "fuelConsumption": 5.8,
        "electricConsumption": null,
        "active": true,
        "updatedAt": "2026-10-06T10:00:00.000Z",
        "drivers": [
          {
            "userId": 15,
            "fullName": "Bea Conductora"
          }
        ]
      },
      {
        "vehicleId": 9,
        "tenantId": 42,
        "plate": "5678DEF",
        "model": null,
        "regime": "own",
        "energy": "electric",
        "assignmentMode": "pool",
        "fuelConsumption": null,
        "electricConsumption": 17.9,
        "active": true,
        "updatedAt": "2026-10-06T10:00:00.000Z",
        "drivers": []
      }
    ]
  }
}

Devuelve la ficha de un vehículo de la empresa con sus conductores (drivers, siempre presente con clave API).

Un vehículo dado de baja responde 404 salvo que se pida includeInactive: true; entonces llega con active: false.

Errores propios

• 404 vehicle_not_found: el vehículo no existe, es de otra empresa o está de baja (sin includeInactive). Es la misma respuesta en los tres casos: no confirma que exista.
• 422 invalid_input: cuerpo que no es un objeto JSON; vehicleId ausente (required) o no válido (invalid); includeInactive no booleano (invalid); clave no admitida (unexpected_field).

curl -sS -X POST "https://app.flotadoc.com/api/movimientos/flota/get" \
  -H "Authorization: Bearer $FLOTADOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vehicleId": 7
  }'

{
  "data": {
    "vehicle": {
      "vehicleId": 7,
      "tenantId": 42,
      "plate": "1234ABC",
      "model": "Seat León",
      "regime": "company",
      "energy": "combustion",
      "assignmentMode": "fixed",
      "fuelConsumption": 5.8,
      "electricConsumption": null,
      "active": true,
      "updatedAt": "2026-10-06T10:00:00.000Z",
      "drivers": [
        {
          "userId": 15,
          "fullName": "Bea Conductora"
        }
      ]
    }
  }
}

Busca marca y modelo para proponer la energía y el consumo medio al dar de alta un vehículo. Devuelve dos listas independientes:

• companyModels: los modelos que ha guardado tu empresa (ver /movimientos/flota/company-models-save), solo los activos, por nombre. Ninguna otra empresa los ve.
• models: variantes del catálogo público de la Agencia Europea de Medio Ambiente (turismos desde 2010 y furgonetas desde 2012), las más matriculadas primero, con su consumo homologado o, si solo se vendieron en 2010-2020, estimado a partir del CO2 (consumptionSource). consumption es null solo en un eléctrico antiguo sin dato.

Cómo busca. Cada palabra de query debe ser el principio de alguna palabra de «marca modelo» (o del nombre del modelo de la empresa), en cualquier orden. No distingue mayúsculas, tildes ni separadores: "seat leon", "SEAT-LEÓN" y "leo sea" encuentran lo mismo; "troc" encuentra T-ROC e "id3", ID.3.

Sin paginación: limit (1-50, 20 por defecto) se aplica a cada lista por separado. Sin coincidencias, las dos listas llegan vacías.

Usar una sugerencia en /movimientos/flota/save. model = make + " " + model (o name en un modelo de la empresa) y energy tal cual. Del catálogo: con unit: l_100km, consumption va a fuelConsumption (y electricConsumption, si lo trae un enchufable, a electricConsumption); con unit: kwh_100km, consumption va a electricConsumption.

Errores propios

• 422 invalid_input: cuerpo que no es un objeto JSON; query ausente o vacío (required), que no es texto, con menos de 2 caracteres o sin letras ni cifras (invalid) o de más de 100 (too_long); limit que no es un entero de 1 a 50 (invalid); clave no admitida (unexpected_field).

curl -sS -X POST "https://app.flotadoc.com/api/movimientos/flota/models-search" \
  -H "Authorization: Bearer $FLOTADOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "seat ibiza",
    "limit": 10
  }'

{
  "data": {
    "companyModels": [
      {
        "companyModelId": 501,
        "name": "Seat Ibiza Cupra 2004",
        "energy": "combustion",
        "fuelConsumption": 8.1,
        "electricConsumption": null,
        "updatedAt": "2026-10-12T10:00:00.000Z"
      }
    ],
    "models": [
      {
        "modelId": 812,
        "category": "car",
        "make": "SEAT",
        "model": "IBIZA",
        "fuel": "petrol",
        "energy": "combustion",
        "powerKw": 70,
        "yearFrom": 2015,
        "yearTo": 2025,
        "consumption": 5.2,
        "unit": "l_100km",
        "electricConsumption": null,
        "consumptionSource": "homologated"
      },
      {
        "modelId": 30117,
        "category": "car",
        "make": "SEAT",
        "model": "IBIZA",
        "fuel": "petrol",
        "energy": "combustion",
        "powerKw": 63,
        "yearFrom": 2011,
        "yearTo": 2017,
        "consumption": 6,
        "unit": "l_100km",
        "electricConsumption": null,
        "consumptionSource": "estimated"
      }
    ]
  }
}

Devuelve los modelos de vehículo que ha guardado la empresa (los que no están en el catálogo), solo los activos, ordenados por nombre (sin distinguir mayúsculas ni tildes), después por energía y por id.

Sin paginación. El cuerpo es opcional: sin cuerpo o {}; no admite ningún campo.

Errores propios

• 422 invalid_input: cuerpo que no es un objeto JSON; cualquier clave (unexpected_field).

curl -sS -X POST "https://app.flotadoc.com/api/movimientos/flota/company-models-list" \
  -H "Authorization: Bearer $FLOTADOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "data": {
    "companyModels": [
      {
        "companyModelId": 502,
        "name": "Iveco Daily 35S",
        "energy": "combustion",
        "fuelConsumption": 9.8,
        "electricConsumption": null,
        "updatedAt": "2026-10-12T10:00:00.000Z"
      }
    ]
  }
}

Sin vehicleId (o con vehicleId: null) da de alta un vehículo; con vehicleId edita ese vehículo, que debe estar activo. Siempre responde 200 con el vehículo guardado.

Guardado completo. Cada llamada manda el vehículo entero. plate, regime, energy y assignmentMode son obligatorios siempre; en una edición, model, fuelConsumption y electricConsumption que no se mandan (o van a null) se borran. Para conservarlos, reenvía los valores actuales (los devuelve /movimientos/flota/get).

• Matrícula: se quitan espacios y guiones y se pasa a mayúsculas ("1234 abc" → "1234ABC"); después debe quedar de 1 a 20 caracteres A-Z y 0-9. Es única entre los vehículos activos de la empresa (dar uno de baja libera su matrícula).
• Modelo: se recortan los extremos y se juntan los espacios repetidos; "" se guarda como null.
• Consumo medio (opcional, de 0,1 a 99,9 con un decimal como mucho): fuelConsumption (l/100 km) solo con energy combustion o hybrid; electricConsumption (kWh/100 km) solo con electric o hybrid. Mandar el que no corresponde a la energía es invalid: no lo mandes o mándalo a null.
• Fijo o variable (assignmentMode): fixed = solo lo usan sus conductores, que se fijan después con /movimientos/flota/assign; pool = variable, lo puede usar cualquier conductor de la empresa y no tiene lista. Pasar un vehículo a pool da de baja a todos sus conductores; volver a fixed lo deja sin conductores hasta el siguiente assign.
• Los conductores no se tocan aquí: en un alta drivers llega siempre []; en una edición, los conductores actuales.
• Cambiar regime no recalcula los viajes ya guardados.
• Solo el alta comprueba el límite del plan; la edición no.

Orden de las comprobaciones: cuenta que admite cambios (423) → cuerpo (422) → en el alta, plaza libre en el plan (409 vehicle_limit) → matrícula libre (409 vehicle_plate_taken) y, en la edición, vehículo existente (404).

Errores propios

• 404 vehicle_not_found: edición de un vehículo que no existe, es de otra empresa o está de baja.

• 409 vehicle_limit: alta con el plan lleno. Además de code y message trae resource: "vehicles", limit (máximo del plan), used (vehículos no dados de baja) y next, que dice la salida:

  • subscribe: cuenta en prueba (máximo 4 vehículos); hay que pasar a pago en la web.
  • add_extra_vehicle: cuenta de pago con menos de 10 vehículos extra; el owner puede contratar uno más en la web (hasta 14 en total).
  • contact_us: del 15.º en adelante o con un límite pactado a medida; «Habla con nosotros».

  Ejemplo: {"error": {"code": "vehicle_limit", "message": "Has llegado al limite de vehiculos de tu plan", "resource": "vehicles", "limit": 4, "used": 4, "next": "subscribe"}}. Dar de baja un vehículo libera plaza.

• 409 vehicle_plate_taken: otro vehículo activo de la empresa ya tiene esa matrícula (normalizada).

• 422 invalid_input: error.fields con todos los campos erróneos a la vez, cada uno con required, invalid, too_long (model de más de 100 caracteres) o unexpected_field. Ejemplo: {"plate": "required", "energy": "invalid", "fuelConsumption": "invalid", "color": "unexpected_field"}.

• 423 account_read_only: la cuenta no admite cambios; reason: account (prueba vencida, solo lectura, cancelada…), suspended o pending_payment.

curl -sS -X POST "https://app.flotadoc.com/api/movimientos/flota/save" \
  -H "Authorization: Bearer $FLOTADOC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "plate": "1234 abc",
    "model": "Seat León",
    "regime": "company",
    "energy": "combustion",
    "assignmentMode": "fixed",
    "fuelConsumption": 5.8
  }'

{
  "vehicleId": 7,
  "plate": "1234ABC",
  "model": "Seat León e-Hybrid",
  "regime": "company",
  "energy": "hybrid",
  "assignmentMode": "fixed",
  "fuelConsumption": 1.4,
  "electricConsumption": 15.5
}

{
  "data": {
    "vehicle": {
      "vehicleId": 7,
      "tenantId": 42,
      "plate": "1234ABC",
      "model": "Seat León",
      "regime": "company",
      "energy": "combustion",
      "assignmentMode": "fixed",
      "fuelConsumption": 5.8,
      "electricConsumption": null,
      "active": true,
      "updatedAt": "2026-10-13T09:30:00.000Z",
      "drivers": []
    }
  }
}

Da de baja un vehículo activo (baja lógica). El vehículo se conserva: sus viajes, gastos y cierres lo siguen apuntando, y list / get con includeInactive: true lo devuelven con active: false. Deja de salir en las listas y entre los vehículos que pueden usar los conductores, libera su matrícula y deja de ocupar plaza del plan. No se puede reactivar: para volver a usarlo, da de alta otro con la misma matrícula.

Errores propios

• 404 vehicle_not_found: el vehículo no existe, es de otra empresa o ya está de baja.
• 409: solo por Idempotency-Key (idempotency_conflict, idempotency_in_progress).
• 422 invalid_input: cuerpo que no es un objeto JSON; vehicleId ausente (required) o no válido (invalid); clave no admitida (unexpected_field).
• 423 account_read_only: la cuenta no admite cambios (reason: account, suspended o pending_payment).

curl -sS -X POST "https://app.flotadoc.com/api/movimientos/flota/delete" \
  -H "Authorization: Bearer $FLOTADOC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "vehicleId": 7
  }'

{
  "data": {
    "deleted": true,
    "vehicleId": 7
  }
}

Fija la lista completa de conductores de un vehículo fijo (assignmentMode: fixed). Los que entran se dan de alta, los que ya no están se dan de baja y los que siguen no se tocan (queda el histórico de quién tuvo el vehículo). userIds: [] lo deja sin conductores: ningún usuario con rol user podrá usarlo.

• Conductor válido: usuario con rol owner o user de la misma empresa que no esté desactivado (los invitados que aún no han entrado sí valen). El gestor no conduce. Los ids salen de /auth/usuarios/list.
• Los ids repetidos cuentan una vez; como mucho 100 elementos.
• Si algún id no es un conductor válido no se escribe nada.
• Repetir la misma lista no cambia nada.
• Un vehículo variable (pool) no tiene lista: pásalo antes a fixed con /movimientos/flota/save.

Responde con el vehículo y sus conductores actuales, por nombre.

Errores propios

• 404 vehicle_not_found: el vehículo no existe, es de otra empresa o está de baja (también si lo dan de baja o lo pasan a variable mientras se guarda la asignación).
• 409 vehicle_not_fixed: el vehículo es variable (pool).
• 422 invalid_input: cuerpo que no es un objeto JSON; fields.vehicleId required / invalid; fields.userIds required (falta o es null), invalid (no es una lista o algún elemento no es un id) o too_many (más de 100); clave no admitida (unexpected_field). Si algún id no es un conductor válido de la empresa (inexistente, de otra empresa, gestor o desactivado): fields: {"userIds": "invalid"} y además invalidUserIds con esos ids, p. ej. {"error": {"code": "invalid_input", "message": "Datos no validos", "fields": {"userIds": "invalid"}, "invalidUserIds": [99]}}.
• 423 account_read_only: la cuenta no admite cambios (reason: account, suspended o pending_payment).

curl -sS -X POST "https://app.flotadoc.com/api/movimientos/flota/assign" \
  -H "Authorization: Bearer $FLOTADOC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "vehicleId": 7,
    "userIds": [
      15,
      16
    ]
  }'

{
  "data": {
    "vehicle": {
      "vehicleId": 7,
      "tenantId": 42,
      "plate": "1234ABC",
      "model": "Seat León",
      "regime": "company",
      "energy": "combustion",
      "assignmentMode": "fixed",
      "fuelConsumption": 5.8,
      "electricConsumption": null,
      "active": true,
      "updatedAt": "2026-10-06T10:00:00.000Z",
      "drivers": [
        {
          "userId": 15,
          "fullName": "Bea Conductora"
        },
        {
          "userId": 16,
          "fullName": "Carlos Conductor"
        }
      ]
    }
  }
}

Sin companyModelId (o con null) guarda un modelo nuevo de la empresa; con companyModelId corrige ese modelo, que debe estar activo. Un modelo de la empresa es una marca y modelo que no está en el catálogo y que se quiere volver a elegir: sale primero en /movimientos/flota/models-search y solo para esta empresa.

Guardado completo, como el del vehículo: los consumos que no se mandan (o van a null) se guardan vacíos.

• name: se recortan los extremos y se juntan los espacios repetidos; de 1 a 100 caracteres con al menos una letra (A-Z, sin tilde) o cifra.
• Consumo medio con las mismas reglas que el vehículo: fuelConsumption solo con combustion o hybrid, electricConsumption solo con electric o hybrid.
• Sin duplicados: no puede haber dos modelos activos de la empresa con el mismo nombre (sin distinguir mayúsculas ni tildes) y la misma energía. El mismo nombre con otra energía sí se admite.
• Corregir un modelo no cambia los vehículos que ya lo usan (copiaron sus datos).
• created dice si fue un alta (true) o una corrección (false).

Errores propios

• 404 company_model_not_found: corrección de un modelo que no existe, es de otra empresa o está retirado.
• 409 company_model_exists: ya hay otro modelo activo con ese nombre y esa energía; error.companyModelId trae el id del que ya existe (o null si no se pudo leer). Se puede dar por guardado.
• 422 invalid_input: cuerpo que no es un objeto JSON; error.fields con name required / invalid / too_long, energy required / invalid, fuelConsumption / electricConsumption invalid (fuera de rango, más de un decimal o no corresponde a la energía), companyModelId invalid o unexpected_field.
• 423 account_read_only: la cuenta no admite cambios (reason: account, suspended o pending_payment).

curl -sS -X POST "https://app.flotadoc.com/api/movimientos/flota/company-models-save" \
  -H "Authorization: Bearer $FLOTADOC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "name": "Renault Kangoo Z.E. 2012",
    "energy": "electric",
    "electricConsumption": 15.5
  }'

{
  "data": {
    "companyModel": {
      "companyModelId": 503,
      "name": "Renault Kangoo Z.E. 2012",
      "energy": "electric",
      "fuelConsumption": null,
      "electricConsumption": 15.5,
      "updatedAt": "2026-10-13T09:30:00.000Z"
    },
    "created": true
  }
}

Retira un modelo de la empresa (baja lógica): deja de salir en la búsqueda y en la lista, y su nombre queda libre para volver a guardarlo. Los vehículos que lo usan conservan sus datos.

Errores propios

• 404 company_model_not_found: el modelo no existe, es de otra empresa o ya está retirado.
• 409: solo por Idempotency-Key (idempotency_conflict, idempotency_in_progress).
• 422 invalid_input: cuerpo que no es un objeto JSON; companyModelId ausente (required) o no válido (invalid); clave no admitida (unexpected_field).
• 423 account_read_only: la cuenta no admite cambios (reason: account, suspended o pending_payment).

curl -sS -X POST "https://app.flotadoc.com/api/movimientos/flota/company-models-delete" \
  -H "Authorization: Bearer $FLOTADOC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "companyModelId": 501
  }'

{
  "data": {
    "deleted": true,
    "companyModelId": 501
  }
}