Appointments_External
Appointments_External
# Appointments (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`.
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.