API de collaboration d'équipe - Steer Autos Documentation

Vue d’ensemble

L’API de collaboration d’equipe permet aux concessions multi-utilisateurs de gerer des equipes, d’inviter des membres, d’assigner des roles et de controler les autorisations d’acces. Ideale pour les organisations avec plusieurs vendeurs, managers et administrateurs.

Fonctionnalites cles

Gestion d'equipe

Creer et gerer plusieurs equipes au sein de votre organisation

Invitations de membres

Inviter des membres par email avec attribution de roles

Acces base sur les roles

Controler ce que les membres peuvent consulter et modifier

Journal d'audit

Suivre les activites d’equipe et les changements de membres

Endpoints

Lister toutes les equipes

GET

endpoint

/teams

Recuperer toutes les equipes avec filtrage et tri optionnels. Parametres de requete :

string

Rechercher par nom d’equipe ou slug

ownerId

string

Filtrer par ID du proprietaire de l’equipe

sortBy

enum

Champ de tri : name, createdAt (defaut : name)

sortOrder

enum

Sens du tri : asc (defaut), desc

Reponse :

[
  {
    "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
  }
]

Obtenir mes equipes

GET

endpoint

/teams/my

Recuperer toutes les equipes dont l’utilisateur courant est membre ou proprietaire. Reponse : Tableau d’objets equipe ou l’utilisateur est membre.

Obtenir une equipe par ID

GET

endpoint

/teams/

Recuperer les informations detaillees d’une equipe specifique. Parametres de chemin :

string

requis

UUID de l’equipe

Parametres de requete :

includeDetails

boolean

Inclure les membres, roles et invitations en attente (defaut : false)

Reponse :

{
  "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
}

Obtenir une equipe par slug

GET

endpoint

/teams/slug/

Recuperer les informations d’une equipe via son slug URL. Parametres de chemin :

slug

string

requis

Slug d’equipe (ex. “downtown-dealership”)

Creer une equipe

POST

endpoint

/teams

Creer une nouvelle equipe. L’utilisateur authentifie devient proprietaire de l’equipe. Corps de requete :

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

name

string

requis

Nom d’affichage de l’equipe (max 100 caracteres)

slug

string

requis

Identifiant URL (minuscules, chiffres, tirets uniquement, max 50 caracteres)

Reponse :

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

Mettre a jour une equipe

PATCH

endpoint

/teams/

Mettre a jour les informations d’equipe. Seul le proprietaire peut modifier les details. Parametres de chemin :

string

requis

UUID de l’equipe

Corps de requete :

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

Supprimer une equipe

DELETE

endpoint

/teams/

Supprimer une equipe. Seul le proprietaire peut supprimer l’equipe, et elle ne doit pas avoir de membres actifs (sauf le proprietaire). Parametres de chemin :

string

requis

UUID de l’equipe

Impossible de supprimer une equipe avec des membres actifs. Retirez d’abord tous les membres ou transferez la propriete.

Inviter un membre de l’equipe

POST

endpoint

/teams//invite

Inviter un utilisateur a rejoindre l’equipe avec un role specifique. Parametres de chemin :

teamId

string

requis

UUID de l’equipe

Corps de requete :

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

string

requis

Adresse email de l’utilisateur a inviter

roleId

string

requis

UUID du role a attribuer au membre

Reponse :

{
  "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"
  }
}

L’utilisateur invite recevra un email avec un lien d’invitation. L’invitation expire apres 7 jours.

Accepter une invitation d’equipe

POST

endpoint

/teams/accept-invitation

Accepter une invitation d’equipe en utilisant le token recu par email. Corps de requete :

{
  "token": "invitation_token_from_email"
}

token

string

requis

Token d’invitation

Reponse :

{
  "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"]
  }
}

Obtenir les membres de l’equipe

GET

endpoint

/teams//members

Recuperer tous les membres d’une equipe avec leurs roles et autorisations. Parametres de chemin :

teamId

string

requis

UUID de l’equipe

Reponse :

[
  {
    "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
  }
]

Obtenir les invitations en attente

GET

endpoint

/teams//invitations

Recuperer toutes les invitations en attente (non acceptees) pour une equipe. Parametres de chemin :

teamId

string

requis

UUID de l’equipe

Reponse :

[
  {
    "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"
    }
  }
]

Retirer un membre de l’equipe

DELETE

endpoint

/teams//members/

Retirer un membre de l’equipe. Necessite les autorisations appropriees. Parametres de chemin :

teamId

string

requis

UUID de l’equipe

memberId

string

requis

ID de l’utilisateur a retirer

Reponse :

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

Impossible de retirer le proprietaire de l’equipe. Transferez d’abord la propriete si besoin.

Annuler une invitation

DELETE

endpoint

/teams/invitations//cancel

Annuler une invitation d’equipe en attente. Parametres de chemin :

invitationId

string

requis

UUID de l’invitation

Reponse :

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

Obtenir les equipes d’un utilisateur

GET

endpoint

/teams/user/

Recuperer toutes les equipes associees a un utilisateur specifique. Parametres de chemin :

userId

string

requis

UUID de l’utilisateur

Roles et autorisations d’equipe

Roles par defaut

