Clave de API: integra otro sistema con tu estudio
La clave de API permite que otro sistema (un ERP, una hoja de cálculo automatizada, un sitio web o una aplicación propia) consulte y registre datos de tu estudio sin que nadie tenga que escribirlos. Cada clave funciona como un usuario del estudio: puede hacer exactamente lo que ese usuario puede hacer, y nada más.
Cuándo usarlo
Sección titulada «Cuándo usarlo»- Un sistema de gestión necesita leer las ventas del día para la contabilidad.
- Un sitio web o una aplicación propia necesita registrar clientes o consultar el catálogo.
- Una automatización necesita registrar gastos o consultar las cuentas por cobrar.
Antes de empezar
Sección titulada «Antes de empezar»Solo quien administra el estudio (con acceso total o permiso para editar Perfiles y Usuarios) puede crear, editar y revocar claves. Si no puedes crear una clave, pídele al dueño del estudio que te habilite el acceso en Accesos → Perfiles.
Te recomendamos crear primero un usuario exclusivo para la integración, con un perfil que habilite solo las pantallas que el otro sistema necesita usar. La clave hereda los permisos de ese usuario.
Paso a paso
Sección titulada «Paso a paso»Paso 1 — Abrir la pestaña API Key
Sección titulada «Paso 1 — Abrir la pestaña API Key»En Configuración → Empresa, abre la pestaña Clave de API. Allí aparece la lista de claves creadas, con el usuario de cada una, las IP permitidas, el Vencimiento y el Último uso.
Paso 2 — Crear la clave
Sección titulada «Paso 2 — Crear la clave»Haz clic en Nueva clave, completa el Nombre y elige el Usuario. En IP permitidas, escribe una IP o un rango por línea para aceptar llamadas solo desde esas direcciones (si lo dejas vacío, se acepta cualquier IP). En Vencimiento, elige Nunca vence o Expira el una fecha: la clave será válida hasta el final de ese día. Haz clic en Crear clave y copia la clave con el botón de copiar. No volverá a mostrarse.
El otro sistema envía la clave en cada llamada, en el encabezado Authorization, así:
Authorization: Bearer hk_... (reemplaza hk_... por la clave completa).
Para usar la clave con una IA (Claude Code, Gemini CLI, Cursor), marca también Permitir uso como conector de IA en Conector de IA. Sin esta opción, la clave funciona con las integraciones, pero no con el conector. Consulta el artículo Conector de IA.
Paso 3 — Revocar una clave
Sección titulada «Paso 3 — Revocar una clave»En la lista, haz clic en el ícono de papelera de la clave y confirma con Revocar. El sistema que usaba la clave perderá el acceso en un máximo de 30 segundos. Para cambiar el nombre, las IP o el vencimiento, usa el ícono del lápiz.
Qué pasa después
Sección titulada «Qué pasa después»- Todo lo que el otro sistema cambie con la clave aparecerá en la Auditoría con el origen Clave de API, a nombre del usuario de la clave.
- La clave dejará de funcionar automáticamente cuando venza o cuando se desactive en el estudio al usuario asociado. En la lista, aparecerá como Vencida o Usuario inactivo.
- Una clave nunca da acceso a otra empresa, aunque su usuario también trabaje en otra.
Errores comunes y dudas
Sección titulada «Errores comunes y dudas»P: ¿La clave puede hacer todo en el sistema? R: No. Tiene los permisos de su usuario y solo en este estudio. Algunas áreas nunca aceptan claves, ni siquiera las de un usuario con acceso total: inicio de sesión y cambio de empresa, la propia pantalla de claves, la gestión de usuarios e invitaciones, Heya, soporte, los paneles, la configuración general de Empresa (logotipo, horarios, feriados, dominio y correo electrónico de los informes) y las pantallas de la plataforma. Si tienes varias integraciones, crea un usuario para cada una: en la Auditoría, los cambios aparecerán a nombre del usuario de la clave.
P: Perdí la clave. ¿Puedo volver a verla? R: No. El sistema solo guarda una huella de la clave, nunca la clave en sí. Revoca la anterior y crea otra.
P: El otro sistema muestra “Esta IP no está autorizada para usar esta clave de API”. ¿Qué hago? R: La IP desde la que hace la llamada no está en IP permitidas. Edita la clave y agrega la IP, o deja la lista vacía para aceptar cualquier IP.
P: El otro sistema muestra “Esta ruta no se puede usar con una clave de API”. ¿Por qué? R: Está intentando acceder a una de las áreas que no aceptan claves (consulta la primera pregunta). Estas operaciones debe hacerlas una persona desde la pantalla.
P: ¿Puedo cambiar el usuario de una clave? R: No. Revoca la clave y crea otra con el nuevo usuario.
P: La lista de usuarios para la nueva clave está vacía. ¿Por qué? R: Los usuarios del equipo de la plataforma no pueden tener una clave de API y no aparecen en la lista. Registra un usuario del propio estudio (preferiblemente uno exclusivo para la integración) y crea la clave para ese usuario.