Conductores

Devuelve todas las personas de la empresa (responsables owner, conductores user y asesoría gestor) con su estado, y las plazas ocupadas del plan. Con clave API ves lo mismo que el owner que creó la clave: todo el equipo, no solo los conductores. Para quedarte con los conductores, filtra por role: user.

• Incluye invitados, activos y desactivados (también a quien ha pedido la baja: status: inactive con deletion). No incluye al equipo de FlotaDoc ni a las personas ya anonimizadas tras su baja.
• Sin filtros ni paginación: una sola respuesta con todo el equipo, ordenada por nombre (sin distinguir mayúsculas) y después por id. Para una persona concreta, usa get.
• seats dice cuántas plazas quedan antes de invitar o reactivar (los mismos números que comprueban invite y reactivate).
• Funciona también con la cuenta de la empresa en solo lectura.
• El cuerpo puede ir vacío o ser {}.

Errores propios

• 422 invalid_input: el cuerpo no es un objeto JSON, o trae una clave distinta de tenantId (fields.<clave>: unexpected_field).

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

{
  "data": {
    "users": [
      {
        "id": 5,
        "email": "ana.garcia@transportesgarcia.es",
        "fullName": "Ana García",
        "role": "owner",
        "status": "active",
        "isBillingOwner": true,
        "lastLoginAt": "2026-10-13T07:45:12.000Z",
        "inviteExpiresAt": null,
        "deletion": null
      },
      {
        "id": 42,
        "email": "luis.perez@transportesgarcia.es",
        "fullName": "Luis Pérez",
        "role": "user",
        "status": "invited",
        "isBillingOwner": false,
        "lastLoginAt": null,
        "inviteExpiresAt": "2026-10-20T09:30:00.000Z",
        "deletion": null
      },
      {
        "id": 17,
        "email": "marta.ruiz@transportesgarcia.es",
        "fullName": "Marta Ruiz",
        "role": "user",
        "status": "inactive",
        "isBillingOwner": false,
        "lastLoginAt": "2026-09-30T16:02:41.000Z",
        "inviteExpiresAt": null,
        "deletion": null
      },
      {
        "id": 9,
        "email": "asesoria@gestoriasol.es",
        "fullName": "Gestoría Sol",
        "role": "gestor",
        "status": "active",
        "isBillingOwner": false,
        "lastLoginAt": "2026-10-02T10:15:00.000Z",
        "inviteExpiresAt": null,
        "deletion": null
      }
    ],
    "seats": {
      "users": {
        "used": 1,
        "limit": 5
      },
      "gestores": {
        "used": 1,
        "limit": 1
      }
    }
  }
}

Devuelve una persona de la empresa por su userId, con el mismo objeto que list. Con clave API sirve para cualquier persona de la empresa (no solo conductores), igual que para el owner.

Útil para seguir una invitación (status pasa de invited a active cuando el conductor crea su contraseña) o comprobar el estado tras deactivate o reactivate.

Errores propios

• 404 user_not_found: no existe, es de otra empresa, es del equipo de FlotaDoc o ya se anonimizó tras su baja (no se distingue).
• 422 invalid_input: fields.userId (required o invalid), o una clave no admitida (unexpected_field).

curl -sS -X POST "https://app.flotadoc.com/api/auth/usuarios/get" \
  -H "Authorization: Bearer $FLOTADOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": 42
  }'

{
  "data": {
    "user": {
      "id": 42,
      "email": "luis.perez@transportesgarcia.es",
      "fullName": "Luis Pérez",
      "role": "user",
      "status": "active",
      "isBillingOwner": false,
      "lastLoginAt": "2026-10-13T15:12:44.000Z",
      "inviteExpiresAt": null,
      "deletion": null
    }
  }
}

Da de alta a un conductor como invitado y le envía por email un enlace para crear su contraseña. Con clave API solo se invitan conductores (role: user). El email sale a nombre del owner que creó la clave: «{owner} te invita a {empresa} en FlotaDoc», con el botón «Aceptar la invitación».

Qué hace, en orden:

