API de colaboracion de equipos - Steer Autos Documentation

Resumen

La API de colaboracion de equipos permite a concesionarios multiusuario gestionar equipos, invitar miembros, asignar roles y controlar permisos. Ideal para organizaciones con vendedores, managers y administradores.

Funcionalidades clave

Gestion de equipos

Crea y gestiona multiples equipos dentro de tu organizacion

Invitaciones de miembros

Invita miembros por email con asignacion de roles

Acceso por roles

Controla que pueden ver y modificar los miembros

Auditoria

Rastrea actividad y cambios de membresia

Endpoints

Listar todos los equipos

GET

endpoint

/teams

Obtiene todos los equipos con filtros y orden opcionales. Query Parameters:

string

Busca por nombre del equipo o slug

ownerId

string

Filtra por ID del owner

sortBy

enum

Campo de orden: name, createdAt (default: name)

sortOrder

enum

Direccion: asc (default), desc

Response:

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Downtown Dealership",
    "slug": "downtown-dealership",
    "ownerId": "owner_uuid",
    "createdAt": "2024-01-15T10:30:00Z",
    "owner": {
      "id": "owner_uuid",
      "name": "John Doe",
      "email": "[email protected]"
    },
    "memberCount": 12,
    "roleCount": 4,
    "invitationCount": 2
  }
]

Obtener mis equipos

GET

endpoint

/teams/my

Obtiene todos los equipos donde el usuario es miembro o owner. Response: Arreglo de equipos donde el usuario es miembro.

Obtener equipo por ID

GET

endpoint

/teams/

Obtiene informacion detallada de un equipo. Path Parameters:

string

requerido

Team UUID

Query Parameters:

includeDetails

boolean

Incluir miembros, roles e invitaciones (default: false)

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Downtown Dealership",
  "slug": "downtown-dealership",
  "ownerId": "owner_uuid",
  "createdAt": "2024-01-15T10:30:00Z",
  "owner": {
    "id": "owner_uuid",
    "name": "John Doe",
    "email": "[email protected]"
  },
  "members": [
    {
      "id": "member_uuid",
      "name": "Jane Smith",
      "email": "[email protected]",
      "image": "https://...",
      "createdAt": "2024-01-15T10:30:00Z",
      "role": {
        "id": "role_uuid",
        "name": "Sales Manager",
        "permissions": ["view_inventory", "edit_inventory", "view_analytics"]
      },
      "isOwner": false
    }
  ],
  "memberCount": 12,
  "roleCount": 4,
  "invitationCount": 2
}

Obtener equipo por slug

GET

endpoint

/teams/slug/

Obtiene informacion usando el slug del equipo. Path Parameters:

slug

string

requerido

Slug (ej., “downtown-dealership”)

Crear equipo

POST

endpoint

/teams

Crea un equipo nuevo. El usuario autenticado se convierte en owner. Request Body:

{
  "name": "North Branch Dealership",
  "slug": "north-branch"
}

name

string

requerido

Nombre del equipo (max 100 caracteres)

slug

string

requerido

Identificador URL-friendly (minusculas, numeros, guiones, max 50 caracteres)

Response:

{
  "id": "new_team_uuid",
  "name": "North Branch Dealership",
  "slug": "north-branch",
  "ownerId": "current_user_uuid",
  "createdAt": "2024-01-17T11:00:00Z"
}

Actualizar equipo

PATCH

endpoint

/teams/

Actualiza informacion del equipo. Solo el owner puede actualizar. Path Parameters:

string

requerido

Team UUID

Request Body:

{
  "name": "North Branch Dealership - Updated",
  "slug": "north-branch-updated"
}

Eliminar equipo

DELETE

endpoint

/teams/

Elimina un equipo. Solo el owner puede eliminarlo y no debe tener miembros activos (excepto el owner). Path Parameters:

string

requerido

Team UUID

No se puede eliminar equipos con miembros activos. Remueve miembros o transfiere ownership.

Invitar miembro

POST

endpoint

/teams//invite

Invita a un usuario con un rol especifico. Path Parameters:

teamId

string

requerido

Team UUID

Request Body:

{
  "email": "[email protected]",
  "roleId": "role_uuid"
}

string

requerido

Email del usuario a invitar

roleId

string

requerido

Role UUID a asignar

Response:

