API, webhooks y asistentes de IA

Para conectar Kalmee con el gestor de expedientes, la sede electrónica, una app municipal o un asistente de IA. Está en los planes Profesional y Multisede, y lo gestionan la propiedad y la administración en Configuración → Integraciones (API). La documentación técnica para desarrolladores está en kalmee.com/desarrolladores.

Claves de API

Cada programa usa su propia clave, que da acceso a la organización sin iniciar sesión. Guárdala como una contraseña.

En Crear una clave escribe el Nombre del programa («Gestor de expedientes») y elige Qué puede hacer: Leer; Dar números y gestionar citas; o Administración (solo la propiedad). Da solo los permisos que necesite.
Pulsa Crear clave. Kalmee la enseña una sola vez: cópiala y pulsa Ya la he guardado. Si la pierdes, revócala y crea otra.
En Claves ves el Último uso de cada una. Revocar la desactiva al momento y no se puede deshacer; una clave revocada se puede Eliminar de la lista.

Puede haber hasta 20 claves activas. Todo lo que hace una clave queda en el Registro de actividad con su nombre. La API nunca devuelve el nombre, el correo, el teléfono ni el DNI de las personas, y cada clave admite 120 peticiones por minuto.

Webhooks: avisos al momento

Con los webhooks Kalmee avisa a tu programa en cuanto pasa algo, sin que tenga que preguntar.

En Añadir una dirección escribe la Dirección (URL), que tiene que empezar por https:// y ser pública en internet, una Descripción (opcional) y marca Qué avisos quieres recibir: de Turnos (se da, se llama, se termina de atender, no se presenta, se anula, se pasa a otro trámite o mesa) y de Citas (se reserva, se anula, cambia la hora, la persona llega y confirma).
Pulsa Añadir dirección. Kalmee enseña una sola vez el secreto de firma (empieza por whsec_): tu programa lo necesita para comprobar cada aviso. Cópialo y pulsa Ya lo he guardado.
Con Enviar prueba mandas un aviso de prueba y ves si ha llegado.

Cada dirección se puede Editar, Pausar y Activar, cambiar su secreto con Nuevo secreto o Eliminar. En Últimos envíos ves el código de respuesta y la duración de cada uno (nunca el contenido), durante 30 días. Si tu servidor no responde, el aviso se reintenta unas 24 horas; si una dirección falla sin parar o pide no recibir más, Kalmee la desactiva, te lo dice en esta página y puedes pulsar Volver a activar cuando esté arreglada. Hasta 10 direcciones por organización.

Asistentes de IA (servidor MCP)

Un asistente de IA compatible con MCP (Claude, ChatGPT u otro) puede consultar y usar Kalmee: ver la cola en directo, las citas y las estadísticas, dar números y reservar o anular citas. Usa las mismas claves de API, con los mismos permisos, límites y registro de actividad.

Crea una clave solo para el asistente y con el permiso mínimo: Leer para consultar; Dar números y gestionar citas solo si también debe dar números o gestionar citas.
Dirección del servidor: https://app.kalmee.com/api/mcp. En la configuración del conector, la clave va en la cabecera Authorization con el valor «Bearer» seguido de la clave. En Claude, el conector personalizado se añade en Ajustes → Conectores.
El asistente ve los mismos datos que la API: nunca el nombre, el correo, el teléfono ni el DNI. Revisa lo que propone antes de que reserve o anule citas.
Si la clave se ha compartido por error, Revocar la deja sin efecto al momento.

Códigos DIR3 y SIA (administraciones públicas)

Si eres una administración, puedes guardar los códigos oficiales (todos opcionales):

Código DIR3 (opcional) de la organización, en Organización → Datos de la organización, como L01030140 para un ayuntamiento.
Código DIR3 (opcional) de cada oficina o unidad, al crear o editar la oficina, como LA0012345. Son 9 caracteres (una letra y ocho letras o cifras) y no puede repetirse entre oficinas.
Código SIA (opcional) de cada trámite, en Oficinas → tu oficina → Trámites: el número del procedimiento en el Inventario de procedimientos, como 2042730.

La API los devuelve (dir3_code y sia_code) y permite buscar con ?dir3= y ?sia=, para enlazar con tu sede electrónica sin guardar identificadores.