Autenticación

Todas las peticiones a la API requieren autenticación mediante una API Key. Esta página explica cómo obtener tu clave y utilizarla en tus peticiones.

Obtener tu API Key

1. Accede a tu cuenta de Beel en app.beel.es
2. Ve a Ajustes → API Keys
3. Haz clic en Crear clave API
4. Selecciona el entorno (sandbox o producción)
5. Dale un nombre descriptivo (ej: "Mi aplicación" o "Integración con ERP")
6. Copia la clave inmediatamente — solo se muestra una vez

Formato de API Key

Ejemplo de clave de sandbox:

beel_sk_test_a1b2c3d4e5f6g7h8

Ejemplo de clave de producción:

beel_sk_live_x9y8z7w6v5u4t3s2

Importante:

• Las claves se muestran solo una vez al crearlas
• Cada clave está vinculada a un entorno específico
• La URL base es la misma (https://app.beel.es/api/v1), la clave determina el entorno

Realizar peticiones autenticadas

Incluye tu API Key en el header X-API-Key de cada petición:

curl https://app.beel.es/api/v1/facturas \
  -H "X-API-Key: beel_sk_xxx"

Ejemplo: Listar facturas

curl https://app.beel.es/api/v1/facturas \
  -H "X-API-Key: beel_sk_test_a1b2c3d4e5f6g7h8"

Ejemplo: Crear una factura

curl -X POST https://app.beel.es/api/v1/facturas \
  -H "X-API-Key: beel_sk_test_a1b2c3d4e5f6g7h8" \
  -H "Content-Type: application/json" \
  -d '{
    "clienteId": "cliente-123",
    "lineas": [
      {
        "descripcion": "Consultoría",
        "cantidad": 1,
        "precio": 100.00
      }
    ]
  }'

Usar variables de entorno

Nunca incluyas tu API Key directamente en el código. Usa variables de entorno:

# Configura la variable de entorno
export BEEL_API_KEY="beel_sk_test_a1b2c3d4e5f6g7h8"

# Úsala en tus peticiones
curl https://app.beel.es/api/v1/facturas \
  -H "X-API-Key: $BEEL_API_KEY"

En Node.js

const apiKey = process.env.BEEL_API_KEY;

const response = await fetch('https://app.beel.es/api/v1/facturas', {
  headers: {
    'X-API-Key': apiKey,
    'Content-Type': 'application/json'
  }
});

En Python

import os
import requests

api_key = os.environ.get('BEEL_API_KEY')

response = requests.get(
    'https://app.beel.es/api/v1/facturas',
    headers={'X-API-Key': api_key}
)

Errores de autenticación

Si la autenticación falla, recibirás una respuesta 401 Unauthorized:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API Key inválida o faltante"
  }
}

Causas comunes:

• Falta el header X-API-Key
• La API Key es incorrecta o tiene un error tipográfico
• La API Key fue eliminada o regenerada
• Estás usando una clave de sandbox para acceder a datos de producción (o viceversa)

Buenas prácticas de seguridad

• Nunca compartas tu API Key públicamente ni la incluyas en repositorios de código
• Usa variables de entorno para almacenar las claves
• Crea claves separadas para diferentes aplicaciones o entornos
• Elimina claves no utilizadas desde el panel de control
• Regenera la clave inmediatamente si sospechas que ha sido comprometida
• Usa claves de sandbox durante el desarrollo y testing

Próximo paso

Ahora que puedes autenticar tus peticiones, explora los endpoints disponibles en la API.