Administrar el equipo
Invitar, cambiar de rol o sucursal y dar de baja a la gente del workspace.
GET /memberships lista a la gente del workspace. Cada miembro lleva un role base (owner, admin, supervisor, agent, consultant), y un custom_role_id puede reemplazarlo por completo. Cuando ese campo trae un valor, los scopes efectivos del miembro son exactamente los del rol personalizado.
location_ids dice a qué sucursales está posteado el miembro. Solo pesa cuando su rol lleva stock_visibility: own_locations.
Leer pide memberships:read; escribir, memberships:write.
Trampa
No puedes otorgar un rol más alto que el tuyo
Cambiar el rol o la sucursal de un miembro pasa por un techo de escalación. Nunca otorgas un rango más alto que el tuyo, ni cedes sucursales que no ves. Con una API key pasa lo mismo: una app conectada no termina con más autoridad que el miembro que la conectó.
Ver el equipo
curl https://api.vitrinadev.com/api/v1/memberships \
-H "Authorization: Bearer $VITRINA_KEY"{
"data": [
{
"id": "11111111-0000-4000-8000-000000000001",
"tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
"user_id": "11111111-0000-4000-8000-000000000001",
"role": "agent",
"custom_role_id": "d2d2d2d2-0000-4000-8000-000000000001",
"custom_role_name": "Vendedor sucursal",
"status": "active",
"display_name": "Camila Rojas",
"phone": "+56912345001",
"avatar_url": null,
"location_ids": ["b1b1b1b1-0000-4000-8000-000000000001"],
"created_at": "2026-01-10T13:00:00.000Z",
"updated_at": "2026-09-10T13:00:00.000Z"
}
],
"meta": { "total": 1 }
}Invitar por correo
Casi siempre invitas por correo, en vez de dar de alta un user_id que ya conoces:
curl -X POST https://api.vitrinadev.com/api/v1/memberships/invitations \
-H "Authorization: Bearer $VITRINA_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"role": "agent",
"custom_role_id": "d2d2d2d2-0000-4000-8000-000000000001",
"location_ids": ["b1b1b1b1-0000-4000-8000-000000000001"]
}'La respuesta trae accept_url, el link de alta. Sirve cuando el workspace todavía no tiene un proveedor de correo configurado:
{
"data": {
"id": "e5e5e5e5-0000-4000-8000-000000000001",
"email": "[email protected]",
"role": "agent",
"custom_role_id": "d2d2d2d2-0000-4000-8000-000000000001",
"custom_role_name": "Vendedor sucursal",
"location_ids": ["b1b1b1b1-0000-4000-8000-000000000001"],
"accept_url": "https://app.vitrinadev.com/invite/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
"expires_at": "2026-09-17T13:00:00.000Z"
}
}role y custom_role_id son independientes, igual que al dar de alta directo. role fija el rango de escalación; el rol personalizado decide el acceso efectivo. location_ids viaja con la invitación y se copia a la membresía apenas la persona acepta. Una cuenta acotada a una sucursal lo está desde su primer login.
Una API key no puede aceptar una invitación
POST /memberships/invitations/by-token/{token}/accept no pide scope. Su
frontera es el token más una coincidencia exacta de correo. Solo la llama una
persona: una sesión de usuario, o un token personal actuando como esa persona
(ver Tokens personales). Una API key recibe 403.
Aceptar dos veces con el mismo token devuelve la misma membresía
y no reaplica la invitación.
Cambiar rol, estado o sucursal
El PUT es parcial: manda solo lo que cambia.
curl -X PUT https://api.vitrinadev.com/api/v1/memberships/11111111-0000-4000-8000-000000000002 \
-H "Authorization: Bearer $VITRINA_KEY" \
-H "Content-Type: application/json" \
-d '{ "custom_role_id": "d2d2d2d2-0000-4000-8000-000000000001", "location_ids": ["b1b1b1b1-0000-4000-8000-000000000001"] }'display_name, phone y avatar_url viajan en el mismo PUT y escriben el perfil del miembro objetivo. Esos tres campos no llevan la restricción de auto-acción que sí pesa sobre el rol y el estado. Editar tu propia identidad siempre está permitido. Para subir una foto como archivo en vez de pasar una URL, usa POST /memberships/{id}/avatar (multipart, hasta 5MB).
Dar de baja sin dejar trabajo huérfano
curl -X DELETE "https://api.vitrinadev.com/api/v1/memberships/11111111-0000-4000-8000-000000000002?handover=round_robin" \
-H "Authorization: Bearer $VITRINA_KEY"{
"data": {
"mode": "round_robin",
"conversationsMoved": 6,
"leadsMoved": 3,
"perAssignee": { "11111111-0000-4000-8000-000000000003": 9 }
}
}handover decide adónde va el trabajo abierto de la persona.
handover | Qué pasa con lo pendiente |
|---|---|
unassign (por defecto) | Las conversaciones quedan «Sin asignar» y nadie recibe aviso. |
user | Todo pasa al heredero que nombras en handover_assignee_id. |
round_robin | Se reparte entre el resto del equipo. |
Antes de dar de baja, GET /memberships/{id}/handover-preview muestra cuánto trabajo abierto tiene la persona y quién podría heredarlo.
El contrato campo por campo, membresías e invitaciones, vive en la referencia de Equipo.