{
  "id": "invitation_uuid",
  "teamId": "team_uuid",
  "userId": "invited_user_uuid",
  "email": "[email protected]",
  "roleId": "role_uuid",
  "token": "invitation_token",
  "expiresAt": "2024-01-24T11:00:00Z",
  "user": {
    "id": "invited_user_uuid",
    "name": "New Member",
    "email": "[email protected]"
  },
  "role": {
    "id": "role_uuid",
    "name": "Salesperson"
  }
}

El usuario recibe un email con el enlace de invitacion. La invitacion expira en 7 dias.

Aceptar invitacion

POST

endpoint

/teams/accept-invitation

Acepta una invitacion usando el token enviado por email. Request Body:

{
  "token": "invitation_token_from_email"
}

token

string

requerido

Token de invitacion

Response:

{
  "id": "membership_uuid",
  "teamId": "team_uuid",
  "userId": "user_uuid",
  "roleId": "role_uuid",
  "team": {
    "id": "team_uuid",
    "name": "Downtown Dealership",
    "slug": "downtown-dealership"
  },
  "role": {
    "id": "role_uuid",
    "name": "Salesperson",
    "permissions": ["view_inventory", "create_leads"]
  }
}

Obtener miembros del equipo

GET

endpoint

/teams//members

Obtiene todos los miembros con roles y permisos. Path Parameters:

teamId

string

requerido

Team UUID

Response:

[
  {
    "id": "member_uuid",
    "name": "Jane Smith",
    "email": "[email protected]",
    "image": "https://...",
    "createdAt": "2024-01-15T10:30:00Z",
    "role": {
      "id": "role_uuid",
      "name": "Sales Manager",
      "permissions": [
        "view_inventory",
        "edit_inventory",
        "delete_inventory",
        "view_analytics",
        "manage_leads",
        "invite_members"
      ]
    },
    "isOwner": false
  }
]

Obtener invitaciones pendientes

GET

endpoint

/teams//invitations

Obtiene invitaciones pendientes (no aceptadas) para un equipo. Path Parameters:

teamId

string

requerido

Team UUID

Response:

[
  {
    "id": "invitation_uuid",
    "teamId": "team_uuid",
    "email": "[email protected]",
    "roleId": "role_uuid",
    "expiresAt": "2024-01-24T11:00:00Z",
    "user": {
      "id": "user_uuid",
      "name": "Pending User",
      "email": "[email protected]"
    },
    "role": {
      "id": "role_uuid",
      "name": "Salesperson"
    }
  }
]

Remover miembro del equipo

DELETE

endpoint

/teams//members/

Elimina un miembro del equipo. Requiere permisos adecuados. Path Parameters:

teamId

string

requerido

Team UUID

memberId

string

requerido

User ID del miembro a eliminar

Response:

{
  "success": true,
  "message": "Member removed from team successfully"
}

No se puede eliminar al owner. Transfiere ownership si es necesario.

Cancelar invitacion

DELETE

endpoint

/teams/invitations//cancel

Cancela una invitacion pendiente. Path Parameters:

invitationId

string

requerido

Invitation UUID

Response:

{
  "success": true,
  "message": "Invitation cancelled successfully"
}

Obtener equipos del usuario

GET

endpoint

/teams/user/

Obtiene todos los equipos asociados a un usuario. Path Parameters:

userId

string

requerido

User UUID

Roles y permisos

Roles por defecto

Role	Permissions	Description
Owner	Todos los permisos	Control total del equipo y recursos
Admin	Todos excepto eliminar equipo	Gestiona miembros e inventario
Manager	Ver/editar inventario, analitica, leads	Manager de ventas
Salesperson	Ver inventario, crear/editar leads	Vendedor
Viewer	Solo lectura	Acceso solo lectura

Sistema de permisos

Permisos comunes:

view_inventory - Ver vehiculos y listados
edit_inventory - Modificar informacion de vehiculos
delete_inventory - Eliminar vehiculos
create_leads - Crear leads
manage_leads - Editar y eliminar leads
view_analytics - Acceso a dashboard y reportes
manage_kpis - Configurar KPIs
invite_members - Invitar miembros
remove_members - Eliminar miembros
manage_roles - Crear y modificar roles
manage_team - Editar configuracion del equipo

Casos de uso

Ejemplo 1: Crear equipo de concesionario

# Create team
curl -X POST "https://api.steerai.autos/v1/teams" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Prime Auto Group",
    "slug": "prime-auto-group"
  }'

Ejemplo 2: Invitar equipo de ventas

# Invite salesperson
curl -X POST "https://api.steerai.autos/v1/teams/{teamId}/invite" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "roleId": "salesperson_role_uuid"
  }'

Ejemplo 3: Monitorear actividad del equipo

