Create Appointment Representation_External

# Create Appointment with Representation (External ID Variant) (`createOneOnOneCouncil`) Esta variante de la mutación se utiliza cuando el ciudadano que asiste al encuentro actúa en calidad de **representante legal (apoderado o tutor)** en nombre de una tercera persona física o jurídica (el Representado), y además se desea vincular la cita utilizando los identificadores lógicos del sistema del cliente (`companyExternalId` y `statuteExternalId`) en lugar de los IDs internos 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 ### 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 | | companyId | ID numérico interno de la entidad en la plataforma OVAC. | SI | Integer | | statuteId | ID numérico interno del trámite en la plataforma. | 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` - Representante) | 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 del Objeto `representation` (`ParticipantInput` - Representado) | 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 | | personOrEntity | `0` - persona física <br>`1` - persona jurídica | 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, $councilOptions: CouncilOptions ) { createOneOnOneCouncil ( council: $council, participant: $participant, representation: $representation, notifyCreation: $notifyCreation, checkAgenda: $checkAgenda, councilOptions: $councilOptions ) { id accessLink creatorId } } ``` ### 2\. Variables de la Petición (JSON Payload) ``` json { "council": { "name": "test creación cita", "companyExternalId": "", "statuteExternalId": "", "councilType": 5, "externalId" : "", "contactEmail": "", "dateStart": "2026-05-23T15:30Z", "conveneText": "", "observations": "Estas son observaciones", "internalNotes": "Estas son notas internas", "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": "alejandro.maneiro@councilbox.com", "phone": "+34600000000", "language":"gal", "zipcode": "00000" }, "representation": { "name": "REPRESENTADO", "surname": "Surname of participant", "idCardType": "dni", "dni" : "22222222H", "idCardCountry": "ES", "personOrEntity": 1, "email": "participant_email+representado@domain.com", "phone": "+34600000000", "language":"es", "zipcode": "00000" }, "notifyCreation": true, "checkAgenda": true, "councilOptions": { "notificationType": 0 } } ``` ### 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":"test creación cita","companyExternalId":"API_TEST","statuteExternalId":"TRAMITE_TEST","councilType":5,"externalId":"REF-CLIENTE-10294","contactEmail":"","dateStart":"2026-05-23T15:30: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":"alejandro.maneiro@councilbox.com","phone":"+34600000000","language":"gal","zipcode":"00000"},"representation":{"name":"REPRESENTADO","surname":"Surname of participant","idCardType":"dni","dni":"22222222H","idCardCountry":"ES","personOrEntity":1,"email":"participant_email+representado@domain.com","phone":"+34600000000","language":"es","zipcode":"00000"},"notifyCreation":true,"checkAgenda":true}}' ``` ### 4\. Respuesta Esperada (200 OK) ``` json { "data": { "createOneOnOneCouncil": { "id": 64918, "accessLink": "https://apitest.ovac.pre.councilbox.com/attendance/token/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb3VuY2lsUGFydGljaXBhbnRJZCI6MjQ5MDE3LCJpZCI6MjQ5MDE3LCJpYXQiOjE3NzkzNjE5MTR9.xhqWkiqrWZhrzPjPCqvyDjTCfFUB8VaDBX3N7yNO7Ig", "creatorId": 3476 } } } ``` > **Nota OpenAPI/Fern:** esta operación GraphQL se documenta como `/graphql/createoneononecouncil-7` para que Fern pueda mostrarla como operación independiente. La ruta técnica real de ejecución es `POST /graphql`.