OAuth2 es el método de autenticación recomendado cuando tu aplicación necesita acceder a múltiples empresas de FacturaDirecta. Permite que los usuarios autoricen tu aplicación sin compartir sus credenciales.

Cuándo usar OAuth2

Usa OAuth2 en estos casos:

Aplicaciones multi-tenant: Tu app permite que múltiples clientes conecten sus cuentas de FacturaDirecta
Integraciones de terceros: Ofreces una integración que los usuarios de FacturaDirecta pueden autorizar
Aplicaciones con login de usuario: Necesitas que el usuario se autentique con su cuenta de FacturaDirecta

Si solo necesitas conectar tu propia empresa, es más sencillo usar una clave de API.

Diferencia con API Key

Característica	API Key	OAuth2
Acceso a empresas	Solo una	Múltiples
Permisos	Definidos en la clave	Definidos por scopes + permisos del usuario
Autenticación de usuario	No requerida	Requerida
Revocación	Eliminando la clave	El usuario puede revocar desde su cuenta
Caso de uso	Integraciones propias	Aplicaciones de terceros

Flujo Authorization Code

FacturaDirecta implementa el flujo OAuth2 Authorization Code. Este es el proceso:

Paso 1: Redirigir al usuario

Envía al usuario a la página de autorización:

https://app.facturadirecta.com/oauth/authorize
  ?client_id=facturadirecta-api
  &response_type=code
  &redirect_uri=https://tu-app.com/callback
  &scope=invoices:read+invoices:write+contacts:read

Parámetros:

client_id: facturadirecta-api (valor fijo)
response_type: code
redirect_uri: URL de tu aplicación donde se enviará el código
scope: Permisos que solicitas (separados por + o espacio)

Paso 2: El usuario autoriza

El usuario inicia sesión en FacturaDirecta (si no lo ha hecho) y ve una pantalla con los permisos que solicitas. Si acepta, FacturaDirecta redirige a tu redirect_uri con un código:

https://tu-app.com/callback?code=abc123xyz

Paso 3: Intercambiar código por token

Tu servidor intercambia el código por un token de acceso:

curl -X POST \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=authorization_code" \
     -d "code=abc123xyz" \
     -d "client_id=facturadirecta-api" \
     -d "redirect_uri=https://tu-app.com/callback" \
     https://app.facturadirecta.com/oauth/token

Respuesta:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2..."
}

Paso 4: Usar el token

Incluye el token en tus llamadas a la API:

curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
     https://app.facturadirecta.com/api/{companyId}/invoices

Obtener las empresas del usuario

Después de autenticar, puedes consultar a qué empresas tiene acceso el usuario:

curl -H "Authorization: Bearer {token}" \
     https://app.facturadirecta.com/api/profile

La respuesta incluye la lista de empresas accesibles con sus IDs.

Renovar el token

Cuando el token expire, usa el refresh token para obtener uno nuevo:

curl -X POST \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=refresh_token" \
     -d "refresh_token=dGhpcyBpcyBhIHJlZnJlc2..." \
     -d "client_id=facturadirecta-api" \
     https://app.facturadirecta.com/oauth/token

Scopes disponibles

Los scopes determinan qué permisos solicitas. Son los mismos que los de las claves de API:

contacts:read, contacts:write
products:read, products:write
invoices:read, invoices:write
estimates:read, estimates:write
deliveryNotes:read, deliveryNotes:write
bills:read, bills:write
payrolls:read, payrolls:write
banks:read, banks:write
accounting:read, accounting:write
settings:read, settings:write

Nota: El acceso efectivo es la intersección entre los scopes solicitados y los permisos que el usuario tiene en la empresa.

💡 Nota: OAuth2 también funciona con los entornos de prueba (sandbox). Los usuarios pueden autorizar tu aplicación en sus sandboxes para que pruebes la integración.

Autenticación OAuth2 para la API