La API pública de FacturaDirecta soporta dos métodos de autenticación, OAuth2 y API key. Cada operación acepta ambos; tú eliges el que mejor encaje con tu integración. Ambos comparten los mismos scopes y operan sobre el mismo conjunto de endpoints.

Todas las URLs de la API pública en producción tienen el prefijo:

A partir de ahí, los paths que se documentan en cada recurso (por ejemplo /{companyId}/contacts) se concatenan a esta base.

Recursos auxiliares:

Recomendado cuando un usuario conecta su propia empresa de FacturaDirecta a tu aplicación. Tú obtienes un token en su nombre y operas dentro de su empresa.

FacturaDirecta usa Keycloak como servicio de autorización, con realm facturadirecta. El flujo es authorizationCode estándar:

URLs del servicio de autorización en producción:

La fuente autoritativa es el openapi.json público en https://app.facturadirecta.com/openapi.json, sección components.securitySchemes.oAuth.flows.authorizationCode.

client_id para integraciones externas es facturadirecta-api y no requiere client_secret.

La API pública solo acepta tokens emitidos para clientes OAuth autorizados por FacturaDirecta. Los clientes gestionados por FacturaDirecta para integraciones propias, como conectores MCP autorizados, pueden usar su propio client_id, pero siguen sujetos a los scopes del token. Un token válido del realm no basta si el cliente OAuth que lo emitió no está autorizado para la API pública.

offline_access como scope te permite obtener un refresh_token para operar sin nueva intervención del usuario.

Si tu integración solo necesita acceder a una empresa concreta que tú administras, puedes generar una API key desde Ajustes > Integraciones en la propia empresa de FacturaDirecta, o crearla por API desde POST /apiKeys.

Al crear una API key le asignas los scopes que va a poder usar (los mismos que están disponibles para OAuth2, salvo offline_access que para una API key no tiene sentido).

Formato: <prefijo de 6 caracteres>.<sufijo de 32 caracteres>. Es lo que devuelve POST /apiKeys en el campo apiKey de la respuesta (solo visible en la creación; tras eso, FacturaDirecta solo conserva el hash). La API key se envía como header propio, no como Authorization: Bearer.

Todas las peticiones aceptan el header accept-version con el número de versión de la API. Si no lo envías, se usa la versión por defecto definida por el servidor. Para producción se recomienda fijarlo explícitamente:

Cada operación de la API declara los scopes que requiere. Los scopes siguen el patrón <recurso>:<acción>:

El conjunto exacto de scopes y su descripción está en el openapi público y en cada página de recurso de esta documentación. Pide siempre los scopes mínimos necesarios para la integración.

Dos scopes se salen del patrón y conviene conocerlos:

Los documentos del Módulo Inventario tienen sus propios scopes: clientOrders:read y clientOrders:write para pedidos, y purchaseOrders:read y purchaseOrders:write para órdenes de compra. Tener el scope no basta: si el plan de la empresa no incluye esos documentos, las escrituras responden 403. Las operaciones de stock de productos siguen usando products:read y products:write, y también dependen de que el plan incluya el control de stock.

Cada empresa tiene un límite de peticiones por minuto que depende de su plan. El límite se cuenta por empresa (no por credencial) en ventanas de un minuto naturales, y solo se aplica al tráfico de integración: llamadas con API key y con clientes OAuth de integración.

Esos son los valores de la familia de planes vigente. Algunas cuentas con planes anteriores o con condiciones particulares tienen otro límite: no lo supongas a partir del plan, léelo de la cabecera de la respuesta.

Cada respuesta incluye estas cabeceras:

Cuando una petición supera el límite, la respuesta añade además Retry-After con los segundos que faltan para la ventana siguiente. Hoy esa petición se sigue atendiendo: el exceso queda registrado pero no se rechaza. Aun así, diseña la integración para respetar el límite —lee X-RateLimit-Remaining y espacia las llamadas— y para tratar un 429 Too Many Requests con reintento tras Retry-After.

Para el formato general de errores ver Errores y validaciones.