Create Appointment Representation Guests_External | Councilbox OVAC API

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.

Detalles de la Solicitud

Método HTTP: POST
URL PRE: https://api.ovac.pre.councilbox.com/graphql
URL PRO: https://api.ovac.councilbox.com/graphql

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. `false`: Registra la cita silenciosamente. Por defecto: `true`	NO	Boolean
$checkAgenda	`true`: Valida la disponibilidad horaria del agente antes de insertar. `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: `-1`: Sin notificación `0`: email `1`: SMS `2`: WhatsApp 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: `5` (Videoatención) `6` (Gestión desatendida) `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) “`KIOSK`” (tótems) “`INMEDIATE`” (urgente) “`URGENT`” (huecos reservados) “`QUICK_APPOINTMENT`” (creación rápida de cita).	SI	String
readOnly	Restricción de edición: `0` (permite modificaciones desde el portal) `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. 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
userScheduleId	Control de asignación del agente: Agenda de alta concurrencia: `-1` o `null` → Asignación automática por el sistema. Agenda normal: `-1` o `null` → Cita sin agente asignado. Ambas agendas: `IdUsuario`→ Fuerza la asignación al agente indicado mediante su ID interno en OVAC. Si no tiene disponibilidad, devuelve error. Valor por defecto: `null`.	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. 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 `1` → Invitado `2` → Representante `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. 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 `1` → Invitado `2` → Representante `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. 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

mutation createAppointment(
    $council: CouncilInput,
    $participant: ParticipantInput,
    $representation: ParticipantInput,
    $notifyCreation: Boolean,
    $checkAgenda: Boolean,
    $guests: [ParticipantInput],
    $councilOptions: CouncilOptions
    )
    {
        createAppointment
            (
            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)

{
    "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

curl --location 'https://api.ovac.pre.councilbox.com/graphql' \
--header 'Content-Type: application/json' \
--header 'x-jwt-token: {{token}}' \
--data-raw '{"query":"mutation createAppointment($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)

{
    "data": {
        "createAppointment": {
            "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/createappointment-4 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.

querystringRequired

GraphQL operation

variablesobjectOptional

GraphQL variables

Response

Successful response. GraphQL business errors may be returned inside the JSON errors field while transport status remains HTTP 200.