Create Appointment Representation Guests_External
Create Appointment Representation Guests_External
# Create Appointment with Guest Representation (External ID Variant) (`createOneOnOneCouncil` - Advanced)
Esta variante avanzada de la mutación permite registrar una cita estructurando escenarios complejos en una única petición utilizando los identificadores lógicos del sistema del cliente (`companyExternalId` y `statuteExternalId`). Es ideal para flujos automatizados de integración donde el participante principal asiste con acompañantes o invitados adicionales (`guests`), y donde alguno de estos invitados actúa como representante legal de un tercero a través del subbloque anidado `representedParticipant`.
### Autenticación
> **Tipo:** API Key**
Header:** `x-jwt-token`
**Ubicación:** Header HTTP_
Ejemplo:_ `x-jwt-token: eyJhbGciOiJIUzI1NiIsInR5cCI6...`
## Mapeo de Roles (`type`)
En los bloques de asistentes (`guests` y `representedParticipant`), se utiliza el campo numérico `type` para dictaminar el rol funcional de cada usuario dentro del encuentro:
- **`0`** → Participante sencillo
- **`1`** → Invitado
- **`2`** → Representante
- **`3`** → Representado
## 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` - Principal)
| 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 |
### Desglose de Objetos dentro del Array `guests` (`[ParticipantInput]`)
Cada elemento del listado de invitados comparte la estructura base de `ParticipantInput` pero añade capacidades de asignación de rol dinámico y anidación de representados:
| 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 |
| type | `0` → Participante sencillo <br>`1` → Invitado <br>`2` → Representante <br>`3` -> Representado | SI | Integer |
| 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 |
| representedParticipant | Subbloque opcional. Contiene los datos de la persona física o jurídica a la que el invitado representa. | NO | Object |
### Desglose del objeto `guests` (`[representedParticipant]`)
| 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 |
| type | `0` → Participante sencillo <br>`1` → Invitado <br>`2` → Representante <br>`3` -> Representado | SI | Integer |
| 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)
| 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)
``` json
{
"council": {
"name": "Prueba de nombre",
"companyExternalId": "API_TEST",
"statuteExternalId": "TRAMITE_TEST",
"councilType": 5,
"externalId": "0000_test",
"contactEmail": "",
"dateStart": "2026-05-23T09:30:00Z",
"conveneText": "",
"observations": "",
"internalNotes": "",
"comment": "",
"readOnly": 0,
"tag": "ADMIN"
},
"participant": {
"name": "participante",
"surname": "test",
"idCardType": "dni",
"dni": "11111111H",
"idCardCountry": "ES",
"email": "participante@dominio.dom",
"phone": "+34600000000",
"language": "es",
"zipcode": "00000"
},
"guests": [
{
"name": "invitado ",
"surname": "representante",
"idCardType": "passport",
"dni": "00000000",
"idCardCountry": "ES",
"type": 2,
"email": "representante@dominio.dom",
"phone": "+34600000000",
"language": "es",
"zipcode": "00000",
"representedParticipant": {
"name": "invitado ",
"surname": "representado",
"idCardType": "passport",
"dni": "111111",
"idCardCountry": "ES",
"type": 3,
"email": "representado@dominio.dom",
"phone": "+34600000000",
"language": "es",
"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-raw '{"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":"Prueba de nombre","companyExternalId":"API_TEST","statuteExternalId":"TRAMITE_TEST","councilType":5,"externalId":"0000_test","contactEmail":"","dateStart":"2026-05-23T09:30Z","conveneText":"","observations":"","internalNotes":"","comment":"","readOnly":0,"tag":"ADMIN"},"participant":{"name":"participante","surname":"test","idCardType":"dni","dni":"11111111H","idCardCountry":"ES","email":"participante@dominio.dom","phone":"+34600000000","language":"es","zipcode":"00000"},"guests":[{"name":"invitado ","surname":"representante","idCardType":"passport","dni":"00000000","idCardCountry":"ES","type":2,"email":"representante@dominio.dom","phone":"+34600000000","language":"es","zipcode":"00000","representedParticipant":{"name":"invitado ","surname":"representado","idCardType":"passport","dni":"111111","idCardCountry":"ES","type":3,"email":"representado@dominio.dom","phone":"+34600000000","language":"es","zipcode":"00000"}}],"notifyCreation":true,"checkAgenda":true}}'
```
### 4\. Respuesta Esperada (200 OK)
``` json
{
"data": {
"createOneOnOneCouncil": {
"id": 64919,
"accessLink": "https://apitest.ovac.pre.councilbox.com/attendance/token/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb3VuY2lsUGFydGljaXBhbnRJZCI6MjQ5MDE5LCJpZCI6MjQ5MDE5LCJpYXQiOjE3NzkzNjQ0MTZ9.AeUze049RfMUrY3SzgcAF9O7dfCrylpGPf1kpFK2FLU",
"creatorId": 3476
}
}
}
```
> **Nota OpenAPI/Fern:** esta operación GraphQL se documenta como `/graphql/createoneononecouncil-6` para que Fern pueda mostrarla como operación independiente. La ruta técnica real de ejecución es `POST /graphql`.