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 |
| $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-4` para que Fern pueda mostrarla como operación independiente. La ruta técnica real de ejecución es `POST /graphql`.