Integración por API

La API de Turno Virtual permite que otros sistemas (por ejemplo, el software de gestión de tu institución) consulten información de tu cuenta de forma automática y, si querés, que tus clientes reserven y cancelen turnos desde tu propio sitio web o tu app. Si recién empezás, leé primero qué es Turno Virtual.

Crear una clave de acceso

Cada sistema que se conecta usa su propia clave. El Administrador de la cuenta las maneja desde el menú de configuración (el engranaje), en Integraciones › Claves de API. La opción aparece solo si tu plan incluye acceso a la API.

Para crear una clave, poné un Nombre que te ayude a reconocer qué sistema la usa y marcá sus Accesos: Reservas, Gestión o ambos. Solo se ofrecen los accesos que incluye tu plan.

Al guardar, la clave completa aparece una sola vez, con un botón para copiarla. Copiala y guardala en un lugar seguro: después no se puede volver a ver. Tiene la forma vit_<prefijo>_<secreto>, y quien la tenga puede consultar la API en nombre de tu cuenta.

En la lista de claves ves cuándo se creó cada una, su nombre, el comienzo de la clave, sus accesos y su Último uso.

Cambiar o eliminar una clave

Podés editar el nombre y los accesos de una clave cuando quieras. Si le sacás todos los accesos, la clave deja de funcionar sin eliminarla.

Si creés que una clave se filtró, o el sistema que la usaba ya no se conecta, eliminala: deja de funcionar en la siguiente consulta. Para reemplazarla, creá una clave nueva, cargala en el otro sistema y después eliminá la vieja.

Hacer una consulta

Todas las direcciones de la API empiezan con /api/v1/ y la clave se envía en el encabezado X-Api-Key. Para comprobar que la clave funciona, consultá a quién pertenece:

GET https://turnovirtual.com/api/v1/me
X-Api-Key: vit_<prefijo>_<secreto>

Las respuestas son JSON. Cuando algo sale mal, la respuesta explica el motivo en formato Problem Details (por ejemplo, 401 si la clave no es válida, o 403 si no tiene permiso para esa consulta).

Documento OpenAPI

La lista completa de consultas disponibles, con sus parámetros y respuestas, está en el documento OpenAPI, que se puede abrir sin clave:

GET https://turnovirtual.com/api/v1/openapi.json

La mayoría de las herramientas de desarrollo pueden importarlo para generar el código de conexión.

Reservar y cancelar turnos

Con el acceso Reservas, tu sitio web o tu app puede ofrecer lo mismo que las reservas online de tu micrositio, con las mismas reglas:

• Ver los horarios libres de una agenda, hasta 31 días por consulta. Se ofrecen solo los horarios que vería tu cliente en el micrositio: franjas en Público, dentro de los Límites de días y, si la agenda lo tiene activado, solo el horario disponible más próximo de cada día.
• Reservar un turno en uno de esos horarios, con los mismos datos que pide el micrositio: el profesional, la cobertura, la práctica y el documento del cliente, entre otros. La duración del turno la define la práctica o el servicio, no el otro sistema. El turno aparece en tu agenda como Solicitado y tu cliente recibe el mismo aviso por correo.
• Cancelar un turno con el documento del cliente. El turno queda Suspendido y el horario se libera.

Si el horario ya no está disponible, la respuesta es 409 para que el otro sistema ofrezca otro. Si falta un dato o no corresponde a la agenda, la respuesta es 422 con el motivo. Si el otro sistema reintenta una reserva que ya se guardó, recibe el mismo turno y no se crea uno nuevo.

Límite de consultas

Cada clave puede hacer hasta 120 consultas por minuto. Si se supera, la API responde 429 con el encabezado Retry-After, que indica cuántos segundos esperar antes de volver a intentar.

Las reservas por API respetan además el Máximo de solicitudes por hora de Configuración › Empresa, pestaña Turno, contado por clave. Las cancelaciones están limitadas a 30 por hora para un mismo documento.