Saltar al contenido principal

La API y las integraciones a medida

Claves de API: leer datos desde fuera

Actualizado el 5 de octubre de 2026

Ajustes → Integraciones → Claves de API. Solo administración.

Una clave permite que otro sistema —tu web, un cuadro de mando, un exportador nocturno— consulte tus datos sin iniciar sesión.

Las claves son de solo lectura. Sirven para leer; ninguna puede crear, modificar ni borrar nada. Es a propósito: una clave acaba antes o después en un repositorio, en una hoja de cálculo o en el portapapeles de alguien, y una clave filtrada que solo lee es un disgusto — una que escribe es un desastre.

Crear una

  1. Ponle un nombre que te diga qué la usa («Web de la clínica», «Cuadro de mando»). Cuando tengas cinco agradecerás saber cuál revocar.
  2. Marca qué puede leer. Hay cuatro permisos: clientes, mascotas, citas y el catálogo de servicios. Marca solo los que necesite: una clave que solo lee servicios no puede sacar la lista de clientes ni aunque se filtre.
  3. Copia la clave. Se enseña una sola vez. Después solo se guarda su huella, así que no hay forma de recuperarla: si la pierdes, revócala y crea otra. Es lo mismo que pasa con el secreto de un webhook, y por la misma razón: una clave que se puede volver a leer desde la pantalla es una clave que se filtra con la pantalla.

En la tabla, cada clave aparece con sus cuatro últimos caracteres (gk_…7Kp2) para distinguirlas, con lo que puede leer y con la fecha de su último uso — que es como se detecta una clave que ya no usa nadie y conviene retirar.

Usarla

La clave viaja en la cabecera Authorization de cada petición:

curl https://tu-centro.guaukit.com/api/v1/clients \
  -H "Authorization: Bearer gk_tu_clave_aqui"

Las cinco direcciones disponibles:

DirecciónQué devuelveFiltros
/api/v1/clientsClientessearch
/api/v1/patientsMascotasclientId, search
/api/v1/appointmentsCitasfrom, to, status, patientId
/api/v1/servicesCatálogo de serviciosbookable, publiclyBookable
/api/v1/availabilityLas horas libres de un servicioserviceId y date, o from y to

Los cuatro listados admiten limit (máximo 100) y offset, y responden con la misma envoltura: { items, total, limit, offset }. El total es el de la consulta entera, no el de la página, así que sirve para saber cuántas vueltas quedan. availability es la excepción: no es un listado paginado y responde { serviceId, durationMinutes, timezone, days }.

to no incluye el día que le pongas. from=2026-08-01&to=2026-08-02 devuelve el 1 de agosto entero. Es lo contrario de lo que mucha gente supone, pero es lo que evita que una cita justo en el borde aparezca en dos días distintos. Las fechas se interpretan en UTC, que es como están guardadas.

Montar un calendario de reservas en tu web

Es lo que junta tres de las cinco direcciones:

  1. Qué se puede ofrecer — /api/v1/services?publiclyBookable=true.
  2. Qué horas quedan — /api/v1/availability?serviceId=…&from=…&to=….
  3. Reservar — por el enlace público de tu centro. La API es de solo lectura, así que la reserva en sí la hace el visitante en esa página.

Tres cosas de availability que conviene tener claras:

  • bookable y publiclyBookable no son lo mismo. El primero es el permiso de un cliente con cuenta en el portal; el segundo, el de cualquiera que pase por internet, que nace apagado y se enciende servicio a servicio. Un calendario montado sobre bookable=true ofrece servicios para los que availability contesta siempre service_not_public: sale vacío y sin explicación.

  • Las horas van en la zona horaria del centro, no en UTC ni en la de quien pregunta. Por eso viaja timezone al lado; sin mirarlo, una web las pintaría desplazadas y no se notaría hasta el primer cliente que llegue una hora tarde.

  • Cuando un día no tiene horas, dice por qué en reason:

    reasonQué pasa
    service_not_publicEse servicio no está abierto a internet (o no existe)
    past_dateEl día ya pasó
    beyond_horizonEstá más allá de los días vista que admite el centro
    closedEse día no se abre
    no_staffNo hay nadie de turno que pueda atenderlo
    daily_limitSe ha llegado al tope diario de ese servicio
    fully_bookedHay turno, pero está todo cogido

El rango va hasta 31 días por petición, y esta dirección tiene un freno más apretado que las demás (60 por minuto): cada día son varias consultas, así que un mes son casi doscientas.


Lo que no sale por la API. Las anotaciones internas del centro no cruzan esta puerta: notas del mostrador, condiciones de alerta de una mascota, el motivo por el que se vetó a alguien, los datos de facturación de un cliente y la configuración interna de un servicio. De una mascota vetada sí sale que está vetada —una web de reservas necesita saberlo— pero no por qué.

Si algo falla, la respuesta lleva siempre un código estable y un mensaje:

CódigoQué pasó
missing_api_key (401)No mandaste la cabecera Authorization
invalid_api_key (401)La clave no existe o se revocó
insufficient_scope (403)La clave no tiene marcado ese permiso
rate_limited (429)Más de 120 peticiones por minuto con la misma clave
bad_request (400)Un parámetro mal escrito; el mensaje dice cuál

Revocar una clave la deja fuera al momento: la siguiente petición ya recibe un 401. Hazlo en cuanto sospeches que se ha filtrado; crear otra cuesta diez segundos.


¿Esto no te resuelve la duda?

Si ya usas GuauKit, abre un aviso desde Soporte, en la propia aplicación: nos llega con tu centro y tu plan, y te contestamos allí mismo. Si todavía no tienes cuenta, escríbenos.