API Keys y Credenciales

Fenicia ofrece herramientas para desarrolladores y usuarios técnicos que necesitan acceso programático a la plataforma o que requieren almacenar credenciales de servicios externos de forma segura.

API Keys

Las API keys te permiten autenticarte con la API de Fenicia desde aplicaciones externas, scripts de automatización o integraciones personalizadas.

Solo el propietario de la cuenta puede gestionar API keys

Hoy la creación, el listado, la revocación y la eliminación de API keys están reservadas al propietario (owner) del tenant. Un miembro con rol de administrador o gerente no puede gestionarlas, aunque tenga permisos amplios de configuración. Si necesitas que alguien más lo haga, tendrá que hacerlo el propietario de la cuenta.

Generar una API Key

Acceder a la sección

Ve a Configuración → API Keys y haz clic en Generar nueva key.

Nombrar la key y elegir sus permisos

Asigna un nombre descriptivo que identifique el uso de la key (ej. "Integración ERP", "Script de sincronización") y marca los permisos que necesita: para cada recurso seleccionas qué acciones puede realizar. Ver Permisos de una API key más abajo.

Copiar la key

La key se muestra una sola vez, al momento de crearla. Cópiala y guárdala en un lugar seguro: no podrás volver a verla desde el panel.

La key generada tiene el prefijo fkapi_ y se envía en cada petición como Bearer token:

Authorization: Bearer fkapi_1m8x2z9k_3f9a1c2d4e5f6789abcd0123ef456789

Seguridad de API Keys

Las API keys otorgan acceso a tu cuenta. Nunca compartas una key en repositorios públicos, correos electrónicos o canales no seguros. Si sospechas que una key fue comprometida, revócala inmediatamente.

Límite de 10 keys activas

Cada cuenta admite un máximo de 10 API keys activas. Si llegas al límite, revoca o elimina las que ya no uses antes de generar una nueva.

Permisos de una API key

Los permisos de una key se definen por recurso y, dentro de cada recurso, por las acciones que puede realizar (por ejemplo: leer pedidos, pero no cancelarlos).

Los recursos que puedes seleccionar al crear una key desde el panel son: productos, pedidos, clientes, canales, inventario y reportes, además de la opción de acceso total.

Tip

Otorga a cada key el mínimo indispensable. Una integración que solo lee inventario no necesita permisos de escritura sobre pedidos: si esa key se filtra, el daño posible es mucho menor.

Para el detalle técnico de cómo se evalúan estos permisos al llamar a la API —incluidos los comodines y el formato recurso:acción— consulta Permisos y scopes en la referencia de API.

Gestionar API Keys

Desde el panel de API keys puedes:

Acción	Qué hace
Ver keys activas	Lista de todas las keys generadas, con su fecha de creación y su último uso
Revocar key	Desactiva la key: deja de funcionar de inmediato, pero el registro se conserva en el historial
Eliminar key	Borra el registro por completo

Revocar y eliminar no son lo mismo

Revocar desactiva la key conservando su registro, útil para auditoría: sabes que existió, quién la creó y cuándo se usó por última vez. Eliminar borra el registro definitivamente. En ambos casos la key deja de funcionar al instante y no hay forma de reactivarla desde el panel: si te equivocas, tendrás que generar una nueva y actualizar tu integración.

No existe un botón de «regenerar»

Para rotar una key, el procedimiento es manual y en este orden: genera una key nueva, actualiza tu integración para que use la nueva, verifica que funcione y solo entonces revoca la anterior. Así evitas una ventana de tiempo sin servicio.

Tip

Revisa periódicamente tus API keys activas y revoca las que ya no estén en uso. La columna de último uso te ayuda a detectar keys olvidadas.

Credenciales de Terceros

Además de las API keys —que sirven para que otros sistemas entren a Fenicia— existe un almacén de credenciales para el caso contrario: que Fenicia llame a un servicio externo desde un paso HTTP de una automatización.

Estas credenciales viven en Automatizaciones

El almacén de credenciales pertenece al motor de automatizaciones y se administra desde esa sección, no desde Configuración. Se usa para autenticar los pasos HTTP de tus flujos automatizados.

Tipos de Credenciales

Tipo	Descripción	Ejemplo
API Key	Clave simple de autenticación	Servicios de envío, pasarelas de pago
OAuth2	Autenticación con token de acceso y refresh	Marketplaces, redes sociales
Bearer Token	Token de portador para APIs REST	Servicios de análisis
Basic Auth	Usuario y contraseña codificados	Sistemas legacy, ERPs
Custom Headers	Headers personalizados de autenticación	APIs propietarias

Agregar Credenciales

Seleccionar tipo

Desde la sección de automatizaciones, abre el almacén de credenciales y selecciona el tipo que necesitas guardar.

Ingresar datos

Completa los campos requeridos según el tipo: clave, secreto, URL de token, etc.

Probar conexión

Usa el botón Probar para verificar que las credenciales son válidas antes de guardar.

Guardar

Las credenciales quedan almacenadas y se usan únicamente en los pasos de automatización que las referencien.

Validar Credenciales

La función de validación te permite probar unas credenciales sin ejecutar una operación completa:

Estado verde — credenciales válidas y conexión exitosa
Estado rojo — credenciales inválidas o servicio no disponible
Estado amarillo — credenciales próximas a expirar (OAuth2)

Renovación automática

Para credenciales de tipo OAuth2, Fenicia intenta renovar automáticamente los tokens de acceso antes de que expiren. Si la renovación falla, recibirás una notificación para re-autorizar el servicio.

Automatización

Las API keys y credenciales habilitan flujos de automatización como:

Sincronización de inventario con sistemas ERP
Importación automática de pedidos desde canales personalizados
Generación programática de reportes

Buenas Prácticas de Seguridad

Genera una key diferente para cada integración o servicio: así puedes revocar una sin afectar a las demás
Otorga a cada key el mínimo de permisos que necesite
Rota las keys periódicamente con el procedimiento de arriba (crear → migrar → revocar)
Revisa la columna de último uso para detectar keys olvidadas
Revoca inmediatamente cualquier key comprometida