Organization Users
# Organization Users (`query`)
Esta operación permite consultar la información detallada de los usuarios pertenecientes a una organización raíz (corporación) y, de manera específica, obtener el listado de las entidades, delegaciones o centros de atención a los que están vinculados. Está especialmente diseñada para conocer el alcance de gestión de los operarios o filtrar de forma directa por su correo electrónico.
### Autenticación
> **Tipo:** API Key**
Header:** `x-jwt-token`
**Ubicación:** Header HTTP_
Ejemplo:_ `x-jwt-token: eyJhbGciOiJIUzI1NiIsInR5cCI6...`
## Referencia de la API
### Parámetros de entrada (Variables)
| Parámetro | Descripción | Requerido | Tipo |
| --- | --- | --- | --- |
| organizationId | Identificador único de la organización. | SI | Integer |
| options | Parámetros de configuración para paginación (ej. limit y offset). | NO | OptionsInput |
| filters | Colección de criterios de filtrado para acotar la búsqueda de usuarios. | NO | FilterInput |
| filters.**field** | Campo del usuario por el que realizar la búsqueda (para este caso técnico: "email"). | SI (si se filtra) | String |
| filters.**text** | Dirección de correo electrónico exacta que se desea buscar en el sistema. | SI (si se filtra) | String |
### Campos de respuesta (Payload)
La consulta devuelve un objeto contenedor `organizationUsers` estructurado con la siguiente taxonomía de datos:
| Parámetro | Descripción | Tipo |
| --- | --- | --- |
| organizationUsers | Objeto raíz contenedor de los resultados de la consulta de organización. | Objeto |
| organizationUsers.**list** | Array que contiene los usuarios localizados bajo los criterios de filtrado. | Array |
| organizationUsers.list\[\].**id** | Identificador numérico único del usuario en la plataforma (userId). | Integer |
| organizationUsers.list\[\].**name** | Nombre de pila del usuario. | String |
| organizationUsers.list\[\].**surname** | Apellidos completos del usuario. | String |
| organizationUsers.list\[\].**email** | Dirección de correo electrónico corporativo del usuario. | String |
| organizationUsers.list\[\].**roles** | Rol de permisos asignado al usuario dentro de la organización (ej. "superadmin"). | String |
| organizationUsers.list\[\].**externalId** | Identificador único del usuario en los sistemas de origen del cliente (si aplica, si no null). | String |
| organizationUsers.list\[\].**companies** | Matriz o colección de entidades específicas a las que pertenece o tiene acceso el usuario. | Array |
| organizationUsers.list\[\].**companies\[\].id** | Identificador numérico único de la entidad/empresa en la plataforma. | Integer |
| organizationUsers.list\[\].**companies\[\].externalId** | Código identificativo externo de la entidad (si no dispone de él, devuelve null). | String |
| organizationUsers.list\[\].**companies.businessName** | Razón social o denominación oficial de la entidad vinculada. | String |
| total | Número total de registros de usuarios encontrados que cumplen las condiciones. | Integer |
## Ejemplos de código y peticiones
> 💡 **Nota de Integración:** Se ha ajustado la consulta GraphQL de ejemplo para incluir explícitamente el nodo `companies` y el argumento `filters` en la firma de ejecución. De este modo, la petición reflejará de forma fidedigna los datos de filtrado de entrada y el listado de centros del payload de respuesta.
### 1\. Consulta GraphQL
``` graphql
query OrganizationUsers(
$organizationId: Int!,
$options: OptionsInput,
$filters: [FilterInput]
) {
organizationUsers(
corporationId: $organizationId,
options: $options,
filters: $filters
) {
list {
id
name
surname
email
roles
externalId
companies {
id
externalId
businessName
}
}
total
}
}
```
### 2\. Variables de la petición (JSON Payload)
``` json
{
"organizationId": 2191,
"options": {
"limit": 100,
"offset": 0
},
"filters": [
{
"field": "email",
"text": "alejandro.maneiro+apiprof@councilbox.com"
}
]
}
```
### 3\. Ejemplo de comando cURL
``` bash
curl --location "https://api.ovac.pre.councilbox.com/graphql" \
--header "Content-Type: application/json" \
--header "x-jwt-token: {{token}}" \
--data '{"query":"query OrganizationUsers($organizationId: Int!, $options: OptionsInput, $filters: [FilterInput]) { organizationUsers(corporationId: $organizationId, options: $options, filters: $filters) { list { id name surname email roles externalId companies { id externalId businessName } } total } }","variables":{"organizationId":2191,"options":{"limit":100,"offset":0},"filters":[{"field":"email","text":"alejandro.maneiro+apiprof@councilbox.com"}]}}'
```
### 4\. Respuesta esperada (200 OK)
``` json
{
"data": {
"organizationUsers": {
"list": [
{
"id": 3477,
"name": "API",
"surname": "PROFESIONAL",
"email": "alejandro.maneiro+apiprof@councilbox.com",
"roles": "professionalAdmin",
"externalId": null,
"companies": [
{
"id": 2191,
"externalId": null,
"businessName": "TEST API"
}
]
}
],
"total": 1
}
}
}
```
> **Nota OpenAPI/Fern:** esta operación GraphQL se documenta como `/graphql/organizationusers` para que Fern pueda mostrarla como operación independiente. La ruta técnica real de ejecución es `POST /graphql`.