1. Valida y normaliza el cuerpo: email sin espacios alrededor y en minúsculas; nombre sin espacios sobrantes (los internos se reducen a uno).
2. Exige que la empresa pueda registrar (423) y que el email no esté ya en uso en la empresa (409 email_in_use). El email es único por empresa, no global: la misma persona puede estar en otra empresa de FlotaDoc.
3. Exige plaza de usuario (409 seat_limit): ocupan plaza los conductores y los owners (salvo el titular), invitados incluidos; los desactivados no.
4. Crea el usuario con status: invited y su invitación: un enlace de un solo uso a https://app.flotadoc.com/invitacion?token=… que caduca a los 7 días (inviteExpiresAt).
5. Envía el email. Si el envío falla, el conductor queda invitado igualmente y la respuesta lleva emailSent: false: reenvíalo con resend-invite (pasado al menos un minuto).

El conductor abre el enlace, crea su contraseña (de 8 caracteres a 72 bytes) y pasa a active; desde entonces entra con su email en la app móvil o en la web. Ya como invitado se le pueden asignar vehículos fijos (movimientos/flota/assign) y registrar viajes o gastos a su nombre (driverUserId).

Con Idempotency-Key, un reintento devuelve el mismo 201 sin crear otro usuario ni enviar otro email.

Errores propios

• 403 api_role_not_allowed: role es owner o gestor. Se comprueba tras validar los campos y antes de crear nada.
• 404 tenant_not_found: la empresa ya no existe (no debería darse con una clave válida).
• 409 email_in_use: ya hay una persona con ese email en la empresa, con cualquier rol. Trae userId y status de esa persona: si es invited, usa resend-invite; si es inactive, reactivate (con clave, solo si su rol es user).
• 409 seat_limit: no quedan plazas de usuario. Trae resource: users, limit, used y next: contact_us: ampliar plazas lo gestiona el owner con FlotaDoc («Habla con nosotros»).
• 422 invalid_input: fields con todos los errores a la vez: email (required, invalid, too_long, invalid_email), fullName (required, invalid, too_long), role (required, invalid_role), o una clave no admitida (unexpected_field).
• 423 account_read_only: la empresa no puede registrar ahora. reason: account (cuenta en solo lectura: prueba o contrato vencidos, cancelada…), suspended (suspendida por FlotaDoc) o pending_payment (la cuenta aún no está activa).

curl -sS -X POST "https://app.flotadoc.com/api/auth/usuarios/invite" \
  -H "Authorization: Bearer $FLOTADOC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "email": "Luis.Perez@TransportesGarcia.es",
    "fullName": "Luis Pérez",
    "role": "user"
  }'

{
  "data": {
    "user": {
      "id": 42,
      "email": "luis.perez@transportesgarcia.es",
      "fullName": "Luis Pérez",
      "role": "user",
      "status": "invited",
      "isBillingOwner": false,
      "lastLoginAt": null,
      "inviteExpiresAt": "2026-10-20T09:30:00.000Z",
      "deletion": null
    },
    "emailSent": true
  }
}

Envía otra vez la invitación a un conductor que aún no la ha aceptado (status: invited). Genera un enlace nuevo (el anterior deja de valer) y los 7 días vuelven a contar desde ahora (inviteExpiresAt). No ocupa otra plaza.

Úsalo si invite devolvió emailSent: false, si la invitación caducó (inviteExpiresAt ya pasado) o si el conductor no encuentra el email. Entre dos envíos al mismo conductor (también el de invite) tiene que pasar al menos un minuto.

Con clave API, solo para usuarios con rol user: con otro rol responde 403 y el enlace que tuviera sigue valiendo (no se rota).

Con Idempotency-Key, un reintento devuelve la respuesta guardada sin enviar otro email.

Errores propios

• 403 api_role_not_allowed: la persona no es conductor (owner o gestor).
• 404 user_not_found: no existe en la empresa (o ya se anonimizó tras su baja).
• 404 tenant_not_found: la empresa ya no existe (no debería darse con una clave válida).
• 409 not_invited: ya no está invitado; status dice por qué: active (ya aceptó: que entre con su contraseña) o inactive (desactivado: primero reactivate).
• 422 invalid_input: fields.userId (required o invalid), o una clave no admitida (unexpected_field).
• 423 account_read_only: la empresa no puede registrar ahora (reason: account, suspended o pending_payment). Se comprueba antes de buscar al usuario.
• 429 resend_too_soon: no ha pasado un minuto desde el último envío. Como rate_limited, lleva la cabecera Retry-After y retryAfterSeconds en el cuerpo (segundos que faltan, de 1 a 60). Reintenta pasado ese tiempo con otra Idempotency-Key: con la misma te devuelve este 429 guardado.

