Crear o actualizar usuario

Este endpoint permite añadir o actualizar la información de un usuario dentro del negocio.

PUT /api/v2/businesses/{businessId}/users/{username}

A continuación, se expone una explicación detallada de cada uno de los campos que pueden conformar el cuerpo de la petición, siendo algunos de ellos obligatorios para que esta se realice de manera exitosa.

Los campos obligatorios están marcados con un asterisco (*).

Cuerpo de la petición

Análisis del JSON 
{
  "username": "string",
  "email": "string",
  "nodes": [
    0
  ],
  "roles": [
    "string"
  ]
}
Detalles

  • username*: nombre de usuario. Debe ser único. Normalmente, se utiliza el correo electrónico.

  • email*: dirección de correo electrónico con el formato correcto. Debe ser única.

  • nodes*: lista de identificadores internos de Orquest en los que el usuario va a tener visibilidad.

  • roles: lista de roles que se aplican al usuario.

Ejemplo de la petición

Una vez realizado el análisis de los distintos campos, se muestra un ejemplo de la petición:

PUT /api/v2/businesses/BUSINESSID/users/test.user@orquest.com
{
    "username": "test.user@orquest.com",
    "email": "test.user@orquest.com",
    "nodes": [
        5391, 5392
    ],
    "roles": ["Manager"]
}

Si la petición se realiza correctamente, la respuesta contendrá la información vinculada al usuario: username, email, nodes y roles, con 200 OK si el usuario ya existía o 201 Created (con cabecera Location) si se ha creado.

Consideraciones

Es posible actualizar la dirección de correo electrónico vinculada a un usuario: solo hay que especificar en el cuerpo de la petición el email actualizado.

Solo se pueden añadir nodos pertenecientes al negocio de la petición. Los nodos de nodes que no pertenezcan a este negocio se descartan en silencio (sin error): si tras filtrarlos no queda ninguno, o si no se envía el campo, al usuario se le asigna automáticamente el nodo raíz del negocio en vez de dejarlo sin nodos.

En roles, el nombre del rol debe coincidir exactamente con el que está configurado en el sistema: Configuración de negocio > Roles.

Si hubiera algún rol definido previamente para el usuario, en la actualización debe enviarse también esta información. Si no se envía el campo, se envía como null o un array vacío [], se eliminan todos los roles.

Un usuario de integraciones podrá asignar cualquier rol definido a nivel de negocio.

Códigos de error

Además de los errores comunes, este endpoint puede devolver los siguientes códigos:

Código Mensaje Descripción

400 Bad Request

-

El username de la URL no coincide con el del cuerpo de la petición.

error.user_validation. [Nodes cannot be null]

Falta el campo nodes.

error.user_validation. [Nodes cannot be empty]

El campo nodes viene vacío.

error.user_validation. [User username cannot be null]

Falta el campo username.

error.user_validation. [User email cannot be empty]

Falta el campo email.

User email is not valid

El formato de email no es válido (validación básica).

error.node_not_found. [id]

Alguno de los identificadores de nodes no existe en Orquest.

error.role_not_found. [rol]

Alguno de los roles no coincide con los definidos a nivel de negocio.

error.email_already_exists. [email]

El email ya pertenece a otro usuario registrado.

User not found. []

El username ya existe, pero registrado en otro negocio distinto del de la petición.

409 Conflict

Some role is not valid

Alguno de los roles del usuario (los de user.roles, no los de las asociaciones de servicio) no es válido.

Este endpoint tiene un manejo de errores propio que no sigue el formato general de la API: el 401 Forbidden del catálogo común, y el 401 Service or node forbidden cuando el nodo existe pero está fuera de la visibilidad de quien hace la petición, se devuelven aquí como 400/404 sin cuerpo según el caso, en vez del 401 con mensaje habitual. Solo 401 Business forbidden (negocio inexistente) conserva el formato estándar.

Enlaces de interés

¿Qué es un usuario?

¿Qué es un nodo? ¿Cómo consultar los nodos del negocio?

¿Cuál es la diferencia entre rol de empleado y rol de usuario?