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 | | $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` - 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], $councilOptions: CouncilOptions ) { createOneOnOneCouncil ( council: $council, participant: $participant, representation: $representation, notifyCreation: $notifyCreation, checkAgenda: $checkAgenda, guests: $guests, councilOptions: $councilOptions ) { 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: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, "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":"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-8` para que Fern pueda mostrarla como operación independiente. La ruta técnica real de ejecución es `POST /graphql`.