17. API de integración y claves API

La API de integración sirve para que tu propio programa, hoja de cálculo o script lea de forma automática los datos de tus proyectos: la lista de proyectos, los listados de cables y de materiales, la tabla de circuitos y la lista de bornes de los cuadros, la medición de cantidades y la composición del paquete de proyecto. La API es de solo lectura: no modifica ni el dibujo ni el proyecto.

Quién puede obtener una clave de API

La clave de API la habilita el operador para cada cuenta. Si tu cuenta ha recibido el permiso, en la página Perfil aparece la tarjeta Claves de API; sin el permiso la tarjeta no se ve. Una cuenta puede tener como máximo 5 claves activas a la vez.

La clave ve los mismos proyectos que tú: los tuyos y, previa solicitud, los que se han compartido contigo. Los listados y la medición de un proyecto compartido solo se devuelven si el uso compartido permite también la exportación.

Crear una clave

1. En la tarjeta Claves de API de la página Perfil, haz clic en el botón Nueva clave.
2. Dale un nombre a la clave (por ejemplo, el nombre del programa que la va a usar).
3. Elige el alcance: Leer proyectos da la lista de proyectos y sus datos, Leer documentos da los listados, la medición y el paquete de proyecto. Indica solo lo que el programa realmente necesita.
4. Elige la caducidad: 30, 90 o 365 días. Una clave caducada deja de funcionar; en su lugar creas una nueva.
5. Introduce tu contraseña actual (en una cuenta sin contraseña hace falta un inicio de sesión reciente). En la primera clave, acepta las condiciones de uso de la API.

Tras la creación, la clave se muestra una sola vez: cópiala y guárdala en un lugar seguro. Después, la lista solo muestra su prefijo (avk_…), con las fechas de creación y de caducidad, el último uso y el número de llamadas. También enviamos una notificación por correo electrónico sobre la nueva clave (sin la clave).

Revocar una clave

Con el botón Revocar junto a la clave en la tarjeta, la clave queda inutilizable de inmediato; esto no se puede deshacer. Revoca la clave cuando ya no la uses, cuando retires el programa que la usaba o si sospechas que se ha filtrado.

Consejos de seguridad

• Trata la clave como tu contraseña: quien la conozca puede leer tus proyectos dentro del alcance indicado.
• Guárdala en un almacén de secretos (gestor de contraseñas, variable de entorno del servidor o variable secreta de la CI), no en el código fuente: que no acabe en el repositorio git, en una hoja de cálculo compartida ni en un correo electrónico.
• No la uses en código que se ejecuta en el navegador (página web, extensión del navegador): allí cualquiera puede leerla. El lugar de la clave es un servidor, un script o un programa de escritorio.
• Cada programa debe tener su propia clave, con el alcance más estrecho posible y una caducidad corta; así, revocar una clave no detiene nada más.

Uso desde un programa

En la cabecera de la petición, la clave se envía como token Bearer: Authorization: Bearer avk_…. Los endpoints están bajo /api/v1/ (por ejemplo GET /api/v1/projects) y responden en JSON. La descripción completa en formato OpenAPI está disponible en /api/v1/openapi.json; la mayoría de las herramientas de desarrollo pueden importarla.

El número de llamadas está limitado por clave y por cuenta (por defecto 60 por minuto y 10 000 al día); al superarlo, el servidor responde con 429, así que espera un poco. El inicio de sesión en la web (cookie) no abre la API, y la clave no inicia sesión en la interfaz web.