> ## Documentation Index
> Fetch the complete documentation index at: https://docs.steerai.autos/llms.txt
> Use this file to discover all available pages before exploring further.

# API de colaboracion de equipos

> Gestion de equipos multiusuario, invitaciones y control de acceso por roles

## 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

<CardGroup cols={2}>
  <Card title="Gestion de equipos" icon="users">
    Crea y gestiona multiples equipos dentro de tu organizacion
  </Card>

  <Card title="Invitaciones de miembros" icon="envelope">
    Invita miembros por email con asignacion de roles
  </Card>

  <Card title="Acceso por roles" icon="shield">
    Controla que pueden ver y modificar los miembros
  </Card>

  <Card title="Auditoria" icon="clock">
    Rastrea actividad y cambios de membresia
  </Card>
</CardGroup>

## Endpoints

### Listar todos los equipos

<ParamField path="GET" type="endpoint">
  /teams
</ParamField>

Obtiene todos los equipos con filtros y orden opcionales.

**Query Parameters:**

<ParamField query="search" type="string">
  Busca por nombre del equipo o slug
</ParamField>

<ParamField query="ownerId" type="string">
  Filtra por ID del owner
</ParamField>

<ParamField query="sortBy" type="enum">
  Campo de orden: `name`, `createdAt` (default: name)
</ParamField>

<ParamField query="sortOrder" type="enum">
  Direccion: `asc` (default), `desc`
</ParamField>

**Response:**

```json theme={null}
[
  {
    "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": "john@dealership.com"
    },
    "memberCount": 12,
    "roleCount": 4,
    "invitationCount": 2
  }
]
```

***

### Obtener mis equipos

<ParamField path="GET" type="endpoint">
  /teams/my
</ParamField>

Obtiene todos los equipos donde el usuario es miembro o owner.

**Response:**

Arreglo de equipos donde el usuario es miembro.

***

### Obtener equipo por ID

<ParamField path="GET" type="endpoint">
  /teams/{id}
</ParamField>

Obtiene informacion detallada de un equipo.

**Path Parameters:**

<ParamField path="id" type="string" required>
  Team UUID
</ParamField>

**Query Parameters:**

<ParamField query="includeDetails" type="boolean">
  Incluir miembros, roles e invitaciones (default: false)
</ParamField>

**Response:**

