API Keys
Una API key permite que un sistema externo (ERP, BI, integración propia) consulte la API de INSSACS sin usar tu sesión.
Las API keys son su propio recurso de permisos: Ver API keys muestra la sección, Crear API keys habilita el botón de creación y Eliminar API keys, el de revocar. La sección solo está disponible para operadores globales o de cliente; un operador de cuenta u operación no la ve.
Qué endpoints existen, qué cuerpo espera cada uno y qué devuelve está en API para integraciones.
Crear una key
| Campo | Nota |
|---|---|
| Nombre | Para reconocerla después (Integración ERP). |
| Cuenta | Opcional. Vacía = key de cliente: opera sobre todas las cuentas del cliente, incluidas las futuras. Con una cuenta elegida, queda acotada solo a esa. |
| Permisos | Qué puede hacer la key. Arranca con todo lo que tú puedes otorgar y desde ahí recortas. |
| Expiración | Opcional. Sin fecha, no caduca. |
| Límite de tasa | Opcional, en solicitudes por minuto. Vacío = el valor por defecto. |
Permisos de la key
Una key no tiene rol: la lista que dejes marcada es todo lo que puede hacer. Es la diferencia con un operador, donde el rol es el piso y lo granular suma.
Desmarca todo lo que la integración no necesite. Un ejemplo típico: un BI que solo lee movimientos necesita Reportes › Ver y nada más.
Nunca puedes otorgar un permiso que tú no tengas: el servidor responde No puedes otorgar permisos que tú no tienes.
Los permisos de una key ya emitida se cambian con el botón del escudo de su fila, sin tener que revocarla ni volver a repartir el secreto.
Al crearla, la app muestra el secreto completo con el aviso Copia el secreto ahora. Por seguridad no se volverá a mostrar. Guárdalo en el gestor de secretos de tu sistema. Si se pierde, hay que revocar la key y crear otra.
La tabla
Nombre, prefijo (los primeros caracteres, para identificarla sin ver el secreto), alcance (Cliente (todas las cuentas) o Cuenta), estado (Activa, Revocada, Expirada), límite por minuto, último uso y expiración.
Uso
El botón Uso (📊) de cada fila muestra los últimos 30 días: solicitudes y ancho de banda, con desglose por día, endpoint y estado de respuesta. Sirve para ver si una integración está reintentando de más o recibiendo errores.
Revocar
Revocar deja la key inservible de inmediato y no se puede deshacer. Hazlo si el secreto se filtró, si la integración se retira o si ves uso que no reconoces. La revocación queda en Auditoría.
Buenas prácticas
- Una key por integración, nunca compartida: así puedes revocar una sin tumbar el resto.
- Elige el alcance mínimo que sirva: si la integración es de una sola sede, una key de cuenta; deja la de cliente para lo que de verdad consolide varias.
- Pon expiración en las temporales (pruebas, un proveedor puntual).
- Ajusta el límite de tasa al consumo real del cliente.
- Revisa Uso cada tanto: una key sin uso es una key que se puede revocar.
Errores frecuentes
| Mensaje | Significado |
|---|---|
| API key inválida o revocada | Secreto mal copiado, key revocada o expirada. |
| La API key no tiene alcance para esta acción | La key es de otra cuenta o del recurso pedido. |
| La API key no puede modificar este campo | La key no está autorizada a escribir ahí. |
| Demasiadas solicitudes | Superó su límite por minuto. |