Skip to navigation
Métodos API02 - Create Appointments

Create Appointment Representation_External

View as Markdown

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.

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...

Referencia de la API

Variables Globales de Entrada

ParámetroDescripciónRequeridoTipo
$notifyCreationtrue: Envía una notificación automática de confirmación al ciudadano.
false: Registra la cita silenciosamente.
Por defecto: true		NOBoolean
$checkAgendatrue: Valida la disponibilidad horaria del agente antes de insertar.
false: Omite la comprobación y fuerza la inserción.		SIBoolean
$councilOptions.notificationTypeSelecciona 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.		NOInteger
$councilConfiguración técnica, fechas y taxonomía de la cita (Ver desglose abajo).SIObject
$participantDatos de identidad y contacto del participante (Ver desglose abajo).SIObject
$representationDatos del Representado. (Solo se rellena en flujos de representación legal).NOObject
$guestsLista de participantes invitados adicionales ([ParticipantInput]).NOArray

Desglose del Objeto council (CouncilInput)

ParámetroDescripciónRequeridoTipo
nameTítulo o nombre asignado al trámite de la cita.SIString
companyIdID numérico interno de la entidad en la plataforma OVAC.SIInteger
statuteIdID numérico interno del trámite en la plataforma.SIInteger
councilTypeCanal de atención:
5 (Videoatención)
6 (Gestión desatendida)
7 (Presencial).		SIInteger
dateStartFecha y hora programada en formato UTC bajo el estándar ISO 8601 (YYYY-MM-DDTHH:mmZ).SIString
tagIdentificador de origen: “ADMIN” (gestores)
“KIOSK” (tótems)
“INMEDIATE” (urgente)
“URGENT” (huecos reservados)
“QUICK_APPOINTMENT” (creación rápida de cita).		SIString
readOnlyRestricción de edición: 0 (permite modificaciones desde el portal)
1 (bloqueada, solo vía API).		SIInteger
languageIdioma 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’.		NOString
contactEmailCorreo electrónico de soporte o contacto de la entidad. Por defecto se usa el parametrizado en la entidad/organización.NOString
externalIdIdentificador propio o ID único de la cita en el sistema del cliente.NOString
conveneTextTexto o cuerpo opcional para la convocatoria de la reunión.NOString
observationsComentarios u observaciones generales de la cita.NOString
internalNotesNotas internas dirigidas al agente (no son visibles por el ciudadano).NOString
commentComentarios adicionales sobre el registro.NOString
userScheduleIdControl 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.		NOString

Desglose del Objeto participant (ParticipantInput - Representante)

ParámetroDescripciónRequeridoTipo
nameNombre de pila del participante.SIString
surnameApellidos completos del participante.SIInteger
idCardTypeTipo 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)SIString
dniNúmero del documento de identidad o identificación fiscal.SIString
idCardCountryCódigo de país del documento en formato ISO 3166-1 alfa-2 (ej. “ES”).SIString
emailDirección de correo electrónico donde el ciudadano recibirá las notificaciones.SIString
phoneTeléfono móvil de contacto con prefijo internacional (ej. “+34600000000”).SIString
languageIdioma 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’.		NOString
zipcodeCódigo postal de residencia del participante.NOString

Desglose del Objeto representation (ParticipantInput - Representado)

ParámetroDescripciónRequeridoTipo
nameNombre de pila del participante.SIString
surnameApellidos completos del participante.SIInteger
idCardTypeTipo 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)SIString
dniNúmero del documento de identidad o identificación fiscal.SIString
idCardCountryCódigo de país del documento en formato ISO 3166-1 alfa-2 (ej. “ES”).SIString
personOrEntity0 - persona física
1 - persona jurídica		SIInteger
emailDirección de correo electrónico donde el ciudadano recibirá las notificaciones.SIString
phoneTeléfono móvil de contacto con prefijo internacional (ej. “+34600000000”).SIString
languageIdioma 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’.		NOString
zipcodeCódigo postal de residencia del participante.NOString

Campos de respuesta (Payload)

ParámetroDescripciónTipo
createOneOnOneCouncilObjeto raíz con los datos de la cita generada.Object
createOneOnOneCouncil.idIdentificador, interno de OVAC, único de la cita generada.Integer
createOneOnOneCouncil.accessLinkEnlace único de acceso directo para auditar la cita.String
createOneOnOneCouncil.creatorIdIdentificador, 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,
    $councilOptions: CouncilOptions
    )
    {
        createAppointment
            (
            council: $council,
            participant: $participant,
            representation: $representation,
            notifyCreation: $notifyCreation,
            checkAgenda: $checkAgenda,
            councilOptions: $councilOptions
            )
        {
            id
            accessLink
            creatorId
        }
    }

2. Variables de la Petición (JSON Payload)

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

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":"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)

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