Create Appointment_External
Create Appointment_External
# Create Appointment (External ID Variant) (`createOneOnOneCouncil`)
Esta variante de la mutación de registro permite agendar y dar de alta una nueva cita en la plataforma vinculando la taxonomía del encuentro directamente a través de los identificadores e integraciones del sistema del cliente (`companyExternalId` y `statuteExternalId`), evitando depender de los IDs internos de la plataforma. Admite de manera nativa y opcional flujos avanzados con invitados o representación legal.
### Autenticación
> **Tipo:** API Key**
Header:** `x-jwt-token`
**Ubicación:** Header HTTP_
Ejemplo:_ `x-jwt-token: eyJhbGciOiJIUzI1NiIsInR5cCI6...`
## Referencia de la API
### Variables Globales de Entrada
| Parámetro | Descripción | Requerido | Tipo |
| --- | --- | --- | --- |
| $notifyCreation | `true`: Envía una notificación automática de confirmación al ciudadano. <br>`false`: Registra la cita silenciosamente. <br>Por defecto: `true` | NO | Boolean |
| $checkAgenda | `true`: Valida la disponibilidad horaria del agente antes de insertar. <br>`false`: Omite la comprobación y fuerza la inserción. | SI | Boolean |
| $councilOptions.**notificationType** | Selecciona el método de notificación de la cita/gestión: <br>`-1`: Sin notificación <br>`0`: email <br>`1`: SMS <br>`2`: WhatsApp <br> <br>Si no se selecciona el bloque, se emplea el método por defecto configurado en el trámite. | NO | Integer |
| $council | Configuración técnica, fechas y taxonomía de la cita (Ver desglose abajo). | SI | Object |
| $participant | Datos de identidad y contacto del participante (Ver desglose abajo). | SI | Object |
| $representation | Datos del Representado. (Solo se rellena en flujos de representación legal). | NO | Object |
| $guests | Lista de participantes invitados adicionales (\[ParticipantInput\]). | NO | Array |
### Desglose del Objeto `council` (`CouncilInput`)
| Parámetro | Descripción | Requerido | Tipo |
| --- | --- | --- | --- |
| name | Título o nombre asignado al trámite de la cita. | SI | String |
| companyExternalId | ID externo de la entidad. No es necesario si se envía companyId. | SI | Integer |
| statuteExternalId | ID externo del trámite. No es necesario si se envía statuteId. | SI | Integer |
| councilType | Canal de atención: <br>`5` (Videoatención) <br>`6` (Gestión desatendida) <br>`7` (Presencial). | SI | Integer |
| dateStart | Fecha y hora programada en formato UTC bajo el estándar ISO 8601 (YYYY-MM-DDTHH:mmZ). | SI | String |
| tag | Identificador de origen: "`ADMIN`" (gestores) <br>"`KIOSK`" (tótems) <br>"`INMEDIATE`" (urgente) <br>"`URGENT`" (huecos reservados). | SI | String |
| readOnly | Restricción de edición: `0` (permite modificaciones desde el portal) <br>`1` (bloqueada, solo vía API). | SI | Integer |
| language | Idioma base en el que se configurará la cita(ej. "es"). Por defecto, se emplea el idioma configurado en la organización. <br>Consultar método '`Languages`'. | NO | String |
| contactEmail | Correo electrónico de soporte o contacto de la entidad. Por defecto se usa el parametrizado en la entidad/organización. | NO | String |
| externalId | Identificador propio o ID único de la cita en el sistema del cliente. | NO | String |
| conveneText | Texto o cuerpo opcional para la convocatoria de la reunión. | NO | String |
| observations | Comentarios u observaciones generales de la cita. | NO | String |
| internalNotes | Notas internas dirigidas al agente (no son visibles por el ciudadano). | NO | String |
| comment | Comentarios adicionales sobre el registro. | NO | String |
### Desglose del Objeto `participant` (`ParticipantInput`)
| Parámetro | Descripción | Requerido | Tipo |
| --- | --- | --- | --- |
| name | Nombre de pila del participante. | SI | String |
| surname | Apellidos completos del participante. | SI | Integer |
| idCardType | Tipo de documento de identidad. Valores admitidos: "`dni`", "`nif`", "`passport`", "`nie`", "`codiceFiscale`" (Identificador Italia), "`otherIDCards`" (cualquier documento de identificación), "`driversLicence`" (Licencia de conducir EEUU), "`europeanDocument`" (documento europeo, solo válido para los documentos de los países de europa) | SI | String |
| dni | Número del documento de identidad o identificación fiscal. | SI | String |
| idCardCountry | Código de país del documento en formato ISO 3166-1 alfa-2 (ej. "ES"). | SI | String |
| email | Dirección de correo electrónico donde el ciudadano recibirá las notificaciones. | SI | String |
| phone | Teléfono móvil de contacto con prefijo internacional (ej. "+34600000000"). | SI | String |
| language | Idioma en el que el ciudadano visualizará la interfaz de OVAC (ej. "es"). Por defecto, se obtiene el de la entidad/ogranización. <br>Consultar método '`Languages`'. | NO | String |
| zipcode | Código postal de residencia del participante. | NO | String |
### Campos de Respuesta (Payload)
La respuesta exitosa devuelve el objeto `createOneOnOneCouncil` con las claves únicas de la cita generada:
| Parámetro | Descripción | Tipo |
| --- | --- | --- |
| createOneOnOneCouncil | Objeto raíz con los datos de la cita generada. | Object |
| createOneOnOneCouncil.**id** | Identificador, interno de OVAC, único de la cita generada. | Integer |
| createOneOnOneCouncil.**accessLink** | Enlace único de acceso directo para auditar la cita. | String |
| createOneOnOneCouncil.**creatorId** | Identificador, interno de OVAC, único del usuario que ha creado la cita. | Integer |
## Ejemplos de Código y Peticiones
### 1\. Mutación GraphQL
``` graphql
mutation CreateOneOnOneCouncil(
$council: CouncilInput,
$participant: ParticipantInput,
$representation: ParticipantInput,
$notifyCreation: Boolean,
$checkAgenda: Boolean,
$guests: [ParticipantInput]
) {
createOneOnOneCouncil(
council: $council,
participant: $participant,
representation: $representation,
notifyCreation: $notifyCreation,
checkAgenda: $checkAgenda,
guests: $guests
) {
id
accessLink
creatorId
}
}
```
### 2\. Variables de la Petición (JSON Payload con Mapeos Externos)
``` json
{
"council": {
"name": "test creación cita",
"companyExternalId": "EXT_COMP_2191",
"statuteExternalId": "EXT_STAT_4685",
"councilType": 5,
"externalId": "SISTEMA_EXTERNO_001",
"contactEmail": "soporte@entidad.com",
"dateStart": "2026-05-16T15:00:00Z",
"conveneText": "",
"observations": "Estas son observaciones",
"internalNotes": "Estas son notas internas",
"language": "gal",
"comment": "Opcional - Información visible mail de creación de cita",
"readOnly": 0,
"tag": "ADMIN"
},
"participant": {
"name": "Name of participant",
"surname": "Surname of participant",
"idCardType": "dni",
"dni": "11111111H",
"idCardCountry": "ES",
"email": "participant_email@domain.com",
"phone": "+34600000000",
"language": "gal",
"zipcode": "00000"
},
"notifyCreation": true,
"checkAgenda": true
}
```
### 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":"mutation createOneOnOneCouncil($council: CouncilInput, $participant: ParticipantInput, $representation: ParticipantInput, $notifyCreation: Boolean, $checkAgenda: Boolean, $guests: [ParticipantInput]){ createOneOnOneCouncil(council: $council, participant: $participant, representation: $representation, notifyCreation: $notifyCreation, checkAgenda: $checkAgenda, guests: $guests) { id accessLink creatorId } }","variables":{"council":{"name":"test creación cita","companyExternalId":"EXT_COMP_2191","statuteExternalId":"EXT_STAT_4685","councilType":5,"externalId":"SISTEMA_EXTERNO_001","contactEmail":"","dateStart":"2026-05-16T15:00:00Z","conveneText":"","observations":"Estas son observaciones","internalNotes":"Estas son notas internas","language":"gal","comment":"","readOnly":0,"tag":"ADMIN"},"participant":{"name":"Name of participant","surname":"Surname of participant","idCardType":"dni","dni":"11111111H","idCardCountry":"ES","email":"participant_email@domain.com","phone":"+34600000000","language":"gal","zipcode":"00000"},"notifyCreation":true,"checkAgenda":true}}'
```
### 4\. Respuesta Esperada (200 OK)
``` json
{
"data": {
"createOneOnOneCouncil": {
"id": 64917,
"accessLink": "https://apitest.ovac.pre.councilbox.com/attendance/token/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb3VuY2lsUGFydGljaXBhbnRJZCI6MjQ5MDE2LCJpZCI6MjQ5MDE2LCJpYXQiOjE3NzkzNjE2Njl9.facpLzBhYA-KmDt9j2zMA32gMhyyBzUc47PNlSyFkaA",
"creatorId": 3476
}
}
}
```
> **Nota OpenAPI/Fern:** esta operación GraphQL se documenta como `/graphql/createoneononecouncil-5` 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.