Skip to navigation
Métodos API02 - Create Appointments

Create Appointment

View as Markdown

Esta mutación permite registrar una nueva cita en la plataforma, vinculando al ciudadano principal y configurando los metadatos de control y taxonomía del encuentro. Al crearse, el sistema genera de forma automática los enlaces de acceso tanto para los agentes como para los asistentes.

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

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
notifyCreationEnvía notificación participante en la creación de la cita:
false -> No envía notificación
true -> Envía notificación		NOBoolean
checkAgendaRevisa la agenda del usuario:
false -> No valida si ya tiene huecos ocupados
true -> Valida si tiene disponibilidad en el tramo en el que se quiere crear la cita, en caso contrario devuelve error de agenda no disponible.		NOInteger
councilOptions.notificationTypeMétodo de notificación solicitado por el participante:
0 -> email
1 -> SMS
2 -> Whatspp		NOInteger

Desglose del Objeto participant (ParticipantInput)

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

Campos de Respuesta (Payload)

La respuesta exitosa devuelve el objeto createOneOnOneCouncil con los identificadores de acceso seguro:

CampoTipoDescripción
idArrayIdentificador interno único de la cita generada en la plataforma OVAC.
accessLinkStringEnlace único de acceso directo (Tokenizado) para auditar, gestionar o iniciar la cita.
creatorIdIntegerIdentificador único del usuario o API Key que ha dado de alta la cita.

Ejemplos de Código y Peticiones

1. Mutación GraphQL

mutation createOneOnOneCouncil(
    $council: CouncilInput,
    $participant: ParticipantInput,
    $notifyCreation: Boolean,
    $checkAgenda: Boolean,
    $councilOptions: CouncilOptions    
    )
    {
        createOneOnOneCouncil
            (
            council: $council,
            participant: $participant,
            notifyCreation: $notifyCreation,
            checkAgenda: $checkAgenda,
            councilOptions: $councilOptions
            )
        {
            id
            accessLink
            creatorId
        }
    }

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

{
    "council": {
        "name": "test",
        "companyId": 1234,
        "statuteId": 9876,
        "councilType": 5,
        "externalId" : "",
        "contactEmail": "",
        "dateStart": "2026-10-19T15:00Z",
        "conveneText": "",
        "observations": "",
        "internalNotes": "",
        "language":"es",
        "comment": "",
        "readOnly": 0,
        "tag": "ADMIN",
        "userScheduleId": -1
    },
    "participant": {
        "name": "",
        "surname": "",
        "idCardType": "dni",
        "dni" : "",
        "idCardCountry": "ES",
        "email": "",
        "phone": "+34600000000",
        "language":"es",
        "zipcode": "00000"
    },
    "notifyCreation": true,
    "checkAgenda": true,
    "councilOptions": 
    { 
        "notificationType": 0 
    }    
}

3. Ejemplo de comando cURL

curl --location 'https://api.tgss.pre.councilbox.com/graphql' \
--header 'apikey: alejandro.maneiro+prof@councilbox.com' \
--header 'Content-Type: application/json' \
--header 'x-jwt-token: ••••••' \
--data-raw '{"query":"mutation createOneOnOneCouncil(\r\n    $council: CouncilInput!\r\n    $participant: ParticipantInput!\r\n    $notifyCreation: Boolean\r\n    $checkAgenda: Boolean\r\n    $councilOptions: CouncilOptions    \r\n    ){\r\n        createOneOnOneCouncil(\r\n            council: $council\r\n            participant: $participant\r\n            notifyCreation: $notifyCreation\r\n            checkAgenda: $checkAgenda\r\n            councilOptions: $councilOptions\r\n            )\r\n            {\r\n                id\r\n                accessLink\r\n                creatorId\r\n            }\r\n    }","variables":{"council":{"name":"Nombre de la cita","companyId":1590,"statuteId":3784,"councilType":5,"externalId":"0000ABCD","contactEmail":"","dateStart":"2026-10-15T15:00Z","conveneText":"","observations":"","internalNotes":"","language":"es","comment":"","readOnly":0,"tag":"ADMIN","userScheduleId":-1},"participant":{"name":"ANIBAL","surname":"PÉREZ SÁNCHEZ","idCardType":"dni","dni":"77777777B","idCardCountry":"ES","email":"alejandro.maneiro@councilbox.com","phone":"+34600000000","language":"es","zipcode":"00000"},"notifyCreation":true,"checkAgenda":true,"councilOptions":{"notificationType":0}}}'

4. Respuesta Esperada (200 OK)

{
    "data": {
        "createOneOnOneCouncil": {
            "id": 64917,
            "accessLink": "https://apitest.ovac.pre.councilbox.com/attendance/token/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb3VuY2lsUGFydGljaXBhbnRJZCI6MjQ5MDE2LCJpZCI6MjQ5MDE2LCJpYXQiOjE3NzkzNjE2Njl9.facpLzBhYA-KmDt9j2zMA32gMhyyBzUc47PNlSyFkaA",
            "creatorId": 3476
        }
    }
}

Nota OpenAPI/Fern: esta operación GraphQL se documenta como /graphql/createoneononecouncil 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.