Ir al contenido

Equipo

Las personas con acceso a tu portal de Bookline y sus permisos, y cómo cambiar o quitar ese acceso.

Los endpoints de equipo devuelven las personas con acceso al portal de tu cuenta y sus permisos, y te permiten cambiar o quitar ese acceso. Para leer hace falta users:read; para cambiar, users:write.

Endpoint Ruta Permiso
Listar el equipo GET /v1/users users:read
Un miembro del equipo GET /v1/users/{user_id} users:read
Sustituir el acceso de un miembro PATCH /v1/users/{user_id} users:write
Quitar a un miembro del equipo DELETE /v1/users/{user_id} users:write

El equipo es de todo el cliente: una clave limitada a algunos locales recibe 403 insufficient_scope. En los ejemplos, $BASE es https://api.bookline.ai/v1 y $BOOKLINE_API_KEY tu clave, como en los primeros pasos.

GET /v1/users devuelve tu equipo, paginado. Admite limit (de 1 a 100, 50 por defecto), cursor y customer_id.

Ventana de terminal
curl -s -H "apikey: $BOOKLINE_API_KEY" "$BASE/users"
{
"data": [
{
"id": "…",
"name": "Ana García",
"email": "ana@example.com",
"access": [
{ "level": "ADMIN", "resource": "ALL", "venue_ids": [] }
]
}
],
"meta": { "limit": 50, "next_cursor": null }
}
Campo Qué es
id El identificador del miembro del equipo
name Su nombre
email La dirección con la que inicia sesión
access[] Su acceso a este cliente únicamente, una entrada por permiso
access[].level Qué puede hacer: ADMIN, VIEW, CREATE, UPDATE o DELETE
access[].resource Qué cubre: ALL (todo el cliente), algunos VENUES, o solo BOTS, ACCOUNTS o ACTIVITY (métricas, llamadas y chats)
access[].venue_ids Los locales que cubre cuando resource es VENUES; vacío en los demás casos

El equipo de Bookline no aparece. Un partner tuyo (una agencia o un integrador) con acceso a tu cuenta, sí.

GET /v1/users/{user_id} devuelve los mismos campos, con una cabecera ETag: la versión que tienes que enviar como If-Match al cambiar su acceso. Alguien sin acceso a tu cuenta es 404 not_found.

PATCH /v1/users/{user_id} sustituye los permisos ALL, VENUES y ACTIVITY de la persona en tu cuenta por la lista que envías. Envía su ETag como If-Match (consulta Escribir datos).

Campo Reglas
access De 1 a 20 permisos
access[].level ADMIN, VIEW, CREATE, UPDATE o DELETE
access[].resource ALL, VENUES o ACTIVITY
access[].venue_ids Locales activos de tu cuenta: obligatorio cuando resource es VENUES (hasta 200), no permitido en los demás casos
Ventana de terminal
curl -s -X PATCH "$BASE/users/<user_id>" \
-H "apikey: $BOOKLINE_API_KEY" \
-H "Content-Type: application/json" \
-H 'If-Match: "<etag>"' \
-d '{"access": [{"level": "VIEW", "resource": "VENUES", "venue_ids": ["<venue_id>"]}]}'
  • Los permisos BOTS y ACCOUNTS solo se configuran en el portal: no los envíes y se mantienen.
  • Su acceso a otras cuentas de Bookline nunca se lee ni se cambia.
  • Solo miembros que ya existen: a alguien nuevo se le invita desde el portal (un id desconocido da 404 not_found).
  • La respuesta es el miembro del equipo tal como queda guardado, con su nuevo ETag. Son datos personales: cuenta en el límite de 30 por minuto y queda registrada como una lectura.

DELETE /v1/users/{user_id} quita los permisos ALL, VENUES y ACTIVITY de la persona en tu cuenta. Envía su ETag como If-Match. La respuesta es 204.

Los permisos BOTS y ACCOUNTS, que solo se configuran en el portal, se mantienen; quien se queda sin ninguno deja de ser miembro del equipo. El usuario de la persona y su acceso a otras cuentas se mantienen.

Las dos escrituras siguen estas reglas, además del permiso users:write:

Regla Si no se cumple
La clave tiene que ser una clave de cuenta, o la de uno de tus propios usuarios con ADMIN sobre ALL de la cuenta 403 insufficient_scope
Una clave nunca cambia el acceso de su propio propietario 403 insufficient_scope
El acceso de un partner (una agencia o un integrador) lo configura Bookline 403 insufficient_scope
La cuenta conserva al menos uno de sus propios usuarios con ADMIN sobre ALL 409 conflict
Cada entrada de venue_ids es un local activo de la cuenta 422 validation_failed

El message de cada rechazo lo explica; consulta por qué se puede rechazar una escritura.

  • La versión cubre a toda la persona. Un cambio de su acceso en otra cuenta de Bookline, o de su perfil, también cambia su ETag: una escritura da entonces 412. Vuelve a leerla y reenvía.
  • Sus claves de API siguen su nuevo acceso. Las claves de un miembro del equipo no se revocan: actúan con el acceso actual de la persona, así que un acceso más limitado se aplica a sus claves en un minuto, aproximadamente.