> For the complete documentation index, see [llms.txt](https://docs.skyone.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.skyone.cloud/espanol/api-skyone-autosky/api-usuarios.md).

# API Usuarios

Llamadas de API para la operación de los objetos Usuarios (Usuarios de Acceso al Sistema).

**Base path:** `/users/`

***

## Listar Usuarios

Realiza la consulta de los usuarios registrados en la plataforma Autosky y vinculados a los clientes.

```http
GET /users/
```

### Parámetros de Query (opcionales)

| Parámetro  | Tipo   | Descripción                                        |
| ---------- | ------ | -------------------------------------------------- |
| `cli_uuid` | string | UUID del cliente para filtrar usuarios específicos |

### Respuesta

**Status:** `200 OK`

```json
[
    {
        "nome": "João",
        "sobrenome": "Souza",
        "email": "joao.souza@dominio.com",
        "ativo": true,
        "username": "joao.souza",
        "usr_uuid": "3bc705ab-5536-4193-bd5c-2d3e8ffd2e5b",
        "external_ad": false
    }
]
```

***

## Obtener datos de un usuario

Obtiene los datos de un usuario especificado por su UUID. Además de los campos del listado, también incluye el campo `clients`.

```http
GET /users/{usr_uuid}
```

### Parámetros de Path

| Parámetro  | Obligatorio | Descripción      |
| ---------- | ----------- | ---------------- |
| `usr_uuid` | Sí          | UUID del usuario |

### Respuesta

**Status:** `200 OK`

```json
{
    "nome": "João",
    "sobrenome": "Souza",
    "email": "joao.souza@dominio.com",
    "ativo": true,
    "username": "joao.souza",
    "usr_uuid": "3bc705ab-5536-4193-bd5c-2d3e8ffd2e5b",
    "clients": [
        {
            "cli_uuid": "79ea8324-4889-4729-8bf0-bc1c40b38273",
            "nome": "MeuCliente001",
            "grupo_seguranca": "Cliente001",
            "email_admin": "email-adm@dominio.com",
            "has_license_limit": false,
            "license_limit": 0,
            "amb_uuid": "715088c9-9f21-424e-bcd5-5eacc0ce165b"
        }
    ],
    "external_ad": false
}
```

***

## Registrar Usuario

Realiza el registro de un nuevo usuario en la plataforma.

* En caso de que el usuario ya exista, este procedimiento solo lo vinculará al cliente enviado como parámetro.
* Almacene el UUID de retorno para modificaciones futuras.
* Si posee un Active Directory específico para el entorno, utilice `external_ad: true` para configurar la contraseña en el registro.

```http
POST /users/
```

### Cuerpo de la Solicitud

| Campo                   | Tipo    | Obligatorio | Descripción                                                      |
| ----------------------- | ------- | ----------- | ---------------------------------------------------------------- |
| `nome`                  | string  | Sí          | Nombre del usuario                                               |
| `sobrenome`             | string  | No          | Apellido del usuario                                             |
| `email`                 | string  | Sí          | Correo electrónico de inicio de sesión del usuario               |
| `ativo`                 | boolean | No          | Si el usuario está activo                                        |
| `username`              | string  | No          | Nombre del usuario en el AD                                      |
| `password`              | string  | No          | Contraseña del usuario                                           |
| `cli_uuid`              | string  | Sí          | UUID del cliente en el que se registrará el usuario              |
| `description`           | string  | No          | Información complementaria del usuario                           |
| `fullname`              | string  | No          | Nombre completo (debe contener al menos dos palabras separadas)  |
| `external_ad`           | boolean | No          | `true` en caso de que posea un Active Directory propio           |
| `send_activation_email` | boolean | No          | Si se debe enviar un correo electrónico de activación al usuario |

### Ejemplo de Solicitud

```json
{
    "nome": "Joao",
    "sobrenome": "Souza",
    "email": "joao.souza@dominio.com",
    "ativo": true,
    "username": "joao.souza",
    "password": "senha123",
    "cli_uuid": "769a0f4e-16a8-422a-99ab-d8c416137d4c",
    "description": "Informações do Usuário XXXX",
    "fullname": "Joao Souza Martins",
    "external_ad": false,
    "send_activation_email": false
}
```

### Respuesta

**Status:** `200 OK`

```json
{
    "nome": "Joao",
    "sobrenome": "Souza",
    "email": "joao.souza@dominio.com",
    "ativo": true,
    "username": "joao.souza",
    "usr_uuid": "3bc705ab-5536-4193-bd5c-2d3e8ffd2e5b",
    "clients": [],
    "external_ad": true
}
```

***

## Editar Usuario

Realiza la edición de la información del usuario. Solo se podrá modificar cierta información.

```http
PUT /users/{usr_uuid}
```

### Parámetros de Path

| Parámetro  | Obligatorio | Descripción      |
| ---------- | ----------- | ---------------- |
| `usr_uuid` | Sí          | UUID del usuario |

### Cuerpo de la Solicitud

| Campo         | Tipo    | Descripción                |
| ------------- | ------- | -------------------------- |
| `nome`        | string  | Nombre del usuario         |
| `sobrenome`   | string  | Apellido del usuario       |
| `ativo`       | boolean | Si el usuario está activo  |
| `password`    | string  | Contraseña del usuario     |
| `description` | string  | Información complementaria |

### Ejemplo de Solicitud

```json
{
    "nome": "Joao",
    "sobrenome": "Souza",
    "ativo": true,
    "password": "senha123"
}
```

### Respuesta

**Status:** `200 OK`

Devuelve el objeto completo del usuario actualizado, incluyendo el array `clients`.

***

## Activar / Desactivar Usuario

Activa o desactiva un usuario

```http
PATCH /users/{usr_uuid}
```

### Parámetros de Path

| Parámetro  | Obligatorio | Descripción     |
| ---------- | ----------- | --------------- |
| `usr_uuid` | Sí          | UUID do usuário |

### Cuerpo de la Solicitud

| Campo                   | Tipo    | Obligatorio | Descripción                                               |
| ----------------------- | ------- | ----------- | --------------------------------------------------------- |
| `ativo`                 | boolean | Sí          | `true` para activar, `false` para desactivar              |
| `send_activation_email` | boolean | No          | Si se debe enviar un correo electrónico de activación     |
| `cli_uuid`              | string  | No          | UUID del cliente asociado al envío del correo electrónico |

### Ejemplo de Solicitud

```json
{
    "ativo": true,
    "send_activation_email": false,
    "cli_uuid": "769a0f4e-16a8-422a-99ab-d8c416137d4c"
}
```

### Respuesta

**Status:** `200 OK`

```json
{
    "nome": "João",
    "sobrenome": "Souza",
    "email": "joao.souza@dominio.com",
    "ativo": true,
    "username": "joao.souza",
    "cli_uuid": "769a0f4e-16a8-422a-99ab-d8c416137d4c"
}
```

***

## Cambiar contraseña del usuario

Modifica la contraseña de acceso de un usuario.

{% hint style="info" %}
La información de la contraseña no se almacena en la base de datos de la plataforma Autosky. Se almacena directamente en el AD de autenticación definido en la plataforma.
{% endhint %}

```http
PATCH /users/{usr_uuid}
```

### Parámetros de Path

| Parámetro  | Obligatorio | Descripción      |
| ---------- | ----------- | ---------------- |
| `usr_uuid` | Sí          | UUID del usuario |

### Cuerpo de la Solicitud

| Campo      | Tipo   | Obligatorio | Descripción                  |
| ---------- | ------ | ----------- | ---------------------------- |
| `password` | string | Sí          | Nueva contraseña del usuario |

### Ejemplo de Solicitud

```json
{
    "password": "NovaSenhaSegura@2024!"
}
```

### Respuesta

**Status:** `200 OK`

```json
{
    "status": "success"
}
```

***

## Eliminar Usuario

Este endpoint elimina un usuario o lo desvincula de un cliente específico.

{% hint style="warning" %}
El endpoint no siempre elimina al usuario del sistema. Si el usuario está vinculado a más de un cliente, solo se desvinculará del cliente informado (permaneciendo activo y con acceso a los demás clientes). En caso de que sea el último o el único cliente del usuario, será eliminado por completo y perderá el acceso al sistema.
{% endhint %}

### Parámetros de Petición (Body) 

A diferencia de las peticiones de eliminación tradicionales, este endpoint acepta y puede requerir un cuerpo (body) en formato `application/json`.

* `cli_uuid` (string): Identificador del cliente del cual desea desvincular al usuario.
  * Obligatorio si el usuario posee vínculo con más de un cliente.
  * Opcional si el usuario está vinculado a un solo cliente.

Ejemplo de Request Body:

```json
{
  "cli_uuid": "0e92037b-ed77-4a38-ab35-909637bea146"
}
```

### Respostas 

* **`200 OK` - Éxito** 

El usuario fue eliminado del sistema o desvinculado del cliente con éxito.

* **`200 OK` - Cliente no informado (Múltiples Vínculos)** 

Se retorna cuando el usuario posee vínculos con más de un cliente, pero el `cli_uuid` no fue enviado en el cuerpo de la petición. (*Nota: El estado HTTP retornado es 200 y no un error 4xx*). La respuesta traerá la lista de clientes a los cuales pertenece el usuario para que se elija uno.

Ejemplo*:*

```json
{
  "status": "error",
  "status_code": "USR006",
  "message": "Por favor informe un cliente (cli_uuid)",
  "clientes": [
    // Lista de clientes vinculados a este usuário
  ]
}
```

* **`404 Not Found` - No Encontrado**

El usuario informado no existe o no fue encontrado.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.skyone.cloud/espanol/api-skyone-autosky/api-usuarios.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.