Organizar equipos y roles

Un equipo recibe el trabajo; un rol personalizado decide qué puede hacer quien lo recibe. Son dos recursos de configuración distintos y casi siempre se editan juntos.

Equipos

Una conversación de un canal aterriza en el equipo que ese canal tiene por defecto, salvo que una regla de asignación diga otra cosa. Un ticket lleva su propio team_id. El equipo también guarda su horario de cobertura.

Leer pide teams:read; escribir, teams:write.

curl -X POST https://api.vitrinadev.com/api/v1/teams \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Soporte técnico",
    "hours_mode": "override",
    "hours": { "mon": { "on": true, "start": "09:00", "end": "19:00" } }
  }'

{
  "data": {
    "id": "cccccccc-0000-4000-8000-000000000001",
    "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
    "name": "Soporte técnico",
    "brand": null,
    "hours_mode": "override",
    "hours": { "mon": { "on": true, "start": "09:00", "end": "19:00" } },
    "created_at": "2026-09-22T13:00:00.000Z",
    "updated_at": "2026-09-22T13:00:00.000Z"
  }
}

hours_mode decide de dónde sale ese horario. Con "workspace", el valor por defecto, el equipo sigue el del workspace; con "override", sigue el suyo, y hours lo describe como mapa parcial de días. Ese horario propio alimenta el reloj de SLA, el chequeo is_business_hours de las automatizaciones y el tono «oficina cerrada» del agente de IA. El huso horario y los feriados siempre vienen del workspace y nunca se sobrescriben.

Miembros del equipo

curl -X POST https://api.vitrinadev.com/api/v1/teams/cccccccc-0000-4000-8000-000000000001/members \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "11111111-0000-4000-8000-000000000001", "role": "member" }'

user_id tiene que ser ya un miembro activo del workspace. Un id desconocido, de otro workspace o desactivado se rechaza con un 400. El role de aquí (lead o member) es una etiqueta del equipo y no un permiso; lo que la persona puede hacer lo deciden su rol de workspace o su rol personalizado.

Roles personalizados

Un rol personalizado fija el acceso efectivo de una membresía. La membresía apuntada a uno recibe exactamente sus scopes, sin ningún piso heredado del rol base, más sus dos techos de visibilidad, que se resuelven en cada solicitud.

Leer pide roles:read; escribir, roles:write.

curl -X POST https://api.vitrinadev.com/api/v1/roles \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Agente de soporte",
    "scopes": ["conversations:read", "conversations:write", "tickets:read", "tickets:write"],
    "record_visibility": "assigned",
    "stock_visibility": "all"
  }'

{
  "data": {
    "id": "d2d2d2d2-0000-4000-8000-000000000001",
    "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
    "name": "Agente de soporte",
    "scopes": ["conversations:read", "conversations:write", "tickets:read", "tickets:write"],
    "record_visibility": "assigned",
    "stock_visibility": "all",
    "created_at": "2026-09-22T13:00:00.000Z",
    "updated_at": "2026-09-22T13:00:00.000Z"
  }
}

Los dos techos son independientes:

Los roles base (owner, admin, supervisor, agent) no son roles personalizados y siempre resuelven a all en los dos ejes.

Borrar un rol con miembros activos es un 409. Vacíalo primero, o pasa ?reassign_to=<id de rol> para mover a todos a otro rol en un solo paso, validado en los tres ejes igual que un PUT.

Los contratos completos están en la referencia de Equipos de trabajo y de Roles personalizados.