Usuarios

CRUD del equipo de la empresa asociada a tu API key. Cubre identidad básica, el slug de agendas (booking_slug) y la personalización del fondo de la landing pública (settings_preferences.booking_branding) para que puedas montar todo el flujo de agenda desde tu integración.

La creación de usuarios está limitada por Company.max_team_size. Cuando la empresa ya está en el tope, POST /users responde 422 con error: "team_limit_reached".

El objeto User

{
  "id":           "65a1b2c3d4e5f6789012abcd",
  "first_name":   "Fabián",
  "last_name":    "García",
  "full_name":    "Fabián García",
  "email":        "fabian@example.com",
  "phone":        "+52 656 1234567",
  "username":     "fabian-garcia",
  "booking_slug": "fabian",
  "booking_url":  "https://book.fi-nova.com/fabian",
  "avatar_url":   "https://cdn.finova.com/v1/avatar/fabian-garcia/avatar-...",
  "is_owner":     true,
  "settings_preferences": {
    "theme":                       "light",
    "block_overlapping_bookings":  true,
    "booking_branding": {
      "theme": "dark",
      "light": { "bg_mode": "solid",  "bg_color_from": "#f9fafb", "bg_color_to": "#e5e7eb", "bg_angle": 135 },
      "dark":  { "bg_mode": "linear", "bg_color_from": "#0080ff", "bg_color_to": "#001a33", "bg_angle": 135 }
    }
  },
  "created_at": "2026-02-08T11:00:00Z",
  "updated_at": "2026-05-17T14:30:21Z"
}

Campos editables

Campo	Tipo	Descripción
first_name, last_name	string	Nombre del usuario.
email	string	Correo único en Finova. Si ya existe, POST devuelve 409 email_taken.
phone	string	Teléfono de contacto (formato libre).
username	string	Identificador interno.
birthdate	string (YYYY-MM-DD)	Opcional.
booking_slug	string	Slug público del usuario en book.fi-nova.com/<slug>/<liga>. Sólo [a-z0-9-], 3–64 caracteres. Único globalmente.
is_owner	boolean	Si es true, el usuario recibe todos los permisos de la empresa.
settings_preferences.theme	"light" | "dark" | "schedule"	Tema del dashboard.
settings_preferences.block_overlapping_bookings	boolean	Si la liga debe bloquear horarios ocupados en Google/Finova.
settings_preferences.booking_branding.theme	"light" | "dark"	Solo es un hint del dashboard para saber qué paleta está editando el host. No controla la landing pública — la landing elige el modo por la hora local del visitante (oscuro de 7pm a 7am) y el visitante puede alternar con un botón en pantalla.
settings_preferences.booking_branding.light.bg_mode	"solid" | "linear" | "radial"	Tipo de fondo cuando la landing se ve en modo claro.
settings_preferences.booking_branding.light.bg_color_from	string hex	Color sólido / inicial del gradiente del modo claro.
settings_preferences.booking_branding.light.bg_color_to	string hex	Color final del gradiente del modo claro (sólo linear/radial).
settings_preferences.booking_branding.light.bg_angle	integer 0-360	Ángulo del gradiente lineal en modo claro.
settings_preferences.booking_branding.dark.bg_mode	"solid" | "linear" | "radial"	Mismo concepto que light.bg_mode, pero para modo oscuro.
settings_preferences.booking_branding.dark.bg_color_from	string hex	Color sólido / inicial del gradiente del modo oscuro.
settings_preferences.booking_branding.dark.bg_color_to	string hex	Color final del gradiente del modo oscuro.
settings_preferences.booking_branding.dark.bg_angle	integer 0-360	Ángulo del gradiente lineal en modo oscuro.

Devise-managed columns (encrypted_password, jti, tokens de reseteo, etc.) nunca se exponen ni se aceptan en el payload.

Scopes requeridos

Acción	Scope
GET /users, GET /users/:id	read-users
POST /users	create-users
PUT /users/:id, POST /users/:id/avatar	update-users
DELETE /users/:id	delete-users

Listar usuarios

GET /api/v1/users

Paginación cursor / offset estándar (?starting_after=, ?ending_before=, ?page=, ?limit=). Solo regresa usuarios miembros de la empresa de la API key.

Crear un usuario

POST /api/v1/users
Content-Type: application/json

{
  "data": {
    "first_name": "Carla",
    "last_name":  "Pineda",
    "email":      "carla@example.com",
    "phone":      "+52 656 9876543",
    "booking_slug": "carla",
    "is_owner": false,
    "settings_preferences": {
      "theme": "light",
      "block_overlapping_bookings": true,
      "booking_branding": {
        "bg_mode":       "radial",
        "bg_color_from": "#0080ff",
        "bg_color_to":   "#001a33"
      }
    }
  }
}

El usuario se crea con una contraseña aleatoria; usa el flujo de recuperación estándar de Finova si necesitas acceso interactivo.

Errores comunes

Status	error	Cuándo
422	team_limit_reached	La empresa alcanzó max_team_size.
409	email_taken	Ya existe un usuario con ese correo.
422	validation_failed	Slug duplicado o con formato inválido, etc.

Actualizar un usuario

PUT /api/v1/users/:id
Content-Type: application/json

{
  "data": {
    "booking_slug": "carla-pineda",
    "settings_preferences": {
      "booking_branding": { "bg_mode": "solid", "bg_color_from": "#1f2937" }
    }
  }
}

Cualquier subconjunto del payload de create es aceptado. is_owner se aplica sobre el CompanyMembership del usuario en la empresa de la API key.

Subir foto de perfil

POST /api/v1/users/:id/avatar
Content-Type: multipart/form-data

avatar: <archivo JPG/PNG>

Regresa el objeto User con avatar_url actualizado. La misma URL se usa como fallback del logo en la landing pública cuando la empresa no tiene logo.

Eliminar un usuario

DELETE /api/v1/users/:id

Quita al usuario de la membresía de la empresa. Si era su única empresa, el registro se soft-deletea (Paranoia) para conservar referencias de auditoría.

No puedes eliminar al usuario dueño de la API key — el servidor responde 403 self_delete_forbidden.