API Keys

Cree y administre llaves de API para que sus sistemas externos accedan a la API REST y GraphQL de ALTUM ERP de forma programática y autenticada.

Requisitos previos

• Permiso integraciones.api_key.gestionar en ALTUM ERP.

Pantalla de API Keys

Navegue a Integraciones → API Keys para ver y gestionar las llaves existentes.

La tabla muestra las llaves activas con las columnas:

Columna	Descripción
Nombre	Nombre descriptivo para identificar la llave.
Alcance de permisos	READ_ONLY, READ_WRITE o CUSTOM.
Últimas peticiones	Contador de usos recientes.
Creada	Fecha de creación de la llave.
Última actividad	Fecha del último uso registrado.
Estado	Activa o revocada.

Crear una API Key

Paso 1: Abrir el formulario de nueva llave

Haga clic en el botón Nueva API Key.

Paso 2: Completar los datos

Campo	Descripción
Nombre	Nombre para identificar el uso de esta llave (ejemplo: Sistema de bodega, ERP externo).
Descripción	Texto opcional con más detalle sobre el propósito.
Alcance de permisos	Nivel de acceso que tendrá la llave (ver tabla de alcances).

Paso 3: Seleccionar el alcance de permisos

Alcance	Descripción
READ_ONLY	La llave solo puede realizar operaciones de lectura (GET y consultas GraphQL). No puede crear, modificar ni eliminar datos.
READ_WRITE	La llave puede realizar todas las operaciones CRUD sobre los recursos permitidos.
CUSTOM	La llave tiene un conjunto granular de permisos definido en la configuración avanzada, con control por recurso.

Paso 4: Guardar y copiar la llave

Al guardar, el sistema genera la API Key y la muestra una sola vez en un diálogo de confirmación.

Precaución

Copie la API Key antes de cerrar el diálogo. No es posible recuperarla después. Si la pierde, deberá revocar la llave actual y crear una nueva.

Actualizar una API Key

Para cambiar el nombre, descripción o alcance de una llave existente, use el botón Editar en la fila correspondiente de la tabla. El valor de la llave no cambia al editarla.

Revocar una API Key

Para inhabilitar permanentemente una llave, use el botón Revocar en la tabla. La revocación es irreversible; cualquier sistema que use esa llave perderá acceso inmediatamente.

Nota

Las llaves revocadas se mantienen en el historial para auditoría pero no se pueden reactivar.

Uso de la API Key en peticiones

Incluya la API Key en el header Authorization de cada petición:

Authorization: Bearer <api_key>

También debe incluir el header X-Tenant-ID con el identificador de su empresa:

X-Tenant-ID: <tenant_id>

Ejemplo con cURL:

curl -H "Authorization: Bearer altum_xxxxxxxxxxxxxxxx" \
     -H "X-Tenant-ID: su-tenant-id" \
     https://api.altum-erp.com/api/v1/productos

Monitoreo de uso

La pantalla de API Keys muestra métricas de uso para cada llave. El detalle de una llave incluye:

• Gráfica de peticiones por período.
• Desglose por tipo de operación (lectura / escritura).
• Tasa de errores.

Reglas y validaciones

• Las API Keys se generan con crypto.randomBytes(32) y se almacenan con hash en la base de datos; el valor en texto claro solo se muestra al crearla.
• Una llave READ_ONLY que intente una operación de escritura recibirá el error 403 Forbidden.
• El alcance CUSTOM requiere que los permisos granulares estén definidos en el campo permissions de la llave; sin permisos definidos, la llave no puede acceder a ningún recurso.
• Las llaves revocadas no pueden reactivarse; debe crear una nueva llave.

Casos frecuentes

El sistema externo recibe 401 Unauthorized. Verifique que el header Authorization esté presente y que el valor sea exactamente Bearer <api_key> (con el prefijo Bearer y un espacio). También confirme que la llave no haya sido revocada.

El sistema externo recibe 403 Forbidden en operaciones de escritura. La llave tiene alcance READ_ONLY. Cree una nueva llave con alcance READ_WRITE o CUSTOM con los permisos necesarios.

Necesito acceso temporal para pruebas de integración. Cree una llave con nombre descriptivo como Test integración 2026-06, realice las pruebas y revóquela cuando termine. Esto mantiene un historial claro de accesos.