> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ovac.councilbox.com/metodos-api/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ovac.councilbox.com/_mcp/server. # 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](https://api.postman.com/collections/45758186-75abaa4f-d609-440f-ab82-5c3a7ccd4eb8?access_key=PMAT-01KSPSGDDTHFG0PGS4C9RHNCYD) ## Autenticación Salvo las operaciones públicas o el método **Login**, los métodos requieren autenticación mediante una clave enviada en cabecera: ```http x-jwt-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: | Entorno | URL base | | ------------- | ------------------------------------- | | Preproducción | `https://api.ovac.pre.councilbox.com` | | Producción | `https://api.ovac.councilbox.com` | 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: | Área | Descripción | | -------------------------- | -------------------------------------------------------------------------------------- | | Autenticación | Login y gestión inicial de sesión. | | Disponibilidad y agendas | Consulta de calendarios mensuales, franjas disponibles y reglas de disponibilidad. | | Gestión de citas | Creación, modificación, reprogramación, cancelación y compartición de citas. | | Documentación y evidencias | Consulta de actas, evidencias, grabaciones y documentación final asociada a la sesión. | | Estructura organizativa | Consulta de compañías, sedes, usuarios y datos necesarios para mapear integraciones. | ## 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: ```text /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. ## API Docs - Métodos API > 00 - Authentication [Login](https://docs.ovac.councilbox.com/metodos-api/00-authentication/login.md) - Métodos API > 01 - Load Global Configuration [Get Languages](https://docs.ovac.councilbox.com/metodos-api/01-load-global-configuration/languages.md) - Métodos API > 01 - Load Global Configuration [Get Organization Companies](https://docs.ovac.councilbox.com/metodos-api/01-load-global-configuration/organization-companies.md) - Métodos API > 01 - Load Global Configuration [Get Organization Users](https://docs.ovac.councilbox.com/metodos-api/01-load-global-configuration/organization-users.md) - Métodos API > 01 - Load Global Configuration [Get Company Procedures](https://docs.ovac.councilbox.com/metodos-api/01-load-global-configuration/statutes.md) - Métodos API > 02 - Create Appointments [Create Appointment](https://docs.ovac.councilbox.com/metodos-api/02-create-appointments/create-one-on-one-council.md) - Métodos API > 02 - Create Appointments [Create Appointment Management](https://docs.ovac.councilbox.com/metodos-api/02-create-appointments/create-one-on-one-council-2.md) - Métodos API > 02 - Create Appointments [Create Appointment Representation](https://docs.ovac.councilbox.com/metodos-api/02-create-appointments/create-appointment.md) - Métodos API > 02 - Create Appointments [Create Appointment Representation Guests](https://docs.ovac.councilbox.com/metodos-api/02-create-appointments/create-appointment-2.md) - Métodos API > 02 - Create Appointments [Create Appointment_External](https://docs.ovac.councilbox.com/metodos-api/02-create-appointments/create-one-on-one-council-3.md) - Métodos API > 02 - Create Appointments [Create Appointment Management_External](https://docs.ovac.councilbox.com/metodos-api/02-create-appointments/create-one-on-one-council-4.md) - Métodos API > 02 - Create Appointments [Create Appointment Representation_External](https://docs.ovac.councilbox.com/metodos-api/02-create-appointments/create-appointment-3.md) - Métodos API > 02 - Create Appointments [Create Appointment Representation Guests_External](https://docs.ovac.councilbox.com/metodos-api/02-create-appointments/create-appointment-4.md) - Métodos API > 03 - Manage Appointments [Assign Appointment to Operator](https://docs.ovac.councilbox.com/metodos-api/03-manage-appointments/assign-council-to-user.md) - Métodos API > 03 - Manage Appointments [Assign Appointment to Operator_External](https://docs.ovac.councilbox.com/metodos-api/03-manage-appointments/assign-council-to-user-2.md) - Métodos API > 03 - Manage Appointments [Reschedule Appointment](https://docs.ovac.councilbox.com/metodos-api/03-manage-appointments/reschedule-appointment.md) - Métodos API > 03 - Manage Appointments [Cancel Appointment](https://docs.ovac.councilbox.com/metodos-api/03-manage-appointments/cancel-appointment.md) - Métodos API > 03 - Manage Appointments [Cancel Appointment_External](https://docs.ovac.councilbox.com/metodos-api/03-manage-appointments/cancel-appointment-2.md) - Métodos API > 03 - Manage Appointments [Share Appointment](https://docs.ovac.councilbox.com/metodos-api/03-manage-appointments/share-appointment.md) - Métodos API > 03 - Manage Appointments [Close Appointment](https://docs.ovac.councilbox.com/metodos-api/03-manage-appointments/end-council.md) - Métodos API > 03 - Manage Appointments [Add Step to Appointment](https://docs.ovac.councilbox.com/metodos-api/03-manage-appointments/add-agenda-point.md) - Métodos API > 03 - Manage Appointments [Update Appointment External ID](https://docs.ovac.councilbox.com/metodos-api/03-manage-appointments/update-council.md) - Métodos API > 03 - Manage Appointments [Upload Appointment Act](https://docs.ovac.councilbox.com/metodos-api/03-manage-appointments/upload-appointment-act.md) - Métodos API > 04 - Get Appointment Information [Get Appointments](https://docs.ovac.councilbox.com/metodos-api/04-get-appointment-information/councils.md) - Métodos API > 04 - Get Appointment Information [Get Appointments_External](https://docs.ovac.councilbox.com/metodos-api/04-get-appointment-information/councils-2.md) - Métodos API > 04 - Get Appointment Information [Get Appointment Information](https://docs.ovac.councilbox.com/metodos-api/04-get-appointment-information/council-info.md) - Métodos API > 04 - Get Appointment Information [Get Appointment Information_External](https://docs.ovac.councilbox.com/metodos-api/04-get-appointment-information/council-info-2.md) - Métodos API > 04 - Get Appointment Information [Get Appointment Evidence Summary](https://docs.ovac.councilbox.com/metodos-api/04-get-appointment-information/council-evidence-summary.md) - Métodos API > 04 - Get Appointment Information [Get Appointment Evidence Summary_External](https://docs.ovac.councilbox.com/metodos-api/04-get-appointment-information/council-evidence-summary-2.md) - Métodos API > 04 - Get Appointment Information [Get Appointment Documentation](https://docs.ovac.councilbox.com/metodos-api/04-get-appointment-information/appointment-documents.md) - Métodos API > 04 - Get Appointment Information [Get Appointment Document Folders](https://docs.ovac.councilbox.com/metodos-api/04-get-appointment-information/council-documentation.md) - Métodos API > 04 - Get Appointment Information [Get Agenda Information](https://docs.ovac.councilbox.com/metodos-api/04-get-appointment-information/agenda.md) - Métodos API > 04 - Get Appointment Information [Get Available Appointment Agendas](https://docs.ovac.councilbox.com/metodos-api/04-get-appointment-information/council.md) - Métodos API > 05 - Check Schedule Availability [Get Company Month Schedule](https://docs.ovac.councilbox.com/metodos-api/05-check-schedule-availability/company-ovac-schedule.md) - Métodos API > 05 - Check Schedule Availability [Get Day slots](https://docs.ovac.councilbox.com/metodos-api/05-check-schedule-availability/company-ovac-day-slots.md) ## OpenAPI Specification The raw OpenAPI 3.1 specification for this API is available at: - [OpenAPI JSON](https://docs.ovac.councilbox.com/openapi.json) - [OpenAPI YAML](https://docs.ovac.councilbox.com/openapi.yaml)