Responsable editorial: Kiuu
API de turnos: cuándo integrar y qué preguntar antes
Cuándo conviene integrar un sistema de turnos con la API, qué permite y qué no la API de Kiuu, y las preguntas de seguridad y mantenimiento antes de empezar.
Conviene integrar un sistema de turnos por API cuando otro sistema necesita crear o leer turnos y tienes un equipo técnico que lo mantenga. La API de Kiuu usa credenciales con permisos (leer turnos, crear turnos, leer colas), tokens OAuth2 con expiración y webhooks firmados con HMAC y reintentos; no expone citas. Se contrata una vez para toda la organización. Antes de integrar, define el caso de uso y el responsable.
Integrar es una decisión de mantenimiento
Una integración por API se programa en semanas y se mantiene durante años. Por eso la pregunta no es «¿podemos conectarlo?» sino «¿quién la va a mantener y para qué?». Una integración sin dueño se rompe en silencio. Esta guía ayuda a decidir si te conviene y qué preguntar. La referencia técnica está en el manual de API para Desarrolladores.
Cuándo conviene
| Caso | Qué haría la integración | ¿Conviene? |
|---|---|---|
| Un sistema propio necesita crear turnos | Crear turnos desde otro sistema (por ejemplo, una app o un kiosco propios) | Sí, si hay equipo técnico |
| Quieres mostrar el estado de las colas en otro lugar | Leer las colas | Sí, con un propósito claro |
| Quieres reaccionar a eventos (turno llamado, completado) | Recibir webhooks | Sí, si el sistema receptor los procesa de forma confiable |
| Solo quieres reportes | Usar las Estadísticas y exportar a CSV | Probablemente no hace falta API |
| No hay un equipo que mantenga la integración | — | Mejor esperar |
Qué cubre la API de Kiuu
- Credenciales con permisos específicos: leer turnos, crear turnos y leer colas.
- Tokens OAuth2 con expiración.
- Webhooks firmados con HMAC, con un panel de entregas y reintentos.
- Eventos típicos: turno llamado, atendido, transferido o completado; encuesta respondida; mensaje entrante de WhatsApp; estado de entrega de un webhook.
- Documentación de referencia y eventos disponibles desde el panel técnico.
- Una sola suscripción para toda la organización; no se contrata por sede.
Qué no cubre
- No expone citas. Si necesitas integrar la agenda, la API actual no lo permite.
- No reemplaza la configuración de servicios, prioridades o usuarios, que se hace en la plataforma.
- No es una integración lista para usar con sistemas de terceros: es una API para que tu equipo o un proveedor construya la integración.
Preguntas antes de empezar
Sobre el caso de uso
- ¿Qué proceso mejora esta integración, y cómo lo mediremos?
- ¿Qué pasa si la integración falla? ¿Hay un plan manual?
- ¿Quién es el dueño técnico y quién el dueño del negocio?
Sobre seguridad
- ¿Qué permisos mínimos necesita cada credencial? Crea una credencial por integración y con el permiso estrictamente necesario.
- ¿Dónde se guardan los secretos y quién tiene acceso?
- ¿Cómo se rotan los tokens y qué ocurre cuando alguien deja el equipo?
- ¿El receptor de webhooks verifica la firma HMAC de cada evento?
Sobre datos personales
- ¿Qué datos de personas viajan por la integración y por qué?
- ¿Dónde se almacenan en el sistema receptor y por cuánto tiempo?
- ¿La política de privacidad lo menciona? Ver cómo debería ser.
Sobre mantenimiento
- ¿Quién revisa el panel de entregas de webhooks y los reintentos fallidos?
- ¿Qué ocurre cuando cambia una versión de la API?
- ¿Hay un entorno de pruebas?
Buenas prácticas para el equipo técnico
- Una credencial por integración, con permisos mínimos y nombre descriptivo.
- Verificar siempre la firma de los webhooks antes de procesarlos.
- Idempotencia: si un evento llega dos veces por un reintento, el receptor debe tolerarlo.
- Registrar los fallos y revisarlos con frecuencia.
- Documentar la integración: qué hace, qué credenciales usa y quién la mantiene.
Antes de la API: ¿hace falta?
Muchas necesidades se resuelven sin integrar: las Estadísticas se exportan a CSV, el seguimiento del turno es una página con enlace, y las aplicaciones opcionales cubren pantallas, avisos y encuestas. Integra cuando haya un sistema concreto que lo necesite y un equipo que lo cuide. Para ordenar las etapas de crecimiento, mira la guía de crecimiento.
Errores frecuentes
- Integrar sin un dueño técnico.
- Una sola credencial con todos los permisos para varias integraciones.
- No verificar la firma de los webhooks.
- No revisar nunca el panel de entregas fallidas.
- Esperar que la API exponga citas.
Preguntas frecuentes
¿Se contrata una API por sede?
No. Una sola suscripción cubre toda la organización.
¿Puedo crear citas por API?
No. La API actual no expone citas; permite leer y crear turnos y leer colas.
¿Cómo sé que un webhook es auténtico?
Los webhooks van firmados con HMAC. El sistema que los recibe debe verificar la firma con el secreto de la integración antes de procesar el evento.