Introducción a la documentación API de OVAC

La API OVAC permite integrar sistemas externos con la Oficina Virtual de Atención Ciudadana de Councilbox. Esta referencia técnica recoge los métodos disponibles para automatizar el ciclo de vida de una cita, consultar disponibilidad de agenda, gestionar participantes, obtener documentación asociada a una sesión y acceder a información organizativa necesaria para la integración.

La mayoría de operaciones se consumen mediante GraphQL a través de peticiones POST sobre el endpoint /graphql. Para facilitar la lectura y navegación de la documentación, cada operación se presenta como un método independiente, aunque técnicamente comparta el mismo endpoint GraphQL de transporte.

Colección pública de Postman

La colección pública utilizada como fuente funcional de esta documentación está disponible en Postman. La publicación automática consulta la colección viva mediante la API de Postman y no depende de una exportación JSON estática versionada:

• Descargar colección pública API OVAC en Postman

Autenticación

Salvo las operaciones públicas o el método Login, los métodos requieren autenticación mediante una clave enviada en cabecera:

1
x-jwt-token: <token>

El token se obtiene ejecutando el método Login con las credenciales asignadas al integrador. Una vez obtenido, debe enviarse en las llamadas protegidas mediante la cabecera x-jwt-token.

Entornos

Los entornos principales son:

En despliegues privados o dedicados, la URL base puede variar y deberá sustituirse por el dominio corporativo asignado.

Bloques funcionales

Los métodos están agrupados en las siguientes áreas:

Notas técnicas de integración

Arquitectura híbrida

La colección utiliza una arquitectura híbrida:

• La mayoría de operaciones se ejecutan mediante consultas y mutaciones GraphQL sobre el endpoint centralizado /graphql.
• Los métodos de descarga de archivos físicos, como actas, grabaciones y firmas, utilizan una arquitectura REST nativa mediante peticiones GET.

Modelo de documentación GraphQL

Aunque técnicamente varias operaciones se ejecutan contra /graphql, la referencia puede mostrar cada query o mutation como una operación independiente para facilitar su lectura y consumo documental.

Ejemplos de rutas documentales:

/graphql/login
/graphql/create-appointment
/graphql/council-evidence-summary

Estas rutas son documentales. La ruta técnica real de ejecución es /graphql, salvo en los métodos REST de descarga.

Procesamiento de errores

Las respuestas de infraestructura devuelven códigos HTTP estándar. Sin embargo, las violaciones de reglas de negocio de EVID o los fallos de validación de datos pueden encapsularse dentro de un array errors en el cuerpo JSON, manteniendo un estado HTTP 200 OK en la capa de transporte GraphQL.

Por este motivo, una integración no debe validar únicamente el código HTTP. También debe comprobar el contenido semántico del cuerpo de respuesta.