Appointments
# Appointments (`query`)
Este método permite obtener un listado paginado o filtrado de las citas (consejos) que cumplan con los criterios de búsqueda especificados. Devuelve la información general y de control de cada registro junto con el recuento total de resultados coincidentes, siendo de gran utilidad para la sincronización de agendas y la generación de reportes consolidados por organización, rango de fechas o estados.
### 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 |
| --- | --- | --- | --- |
| companyId | Identificador de la organización | SI | Integer |
| externalId | Identificador externo de la organización. Si se indica el externalId no se debe indicar companyId | NO | 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 |
| councilTypes | Filtro de tipo de cita: <br>`5` -> Videoatención <br>`6` -> Gestión <br>`7` -> Presencial | NO | Integer |
⚠️ **Nota sobre** **`councilTypes`****:** Aunque en algunos ejemplos heredados de variables se incluye el campo `councilTypes`, este no se encuentra declarado en la firma de la consulta base provista por el backend. Cualquier intento de enviarlo sin modificar la declaración de la query será ignorado de forma silenciosa.
### Campos de Respuesta (Payload)
La consulta devuelve un objeto raíz `councils` compuesto por las siguientes propiedades:
| | 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 del trámite o cita modificado tras la creación | 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.list\[\].**statute** | Objeto del trámite | Object |
| data.councils.list\[\].statute.**title** | Nombre del trámite en OVAC | String |
| data.councils.list\[\].statute.**statuteId** | Identificador único del trámite | Integer |
| 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(
$companyId: Int
$companyExternalId: String
$state: [Int]
$externalId: String
$options: OptionsInput
$fromDate: String
$toDate: String
) {
councils(
companyId: $companyId
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
}
statute {
title
statuteId
}
}
total
}
}
```
### 2\. Variables de la Petición (JSON Payload)
``` json
{
"companyId": 2191,
"fromDate": "2026-05-17T00:00Z",
"toDate": "2026-05-19T00:00Z",
"state": [60],
"externalId": ""
}
```
### 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 Councils($companyId: Int, $companyExternalId: String, $state: [Int], $externalId: String, $options: OptionsInput, $fromDate: String, $toDate: String) { councils (companyId: $companyId, 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":{"companyId":2191,"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"
}
],
"statute": {
"id": 64888,
"title": "TEST",
"statuteId": 4685
}
}
],
"total": 1
}
}
}
```
> **Nota OpenAPI/Fern:** esta operación GraphQL se documenta como `/graphql/councils` para que Fern pueda mostrarla como operación independiente. La ruta técnica real de ejecución es `POST /graphql`.
Authentication
x-jwt-tokenstring
JWT token obtained from Login.
Request
This endpoint expects an object.
query
GraphQL operation
variables
GraphQL variables
Response
Successful response. GraphQL business errors may be returned inside the JSON errors field while transport status remains HTTP 200.