Qué es esto
Un estudio que usa Hive puede dejar que otro sistema lea su agenda. Es lo que hace falta, por ejemplo, para mandarle a un socio un recordatorio de su cita desde un servicio de fuera.
Todo es de solo lectura. No hay forma de agendar, mover, cancelar ni confirmar una cita desde aquí. Y no viaja ningún dato clínico del socio: qué queda fuera.
Quien decide abrir su agenda es el estudio, y puede cerrarla cuando quiera. Si dejas de recibir respuesta, lo primero que hay que preguntarle es si revocó la llave.
Cómo se obtiene la llave
La genera la propio estudio, no nosotros. Un administrador entra a Ajustes → Integraciones, crea una llave para «un servicio externo» y la copia con un botón.
Conviene una llave por proveedor: así el estudio puede cortarle a uno sin dejar sin servicio a los demás. Y trátala como una contraseña — quien la tenga ve esa agenda.
Consultar las citas
curl -H "Authorization: Bearer TU_LLAVE" \
"https://hivegyms.com/api/v1/appointments?desde=2026-08-26&hasta=2026-09-02"Sin cabecera, o con una llave inválida o revocada, responde 401.
Parámetros
| Parámetro | Qué hace |
|---|---|
| desde hasta |
Rango de fechas (AAAA-MM-DD). Máximo 62 días
por consulta. Sin ellos: hoy y los siete días siguientes.
Para un solo día, la misma fecha en las dos.
|
| sucursal_id |
Solo las citas de esa sede. Los números salen en sucursales de la respuesta.
|
| actualizadas_desde | Instante ISO 8601. Devuelve solo lo modificado desde entonces — la forma barata de preguntar «¿qué cambió?» en vez de barrer la agenda entera cada vez. |
| cursor | Página siguiente. Sale en siguiente_cursor. |
| limite | Citas por página. Máximo 500, por omisión 200. |
La respuesta
{
"ok": true,
"desde": "2026-08-26",
"hasta": "2026-09-02",
"zona": "America/Bogota",
"sucursales": [
{ "id": 3, "nombre": "Sede Norte" },
{ "id": 4, "nombre": "Sede Sur" }
],
"siguiente_cursor": null,
"citas": [
{
"id": 4821,
"fecha": "2026-08-27",
"hora": "10:00",
"duracion_minutos": 30,
"inicio": "2026-08-27T10:00:00-05:00",
"zona": "America/Bogota",
"estado": "confirmada",
"recordatorio": "ninguno",
"sucursal": { "id": 3, "nombre": "Sede Norte" },
"coach": { "id": 12, "nombre": "Coach Forero" },
"socio": {
"id": 990,
"nombre": "Juan Pérez",
"telefono": "+57 3001112233",
"email": "[email protected]",
"acepta_whatsapp": true
},
"actualizada_en": "2026-08-26T09:12:44Z"
}
]
}La hora: usa inicio
Es el error más fácil de cometer aquí.
fecha y hora son la hora de pared de la
estudio: «las 10:00» quiere decir las diez en el consultorio, sin huso.
inicio es ese mismo momento con el desfase real de la sucursal, y es el único campo
contra el que se debe calcular «24 horas antes». Si restas sobre la hora suelta, los avisos salen
corridos.
Por eso zona viene por cita y no por estudio: una cadena
puede tener sedes en husos distintos, y Tijuana y Ciudad de México llevan dos horas de diferencia
entre sí.
Estudios con varias sedes
Cada respuesta trae sucursales con las sedes que esa llave
alcanza, y cada cita dice a cuál pertenece. Hay dos formas de trabajar, según cómo la haya creado la
estudio:
Una llave para todal estudio
Lo normal. Vienen las citas de todas las sedes juntas, cada una con su sucursal.
Si solo interesa una, se filtra con sucursal_id.
Una llave por sede
El estudio la acota al crearla, y esa llave no puede ver las demás por más que se le pidan.
Pedir una sucursal_id que la llave no alcanza responde
422 con el motivo, no una
lista vacía — para que no se confunda «no hay citas» con «no tengo acceso».
Campos que pueden venir vacíos
coach es null en las citas agendadas sin asignar profesional (pasa en
recepción, es normal). telefono y email son null cuando la
estudio no los tiene cargados.
Conviene contarlos antes de prometer cobertura: el número de citas no es el número de recordatorios que se pueden mandar.
acepta_whatsapp
Dice si en la ficha del socio alguien marcó explícitamente que acepta recibir WhatsApp.
Es informativo, no una instrucción. Hoy la mayoría lo tienen en
false simplemente porque nadie ha ido a marcarlo, no porque se hayan negado: el
consentimiento real lo tiene el estudio en su aviso de privacidad, firmado al abrir la historia.
A quién se le escribe lo decide el estudio, y es un acuerdo entre ella y su proveedor. Si el criterio es «solo a quien lo marcó», este campo sirve para filtrar; si es «a todo el que dejó teléfono» —que es lo que hace el propio WhatsApp de Hive— el campo se ignora.
Estados de una cita
programada · confirmada · llego · en_silla · en_procedimiento · checkout · completada · cancelada · no_asistio · reagendar
Las canceladas sí aparecen: saber que una cita se cayó suele ser medio motivo de consultar. Lo que no aparece nunca son los bloqueos de horario (almuerzos, juntas) ni las citas eliminadas por error.
recordatorio es el estado del aviso que manda Hive
por WhatsApp (ninguno, enviado, entregado, fallido).
Si los recordatorios los manda un tercero, ese campo se queda en ninguno.
Límites y errores
60 consultas por minuto y por llave.
| Código | Cuándo |
|---|---|
| 401 | Llave ausente, inválida o revocada. |
| 422 | Fechas mal escritas, rango mayor a 62 días, o una sucursal que la llave no alcanza. |
| 429 | Más de 60 consultas en un minuto. |
Todos responden { "ok": false, "error": "…" } con el motivo en castellano.
Feed de calendario
Para ver la agenda en Google Calendar, en el iPhone o en Outlook no hace falta programar nada: en Ajustes → Integraciones el estudio genera una dirección que se pega en el calendario como «suscribirse por URL».
Google Calendar decide por su cuenta cada cuánto vuelve a mirar, y suele tardar entre 8 y 24 horas. No hay forma de apurarlo. Sirve para ver la semana; para reaccionar a un cambio de última hora hay que usar la API.
Incluye desde 30 días atrás hasta 180 adelante, sin las citas canceladas (para que el hueco se borre solo del calendario), y cada evento lleva únicamente el nombre del socio, el coach y la sede.
Qué NO devuelve, y no es un descuido
Ni notas de evolución, ni el motivo de consulta escrito en la cita, ni servicios, planes, presupuestos, saldos, alergias ni anamnesis. Son datos de salud, el estudio responde por ellos, y nada de eso hace falta para avisarle a un socio de su cita.
Tampoco hay forma de escribir: ni agendar, ni mover, ni cancelar, ni confirmar. Si un flujo lo necesita, hay que hablarlo — está fuera a propósito, no por falta de tiempo.