Councils_External
Councils_External
# Councils (External ID Variant) (`query`)
Este método permite obtener un listado filtrado o paginado de las citas (consejos) correspondientes a una organización a través de su identificador externo (`companyExternalId`). Devuelve la información general y de control de cada registro junto con el recuento total de resultados coincidentes, facilitando la búsqueda por estados, identificadores externos de citas y rangos de fechas sin depender de los IDs internos de la base de datos de la plataforma.
### 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 |
| --- | --- | --- | --- |
| companyExternalId | Identificador externo de la organización | SI | String |
| state | lista de estados por los que filtrar las citas: <br>'`-1`' -> Cancelado <br>`10` -> Confirmado <br>`20` -> Sala abierta <br>`25` -> Pausa <br>`40` -> Finalizada la sesión de vídeoatención/Gestión <br>`45` -> Procesando informe <br>`60` -> Completada <br>`65` -> Incompleta | SI | Integer |
| fromDate | fecha inicial del rango de búsqueda, formato UTC. | SI | String |
| toDate | fecha final del rango de búsqueda, formato UTC. | SI | String |
| externalId | Identificador externo de la cita | NO | String |
| councilTypes | Filtro de tipo de cita: <br>`5` -> Videoatención <br>`6` -> Gestión <br>`7` -> Presencial | NO | Integer |
> Nota: en el ejemplo de variables de la petición aparece `councilTypes`, pero actualmente **no forma parte de la query enviada** por este request, por lo que no interviene en la ejecución mientras no se añada explícitamente a la consulta.
### Campos de Respuesta (Payload)
La consulta devuelve un objeto raíz `councils` compuesto por las siguientes propiedades:
| Parámetro | Descripción | Tipo |
| --- | --- | --- |
| data | Objeto del conjunto de datos | Object |
| data.councils | Objeto de la cita | Object |
| data.councils.list | Array de las citas obtenidas aplicando el filtro | Object |
| data.councils.list\[\].id | Identificador de la cita | Integer |
| data.councils.list\[\].name | Nombre de la cita | String |
| data.councils.list\[\].observations | Observaciones que se han añadido para la cita | String |
| data.councils.list\[\].state | Estado de la cita | Integer |
| data.councils.list\[\].councilType | Tipo de cita (videoatención \[5\], gestión\[6\] o presencial\[7\]) | Integer |
| data.councils.list\[\].creationDate | Fecha de creación de cita, en formato UTC | String |
| data.councils.list\[\].dateStart | Fecha determinada en la cual se va a realizar el trámite, en formato UTC | String |
| data.councils.list\[\].dateRealEnd | Fecha en la que se ha finalizado oficialmente la cita, en formato UTC | String |
| data.councils.list\[\].dateRealStart | echa en la que se iniciado oficialmente la cita, en formato UTC | String |
| data.councils.list\[\].participants | Array de los participantes | Array |
| data.councils.list\[\].participants\[\].name | Nombre del participante | String |
| data.councils.list\[\].participants\[\].surname | Apellido del participante | String |
| data.councils.total | Recuento del número de citas obtenidas con el filtro aplcado | Integer |
## Ejemplos de Código y Peticiones
### 1\. Consulta GraphQL
``` graphql
query Councils(
$companyExternalId: String
$state: [Int]
$externalId: String
$options: OptionsInput
$fromDate: String
$toDate: String
) {
councils(
companyExternalId: $companyExternalId
state: $state
externalId: $externalId
options: $options
fromDate: $fromDate
toDate: $toDate
) {
list {
id
name
observations
state
councilType
creationDate
dateStart
dateRealEnd
dateRealStart
participants {
name
surname
}
}
total
}
}
```
### 2\. Variables de la Petición (JSON Payload)
``` json
{
"companyExternalId": "API_TEST",
"fromDate": "2026-05-17T00:00:00Z",
"toDate": "2026-05-19T00:00:00Z",
"state": [60],
"externalId": ""
}
```
### 3\. Ejemplo de comando cURL
``` bash
curl --location --globoff 'https://api.ovac.pre.councilbox.com/graphql' \
--header 'Content-Type: application/json' \
--header 'x-jwt-token: {{token}}' \
--data '{"query":"query Councils($companyExternalId: String, $state: [Int], $externalId: String, $options: OptionsInput, $fromDate: String, $toDate: String) { councils (companyExternalId: $companyExternalId, state: $state, externalId: $externalId, options: $options, fromDate: $fromDate, toDate: $toDate ){ list { id name observations state councilType creationDate dateStart dateRealEnd dateRealStart participants { name surname } } total } }","variables":{"companyExternalId":"API_TEST","fromDate":"2026-05-17T00:00Z","toDate":"2026-05-19T00:00Z","state":[60],"externalId":""}}'
```
### 4\. Respuesta Esperada (200 OK)
``` json
{
"data": {
"councils": {
"list": [
{
"id": 64767,
"name": "test creación cita",
"observations": "opcional",
"state": 60,
"councilType": 5,
"creationDate": "2026-04-23T15:16:10.085Z",
"dateStart": "2026-05-18T15:00:00.000Z",
"dateRealEnd": "2026-05-18T09:48:53.988Z",
"dateRealStart": "2026-05-18T09:48:37.215Z",
"participants": [
{
"name": "Name of participant",
"surname": "Surname of participant"
},
{
"name": "Name of participant",
"surname": "Surname of participant"
}
]
}
],
"total": 1
}
}
}
```
> **Nota OpenAPI/Fern:** esta operación GraphQL se documenta como `/graphql/councils-2` para que Fern pueda mostrarla como operación independiente. La ruta técnica real de ejecución es `POST /graphql`.