Autenticación

Emitoo usa API keys con prefijo visible y hash en base de datos. Cada key pertenece a tu empresa y lleva sus propios permisos por recurso y método.

Formato de las API keys

Todas las keys empiezan con el prefijo fpk_ seguido de un token aleatorio. El servidor solo guarda el hash (SHA-256) y el prefijo visible (fpk_ + 8 caracteres) para que la identifiques en el panel; la key completa se muestra una sola vez al crearla.

Cómo enviar la key

Hay dos formas equivalentes de autenticar una petición: el header X-API-Key directo, o el header Authorization con esquema ApiKey.

import { Emitoo } from "emitoo";

// El SDK adjunta el header X-API-Key en cada request por ti.
const client = new Emitoo(); // o new Emitoo({ apiKey: "fpk_..." })

const factura = await client.facturas.crear(payload);

from emitoo import EmitooClient

# El SDK adjunta el header X-API-Key en cada request por ti.
client = EmitooClient()  # o EmitooClient(api_key="fpk_...")

factura = client.facturas.crear(payload)

// El SDK adjunta el header X-API-Key en cada request por ti.
client, err := emitoo.New("") // o emitoo.New("fpk_...")
if err != nil {
	log.Fatal(err)
}
ctx := context.Background()

factura, err := client.Facturas.Crear(ctx, payload)

# Equivalentes:
curl https://api.emitoo.io/api/v1/facturas \
  -H "X-API-Key: $EMITOO_API_KEY"

curl https://api.emitoo.io/api/v1/facturas \
  -H "Authorization: ApiKey $EMITOO_API_KEY"

Con los SDKs oficiales no gestionas el header

Los SDKs oficiales (Python, TypeScript y Go) adjuntan el header X-API-Key por ti en cada request. Toman la key del parámetro del constructor o, si lo omites, de la variable de entorno EMITOO_API_KEY.

Bearer es para el panel

Authorization: Bearer … transporta la sesión de usuario del panel web, no API keys. Para integraciones usa siempre X-API-Key o Authorization: ApiKey.

Permisos por recurso

Cada key define qué puede hacer sobre cada recurso de la API pública: facturas, guias_remision, retenciones, personas_empresas, servicios, sucursales y eventos. Por recurso se otorgan métodos (GET, POST, PUT, DELETE) de forma independiente — por ejemplo, una key de tu checkout puede crear facturas pero no borrarlas. Los cambios de permisos se aplican en caliente, sin redeploys.

Alcance de las API keys

Las keys solo acceden a los recursos de la API pública listados arriba. La configuración de la empresa, usuarios, webhooks y workflows se gestionan desde el panel con tu sesión de usuario.

Rate limiting

La API pública limita a 120 requests por minuto por key (ventana deslizante). Si lo excedes, la respuesta es 429 con el header Retry-After en segundos. Diseña tus integraciones con reintentos y backoff exponencial.

Rotación y revocación

Crea, edita y revoca tus keys desde el panel (API Keys). Puedes fijar una fecha de expiración al crearlas y ver su último uso para detectar keys huérfanas. Para rotar: crea la nueva, despliega el cambio, verifica en el panel que la anterior ya no registra uso, y revócala.

Revocación inmediata

Si crees que una key fue comprometida, revócala desde el panel: el efecto es inmediato y global. La key queda inactiva pero su historial de auditoría se conserva.

Auditoría

Cada request autenticado queda registrado con: actor (prefijo de la key), método, recurso, status, IP, user-agent y duración. El histórico está disponible en el panel.