curl -sS -X POST "https://app.flotadoc.com/api/auth/usuarios/resend-invite" \
  -H "Authorization: Bearer $FLOTADOC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "userId": 42
  }'

{
  "data": {
    "user": {
      "id": 42,
      "email": "luis.perez@transportesgarcia.es",
      "fullName": "Luis Pérez",
      "role": "user",
      "status": "invited",
      "isBillingOwner": false,
      "lastLoginAt": null,
      "inviteExpiresAt": "2026-10-22T11:04:37.000Z",
      "deletion": null
    },
    "emailSent": true
  }
}

Quita el acceso a un conductor sin borrarlo (status: inactive). Se deshace con reactivate.

• No puede entrar: sus sesiones abiertas dejan de valer (en un máximo de 5 minutos) y, si aún estaba invitado, su enlace de invitación deja de funcionar.
• Deja de ocupar plaza.
• Sus viajes, gastos, tickets y firmas se conservan y siguen en los informes, los cierres y el libro de viajes.
• No se le quita de los vehículos fijos que tenía asignados (sigue saliendo en sus drivers), pero ya no se le pueden registrar viajes ni gastos nuevos (422 invalid_input con fields.driverUserId: not_found) ni volver a asignar: al actualizar los conductores de esos vehículos con movimientos/flota/assign, déjalo fuera (si no, 422 invalid_input con invalidUserIds).
• Si ya estaba desactivado: 200 sin cambios.
• Funciona también con la cuenta de la empresa en solo lectura: quitar el acceso a quien se va no espera a que la cuenta se regularice.

Con clave API, solo sobre usuarios con rol user (también si ya estaban desactivados). El rol se comprueba en la misma operación que desactiva: si alguien lo cambia a la vez desde la web, la clave ve el rol nuevo.

Errores propios

• 403 api_role_not_allowed: la persona no es conductor (owner o gestor).
• 404 user_not_found: no existe en la empresa (o ya se anonimizó tras su baja).
• 409 cannot_modify_self: userId es el owner que creó la clave.
• 422 invalid_input: fields.userId (required o invalid), o una clave no admitida (unexpected_field).

curl -sS -X POST "https://app.flotadoc.com/api/auth/usuarios/deactivate" \
  -H "Authorization: Bearer $FLOTADOC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "userId": 42
  }'

{
  "data": {
    "user": {
      "id": 42,
      "email": "luis.perez@transportesgarcia.es",
      "fullName": "Luis Pérez",
      "role": "user",
      "status": "inactive",
      "isBillingOwner": false,
      "lastLoginAt": "2026-10-13T15:12:44.000Z",
      "inviteExpiresAt": null,
      "deletion": null
    }
  }
}

Devuelve el acceso a un conductor desactivado. Vuelve a ocupar plaza.

• Si ya había creado su contraseña, queda active y puede entrar enseguida con la misma.
• Si nunca aceptó la invitación, vuelve a invited: su enlace anterior vuelve a valer si no ha caducado (inviteExpiresAt). Si caducó, envíale otro con resend-invite. Reactivar no envía ningún email.
• Si no estaba desactivado: 200 sin cambios (no mira plazas).

Con clave API, solo sobre usuarios con rol user. El rol se vuelve a comprobar en la misma operación que reactiva.

Errores propios (en el orden en que se comprueban)

• 423 account_read_only: la empresa no puede registrar ahora (reason: account, suspended o pending_payment).
• 404 user_not_found: no existe en la empresa (o ya se anonimizó tras su baja).
• 403 api_role_not_allowed: la persona no es conductor (owner o gestor).
• 409 deletion_pending: la propia persona pidió darse de baja. Solo la deshace el owner desde la web, no la API.
• 409 seat_limit: no quedan plazas de usuario. Trae resource: users, limit, used y next: contact_us.
• 422 invalid_input: fields.userId (required o invalid), o una clave no admitida (unexpected_field). Se comprueba antes que todo lo anterior.

curl -sS -X POST "https://app.flotadoc.com/api/auth/usuarios/reactivate" \
  -H "Authorization: Bearer $FLOTADOC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "userId": 42
  }'

{
  "data": {
    "user": {
      "id": 42,
      "email": "luis.perez@transportesgarcia.es",
      "fullName": "Luis Pérez",
      "role": "user",
      "status": "active",
      "isBillingOwner": false,
      "lastLoginAt": "2026-10-13T15:12:44.000Z",
      "inviteExpiresAt": null,
      "deletion": null
    }
  }
}