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.
Listar el equipo
Sección titulada «Listar el equipo»GET /v1/users devuelve tu equipo, paginado. Admite limit (de 1 a 100, 50 por defecto), cursor y customer_id.
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í.
Un miembro del equipo
Sección titulada «Un miembro del equipo»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.
Cambiar el acceso de un miembro del equipo
Sección titulada «Cambiar el acceso de un miembro del equipo»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 |
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
BOTSyACCOUNTSsolo 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.
Quitar a un miembro del equipo
Sección titulada «Quitar a un miembro del equipo»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.
Quién puede cambiar el acceso
Sección titulada «Quién puede cambiar el acceso»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.
Reglas de los datos
Sección titulada «Reglas de los datos»- 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.
Relacionado
Sección titulada «Relacionado»- Claves y permisos: qué lee y qué puede cambiar cada clave.
- Equipo: gestionar tu equipo en el portal.
