Claves API

Las claves API te permiten acceder a la API de Fynex desde sistemas externos de forma segura, sin necesidad de un usuario interactivo. Cada clave tiene un nombre, scopes que controlan los permisos y un vencimiento opcional.

Crear una clave API

1. Andá a Configuración > Integraciones.
2. En la sección Claves API, hacé clic en Crear clave.
3. Ingresá un nombre descriptivo (ej.: "Sync ERP producción").
4. Seleccioná los scopes que necesita la clave.
5. Opcionalmente, configurá una fecha de vencimiento.
6. Hacé clic en Crear.

WARNING

La clave completa se muestra una sola vez después de crearla. Copiala y guardala en un lugar seguro. Si la perdés, tenés que revocarla y crear una nueva.

Scopes disponibles

Scope	Descripción
accounts:read	Leer cuentas y sus datos asociados
accounts:write	Crear y actualizar cuentas (incluye lectura)
contacts:read	Leer datos de contactos
contacts:write	Crear y actualizar contactos (incluye lectura)
payments:write	Registrar pagos contra cuentas
import	Importar cuentas de forma masiva
export	Exportar datos de cuentas en JSON o CSV
webhooks:manage	Crear, listar, actualizar y eliminar suscripciones webhook

TIP

El scope write incluye automáticamente permisos de read para el mismo recurso. Si asignás accounts:write, no necesitás agregar accounts:read.

Cómo usar la clave

Incluí la clave en el header X-API-Key de cada petición HTTP:

curl -X GET https://api.fynex.solutions/api/v1/accounts \
  -H "X-API-Key: fynex_pk_a1b2c3d4..."

La API también acepta autenticación por JWT (Authorization: Bearer <token>). Si ambos headers están presentes, se usa la clave API.

Formato de la clave

Las claves de Fynex tienen el prefijo fynex_pk_ seguido de 64 caracteres hexadecimales. Solo se almacena un hash SHA-256 de la clave en la base de datos — la clave original no se puede recuperar.

Límites de tasa

Las peticiones autenticadas con clave API están sujetas a un límite de 100 peticiones cada 15 minutos. Si excedés el límite, la API responde con 429 Too Many Requests. Esperá a que se reinicie la ventana de 15 minutos antes de reintentar.

Revocar una clave

1. Andá a Configuración > Integraciones.
2. Buscá la clave en la lista y hacé clic en Revocar.
3. Confirmá la acción.

La clave deja de funcionar inmediatamente. Las peticiones con esa clave van a recibir 401 Unauthorized.

Buenas prácticas

• Una clave por integración — Creá claves separadas para cada sistema que se conecte. Si uno se compromete, podés revocar solo esa clave.
• Mínimo privilegio — Asigná solo los scopes que la integración necesita. Un cron que solo importa cuentas no necesita export ni webhooks:manage.
• Rotá las claves periódicamente — Usá la fecha de vencimiento para forzar rotación. Creá la nueva clave antes de revocar la anterior para evitar interrupciones.
• Nunca expongas claves en el frontend — Las claves API son para uso servidor-a-servidor. Nunca las incluyas en código JavaScript del navegador ni en repositorios públicos.
• Monitoreá el uso — Revisá la columna "Último uso" para detectar claves inactivas o actividad sospechosa.