# Get team members
curl -X GET "https://api.steerai.autos/v1/teams/{teamId}/members" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get pending invitations
curl -X GET "https://api.steerai.autos/v1/teams/{teamId}/invitations" \
  -H "Authorization: Bearer YOUR_API_KEY"

Codigos de error

Code	Status	Description
`TEAM_NOT_FOUND`	404	El ID del equipo no existe
`SLUG_ALREADY_EXISTS`	400	El slug del equipo ya existe
`NOT_TEAM_OWNER`	403	Solo el owner puede realizar esta accion
`INSUFFICIENT_PERMISSIONS`	403	El usuario no tiene permisos
`ALREADY_TEAM_MEMBER`	400	El usuario ya es miembro
`INVITATION_EXPIRED`	400	El token de invitacion expiro
`INVITATION_NOT_FOUND`	404	La invitacion no existe
`CANNOT_REMOVE_OWNER`	400	No se puede eliminar al owner
`TEAM_HAS_MEMBERS`	400	No se puede eliminar equipo con miembros

Mejores practicas

Usa nombres y slugs descriptivos

Elige nombres claros y profesionales. Los slugs deben ser URL-friendly y memorables.

Implementa control de acceso por roles

Asigna roles segun funciones. No des acceso admin a todos.

Revisa membresias regularmente

Audita miembros trimestralmente. Elimina inactivos y ajusta roles.

Configura recordatorios de expiracion

Da seguimiento a invitaciones pendientes antes de que expiren (7 dias).

Documenta roles personalizados

Si creas roles custom, documenta permisos claramente.

Usa slugs para routing

Usa slugs en URLs para links mas limpios y compartibles.

Patrones de integracion

Arquitectura multi-tenant

// Check user's team membership
async function getUserTeams(userId) {
  const response = await fetch(
    `https://api.steerai.autos/v1/teams/user/${userId}`,
    {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    }
  );
  return response.json();
}

// Filter data by team context
async function getTeamInventory(teamId) {
  const response = await fetch(
    `https://api.steerai.autos/v1/vehicles?teamId=${teamId}`,
    {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    }
  );
  return response.json();
}

Verificacion de permisos

function hasPermission(member, permission) {
  return member.role.permissions.includes(permission) || member.isOwner;
}

// Usage
if (hasPermission(currentMember, 'edit_inventory')) {
  // Show edit controls
}

Recursos relacionados

API de autenticacion

Autenticacion de usuarios y sesiones

Roles y permisos

Guia detallada de permisos

Configuracion multi-tenant

Mejores practicas para multiples ubicaciones

Guia de seguridad

Mejores practicas de seguridad para equipos

Documentacion de la API

​Resumen

​Funcionalidades clave

Gestion de equipos

Invitaciones de miembros

Acceso por roles

Auditoria

​Endpoints

​Listar todos los equipos

​Obtener mis equipos

​Obtener equipo por ID

​Obtener equipo por slug

​Crear equipo

​Actualizar equipo

​Eliminar equipo

​Invitar miembro

​Aceptar invitacion

​Obtener miembros del equipo

​Obtener invitaciones pendientes

​Remover miembro del equipo

​Cancelar invitacion

​Obtener equipos del usuario

​Roles y permisos

​Roles por defecto

​Sistema de permisos

​Casos de uso

​Ejemplo 1: Crear equipo de concesionario

​Ejemplo 2: Invitar equipo de ventas

​Ejemplo 3: Monitorear actividad del equipo

​Codigos de error

​Mejores practicas

​Patrones de integracion

​Arquitectura multi-tenant

​Verificacion de permisos

​Recursos relacionados

API de autenticacion

Roles y permisos

Configuracion multi-tenant

Guia de seguridad

Resumen

Funcionalidades clave

Endpoints

Listar todos los equipos

Obtener mis equipos

Obtener equipo por ID

Obtener equipo por slug

Crear equipo

Actualizar equipo

Eliminar equipo

Invitar miembro

Aceptar invitacion

Obtener miembros del equipo

Obtener invitaciones pendientes

Remover miembro del equipo

Cancelar invitacion

Obtener equipos del usuario

Roles y permisos

Roles por defecto

Sistema de permisos

Casos de uso

Ejemplo 1: Crear equipo de concesionario

Ejemplo 2: Invitar equipo de ventas

Ejemplo 3: Monitorear actividad del equipo

Codigos de error

Mejores practicas

Patrones de integracion

Arquitectura multi-tenant

Verificacion de permisos

Recursos relacionados