Role	Autorisations	Description
Owner	Toutes les autorisations	Controle total sur l’equipe et toutes les ressources
Admin	Tout sauf suppression d’equipe	Peut gerer les membres, l’inventaire et les parametres
Manager	Voir/Modifier inventaire, Analytics, Leads	Manager commercial avec acces aux rapports
Salesperson	Voir inventaire, Creer/Modifier des leads	Personnel commercial de terrain
Viewer	Acces en lecture seule	Acces en lecture seule a l’inventaire et aux rapports

Systeme d’autorisations

Autorisations courantes :

view_inventory - Voir les vehicules et les annonces
edit_inventory - Modifier les informations vehicule
delete_inventory - Supprimer des vehicules
create_leads - Creer de nouveaux leads
manage_leads - Modifier et supprimer tous les leads
view_analytics - Acceder au tableau de bord et rapports
manage_kpis - Configurer le tableau de bord KPI
invite_members - Inviter de nouveaux membres
remove_members - Retirer des membres
manage_roles - Creer et modifier des roles
manage_team - Modifier les parametres d’equipe

Cas d’usage

Exemple 1 : Creer une equipe de concession

# 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"
  }'

Exemple 2 : Inviter une equipe commerciale

# 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"
  }'

Exemple 3 : Surveiller l’activite d’equipe

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

Codes d’erreur

Code	Statut	Description
`TEAM_NOT_FOUND`	404	L’ID d’equipe n’existe pas
`SLUG_ALREADY_EXISTS`	400	Le slug d’equipe est deja utilise
`NOT_TEAM_OWNER`	403	Seul le proprietaire peut effectuer cette action
`INSUFFICIENT_PERMISSIONS`	403	L’utilisateur n’a pas les autorisations requises
`ALREADY_TEAM_MEMBER`	400	L’utilisateur est deja membre
`INVITATION_EXPIRED`	400	Le token d’invitation a expire
`INVITATION_NOT_FOUND`	404	L’invitation n’existe pas
`CANNOT_REMOVE_OWNER`	400	Impossible de retirer le proprietaire
`TEAM_HAS_MEMBERS`	400	Impossible de supprimer une equipe avec des membres actifs

Bonnes pratiques

Utiliser des noms et slugs d'equipe descriptifs

Choisissez des noms clairs et professionnels. Les slugs doivent etre lisibles et memorables.

Mettre en place un acces base sur les roles

Assignez les roles en fonction des fonctions. Ne donnez pas l’acces admin a tout le monde.

Reviser regulierement la composition des equipes

Auditez les membres chaque trimestre. Supprimez les utilisateurs inactifs et mettez a jour les roles.

Mettre en place des rappels d'expiration d'invitation

Relancez les invitations en attente avant leur expiration (7 jours).

Documenter les roles personnalises

Si vous creez des roles personnalises, documentez clairement leurs autorisations.

Utiliser les slugs d'equipe pour le routage

Utilisez les slugs pour des URLs plus propres et plus partageables.

Modeles d’integration

Architecture multi-locataires

// 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();
}

Verification des autorisations

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

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

Ressources associees

API d'authentification

Authentification des utilisateurs et gestion des sessions

Roles et autorisations

Guide detaille du systeme d’autorisations

Configuration multi-locataire

Bonnes pratiques pour les concessions multi-sites

Guide de securite

Bonnes pratiques de securite pour les equipes

Documentation API

​Vue d’ensemble

​Fonctionnalites cles

Gestion d'equipe

Invitations de membres

Acces base sur les roles

Journal d'audit

​Endpoints

​Lister toutes les equipes

​Obtenir mes equipes

​Obtenir une equipe par ID

​Obtenir une equipe par slug

​Creer une equipe

​Mettre a jour une equipe

​Supprimer une equipe

​Inviter un membre de l’equipe

​Accepter une invitation d’equipe

​Obtenir les membres de l’equipe

​Obtenir les invitations en attente

​Retirer un membre de l’equipe

​Annuler une invitation

​Obtenir les equipes d’un utilisateur

​Roles et autorisations d’equipe

​Roles par defaut

​Systeme d’autorisations

​Cas d’usage

​Exemple 1 : Creer une equipe de concession

​Exemple 2 : Inviter une equipe commerciale

​Exemple 3 : Surveiller l’activite d’equipe

​Codes d’erreur

​Bonnes pratiques

​Modeles d’integration

​Architecture multi-locataires

​Verification des autorisations

​Ressources associees

API d'authentification

Roles et autorisations

Configuration multi-locataire

Guide de securite

Vue d’ensemble

Fonctionnalites cles

Endpoints

Lister toutes les equipes

Obtenir mes equipes

Obtenir une equipe par ID

Obtenir une equipe par slug

Creer une equipe

Mettre a jour une equipe

Supprimer une equipe

Inviter un membre de l’equipe

Accepter une invitation d’equipe

Obtenir les membres de l’equipe

Obtenir les invitations en attente

Retirer un membre de l’equipe

Annuler une invitation

Obtenir les equipes d’un utilisateur

Roles et autorisations d’equipe

Roles par defaut

Systeme d’autorisations

Cas d’usage

Exemple 1 : Creer une equipe de concession

Exemple 2 : Inviter une equipe commerciale

Exemple 3 : Surveiller l’activite d’equipe

Codes d’erreur

Bonnes pratiques

Modeles d’integration

Architecture multi-locataires

Verification des autorisations

Ressources associees