Skip to main content

​
Autenticacion

La API de ZenFlow usa API Keys para autenticar las peticiones. Puedes administrar tus API keys desde el panel de ZenFlow.

​
Obtener una API Key

  1. Inicia sesion en tu Panel de ZenFlow
  2. Navega a Configuracion > API Keys
  3. Haz clic en Crear API Key
  4. Configura tu key:
    • Nombre: Un nombre descriptivo (ej: “Integracion ERP”)
    • Scopes: Selecciona los permisos que tu key necesita
    • Expiracion: Fecha de expiracion opcional
  5. Haz clic en Crear
  6. Copia tu API key inmediatamente - no se mostrara de nuevo
Guarda tu API key de forma segura. Nunca la guardes en control de versiones ni la expongas en codigo del lado del cliente.

​
Usar tu API Key

Incluye tu API key en el header X-API-Key en cada peticion: 
curl -X GET "https://api.zenflow.com.ar/api/v1/orders" \
  -H "X-API-Key: zenflow_live_abc123..."

​
Formato de API Key

Las API keys de ZenFlow siguen este formato: 
zenflow_live_<cadena_aleatoria>
zenflow_test_<cadena_aleatoria>
  • zenflow_live_*: Keys de produccion
  • zenflow_test_*: Keys de prueba/sandbox (proximamente)

​
Scopes (Permisos)

Las API keys tienen permisos especificos. Scopes disponibles:
ScopeDescripcion
read:ordersLeer datos de pedidos
write:ordersCrear y actualizar pedidos
read:productsLeer catalogo de productos
write:productsCrear y actualizar productos
read:stockLeer niveles de inventario
write:stockActualizar inventario
read:webhooksVer configuraciones de webhooks
write:webhooksAdministrar webhooks
adminAcceso completo a todos los recursos

​
Presets de Scopes

Para casos de uso comunes, ofrecemos combinaciones predefinidas:
PresetScopesCaso de Uso
Solo Lecturaread:orders, read:products, read:stockReportes y analiticas
Sync ERPread:orders, write:orders, read:products, read:stock, write:stockIntegracion ERP completa
Sync Stockread:products, read:stock, write:stockSincronizacion de inventario
Acceso TotaladminAcceso administrativo

​
Respuestas de Error

​
API Key Invalida

{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "La API key proporcionada es invalida o ha sido revocada"
  }
}

​
API Key Faltante

{
  "success": false,
  "error": {
    "code": "missing_api_key",
    "message": "Se requiere API key. Incluyela en el header X-API-Key"
  }
}

​
Permisos Insuficientes

{
  "success": false,
  "error": {
    "code": "insufficient_scope",
    "message": "Esta API key no tiene el scope requerido: write:orders"
  }
}

​
API Key Expirada

{
  "success": false,
  "error": {
    "code": "expired_api_key",
    "message": "Esta API key ha expirado"
  }
}

​
Mejores Practicas de Seguridad

Usa Variables de Entorno

Guarda las API keys en variables de entorno, no en codigo

Permisos Minimos

Solo solicita los scopes que realmente necesitas

Rota Regularmente

Rota tus API keys periodicamente

Monitorea Uso

Revisa los logs de uso de API keys para detectar actividad sospechosa

​
Ejemplo: Variables de Entorno

# archivo .env (nunca hagas commit de esto!)
ZENFLOW_API_KEY=zenflow_live_abc123...

// Node.js
const apiKey = process.env.ZENFLOW_API_KEY;

# Python
import os
api_key = os.environ.get('ZENFLOW_API_KEY')

​
Rotar API Keys

Para rotar una API key:
  1. Crea una nueva API key con los mismos scopes
  2. Actualiza tu aplicacion para usar la nueva key
  3. Verifica que la nueva key funciona
  4. Revoca la key antigua
Puedes tener multiples API keys activas. Esto permite rotacion sin tiempo de inactividad.

​
Lista Blanca de IPs (Opcional)

Para seguridad adicional, puedes restringir el uso de API keys a direcciones IP especificas:
  1. Ve a Configuracion > API Keys
  2. Selecciona tu API key
  3. Agrega direcciones IP permitidas o rangos CIDR
  4. Guarda los cambios
{
  "ip_whitelist": ["192.168.1.100", "10.0.0.0/24"]
}

​
Limites de Tasa

Consulta Limites de Tasa para detalles sobre rate limiting de la API.