```json theme={null}
{
  "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": "john@dealership.com"
  },
  "members": [
    {
      "id": "member_uuid",
      "name": "Jane Smith",
      "email": "jane@dealership.com",
      "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

<ParamField path="GET" type="endpoint">
  /teams/slug/{slug}
</ParamField>

Obtiene informacion usando el slug del equipo.

**Path Parameters:**

<ParamField path="slug" type="string" required>
  Slug (ej., "downtown-dealership")
</ParamField>

***

### Crear equipo

<ParamField path="POST" type="endpoint">
  /teams
</ParamField>

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

**Request Body:**

```json theme={null}
{
  "name": "North Branch Dealership",
  "slug": "north-branch"
}
```

<ParamField body="name" type="string" required>
  Nombre del equipo (max 100 caracteres)
</ParamField>

<ParamField body="slug" type="string" required>
  Identificador URL-friendly (minusculas, numeros, guiones, max 50 caracteres)
</ParamField>

**Response:**

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

***

### Actualizar equipo

<ParamField path="PATCH" type="endpoint">
  /teams/{id}
</ParamField>

Actualiza informacion del equipo. Solo el owner puede actualizar.

**Path Parameters:**

<ParamField path="id" type="string" required>
  Team UUID
</ParamField>

**Request Body:**

```json theme={null}
{
  "name": "North Branch Dealership - Updated",
  "slug": "north-branch-updated"
}
```

***

### Eliminar equipo

<ParamField path="DELETE" type="endpoint">
  /teams/{id}
</ParamField>

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

**Path Parameters:**

<ParamField path="id" type="string" required>
  Team UUID
</ParamField>

<Warning>
  No se puede eliminar equipos con miembros activos. Remueve miembros o transfiere ownership.
</Warning>

***

### Invitar miembro

<ParamField path="POST" type="endpoint">
  /teams/{teamId}/invite
</ParamField>

Invita a un usuario con un rol especifico.

**Path Parameters:**

<ParamField path="teamId" type="string" required>
  Team UUID
</ParamField>

**Request Body:**

```json theme={null}
{
  "email": "newmember@dealership.com",
  "roleId": "role_uuid"
}
```

<ParamField body="email" type="string" required>
  Email del usuario a invitar
</ParamField>

<ParamField body="roleId" type="string" required>
  Role UUID a asignar
</ParamField>

**Response:**

```json theme={null}
{
  "id": "invitation_uuid",
  "teamId": "team_uuid",
  "userId": "invited_user_uuid",
  "email": "newmember@dealership.com",
  "roleId": "role_uuid",
  "token": "invitation_token",
  "expiresAt": "2024-01-24T11:00:00Z",
  "user": {
    "id": "invited_user_uuid",
    "name": "New Member",
    "email": "newmember@dealership.com"
  },
  "role": {
    "id": "role_uuid",
    "name": "Salesperson"
  }
}
```

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

***

### Aceptar invitacion

<ParamField path="POST" type="endpoint">
  /teams/accept-invitation
</ParamField>

Acepta una invitacion usando el token enviado por email.

**Request Body:**

```json theme={null}
{
  "token": "invitation_token_from_email"
}
```

<ParamField body="token" type="string" required>
  Token de invitacion
</ParamField>

**Response:**

```json theme={null}
{
  "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

<ParamField path="GET" type="endpoint">
  /teams/{teamId}/members
</ParamField>

Obtiene todos los miembros con roles y permisos.

**Path Parameters:**

<ParamField path="teamId" type="string" required>
  Team UUID
</ParamField>

**Response:**

```json theme={null}
[
  {
    "id": "member_uuid",
    "name": "Jane Smith",
    "email": "jane@dealership.com",
    "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

<ParamField path="GET" type="endpoint">
  /teams/{teamId}/invitations
</ParamField>

Obtiene invitaciones pendientes (no aceptadas) para un equipo.

**Path Parameters:**

<ParamField path="teamId" type="string" required>
  Team UUID
</ParamField>

**Response:**

```json theme={null}
[
  {
    "id": "invitation_uuid",
    "teamId": "team_uuid",
    "email": "pending@dealership.com",
    "roleId": "role_uuid",
    "expiresAt": "2024-01-24T11:00:00Z",
    "user": {
      "id": "user_uuid",
      "name": "Pending User",
      "email": "pending@dealership.com"
    },
    "role": {
      "id": "role_uuid",
      "name": "Salesperson"
    }
  }
]
```

***

### Remover miembro del equipo

<ParamField path="DELETE" type="endpoint">
  /teams/{teamId}/members/{memberId}
</ParamField>

Elimina un miembro del equipo. Requiere permisos adecuados.

**Path Parameters:**

<ParamField path="teamId" type="string" required>
  Team UUID
</ParamField>

<ParamField path="memberId" type="string" required>
  User ID del miembro a eliminar
</ParamField>

**Response:**

```json theme={null}
{
  "success": true,
  "message": "Member removed from team successfully"
}
```

<Warning>
  No se puede eliminar al owner. Transfiere ownership si es necesario.
</Warning>

***

### Cancelar invitacion

<ParamField path="DELETE" type="endpoint">
  /teams/invitations/{invitationId}/cancel
</ParamField>

Cancela una invitacion pendiente.

**Path Parameters:**

<ParamField path="invitationId" type="string" required>
  Invitation UUID
</ParamField>

**Response:**

```json theme={null}
{
  "success": true,
  "message": "Invitation cancelled successfully"
}
```

***

### Obtener equipos del usuario

<ParamField path="GET" type="endpoint">
  /teams/user/{userId}
</ParamField>

Obtiene todos los equipos asociados a un usuario.

**Path Parameters:**

<ParamField path="userId" type="string" required>
  User UUID
</ParamField>

***

## 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

```bash theme={null}
# 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

```bash theme={null}
# 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": "salesperson@dealership.com",
    "roleId": "salesperson_role_uuid"
  }'
```

### Ejemplo 3: Monitorear actividad del equipo

```bash theme={null}
# 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

<AccordionGroup>
  <Accordion title="Usa nombres y slugs descriptivos">
    Elige nombres claros y profesionales. Los slugs deben ser URL-friendly y memorables.
  </Accordion>

  <Accordion title="Implementa control de acceso por roles">
    Asigna roles segun funciones. No des acceso admin a todos.
  </Accordion>

  <Accordion title="Revisa membresias regularmente">
    Audita miembros trimestralmente. Elimina inactivos y ajusta roles.
  </Accordion>

  <Accordion title="Configura recordatorios de expiracion">
    Da seguimiento a invitaciones pendientes antes de que expiren (7 dias).
  </Accordion>

  <Accordion title="Documenta roles personalizados">
    Si creas roles custom, documenta permisos claramente.
  </Accordion>

  <Accordion title="Usa slugs para routing">
    Usa slugs en URLs para links mas limpios y compartibles.
  </Accordion>
</AccordionGroup>

## Patrones de integracion

### Arquitectura multi-tenant

```javascript theme={null}
// 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

```javascript theme={null}
function hasPermission(member, permission) {
  return member.role.permissions.includes(permission) || member.isOwner;
}

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

## Recursos relacionados

<CardGroup cols={2}>
  <Card title="API de autenticacion" icon="key" href="/es/api-reference/auth/authentication">
    Autenticacion de usuarios y sesiones
  </Card>

  <Card title="Roles y permisos" icon="shield-halved" href="/es/guides/roles-permissions">
    Guia detallada de permisos
  </Card>

  <Card title="Configuracion multi-tenant" icon="building" href="/es/guides/multi-tenant">
    Mejores practicas para multiples ubicaciones
  </Card>

  <Card title="Guia de seguridad" icon="lock" href="/es/guides/security">
    Mejores practicas de seguridad para equipos
  </Card>
</CardGroup>