Autenticación

La API de Factuarea autentica cada request con una API key. Las claves son tokens opacos que emite un titular o administrador de la cuenta en el dashboard de desarrolladores (app.factuarea.com/settings/developers/api-keys), o mediante los endpoints v1 self-service. Una clave pertenece a una cuenta, nunca a un solo NIF. Su alcance es su ámbito: los NIF asignados a ella, que pueden ser NIF de la cuenta y NIF de otra cuenta que te deja alcanzarlos. Cada ruta de NIF nombra en su propio path aquel sobre el que opera (/v1/companies/{company}/…), y cada ruta de cuenta nombra tu cuenta (/v1/accounts/{account}/…). GET /v1/me enumera el ámbito —una entrada por NIF, con el id opaco que espera el path y su tax_id—, así que una credencial nunca tiene que adivinar a qué NIF llega. Cada request a https://api.factuarea.com/v1/* debe incluir una clave válida en uno de los dos formatos soportados.

Formato de la API key

fact_live_<24 alphanumeric characters>
fact_test_<24 alphanumeric characters>

Ejemplo:

fact_live_8KqW3pXnR2VbY7TcA9eFmN5z
fact_test_3pXnR2VbY7TcA9eFmN5z8KqW

• Prefijo: determina el entorno. fact_live_ opera sobre tus NIF reales (producción); fact_test_ alcanza solo la empresa sandbox aislada de tu cuenta, con los efectos externos (VeriFactu → AEAT, FACe, emails, webhooks) desactivados. El prefijo te permite identificar el entorno sin decodificar la clave. Consulta Modo de prueba y sandbox.
• Secreto: 24 caracteres base62 → ~143 bits de entropía. Se muestra solo una vez al crearla, en el dashboard o en la respuesta de la API. Si la pierdes, debes rotarla.
• Almacenamiento: el backend solo almacena un hash con clave (HMAC-SHA256) del secreto, nunca el secreto. No hay forma de recuperarlo.

Enviar la clave en cada request

La API acepta dos formatos equivalentes. Elige el que mejor encaje con tu cliente:

Authorization Bearer (recomendado)

curl https://api.factuarea.com/v1/companies/{company}/contacts \
  -H "Authorization: Bearer fact_live_8KqW3pXnR2VbY7TcA9eFmN5z"

Cabecera X-API-Key

curl https://api.factuarea.com/v1/companies/{company}/contacts \
  -H "X-API-Key: fact_live_8KqW3pXnR2VbY7TcA9eFmN5z"

Envía solo una de las dos cabeceras. Si ambas están presentes, la cabecera Authorization: Bearer tiene prioridad.

Ejemplos por lenguaje

$client = new GuzzleHttp\Client([
    'base_uri' => 'https://api.factuarea.com/v1/',
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('FACTUAREA_API_KEY'),
        'Accept' => 'application/json',
    ],
]);

$response = $client->get('companies/{company}/contacts?limit=10');
$body = json_decode((string) $response->getBody(), true);

const res = await fetch('https://api.factuarea.com/v1/companies/{company}/contacts?limit=10', {
  headers: {
    Authorization: `Bearer ${process.env.FACTUAREA_API_KEY}`,
    Accept: 'application/json',
  },
});
const data = await res.json();

import os
import requests

resp = requests.get(
    'https://api.factuarea.com/v1/companies/{company}/contacts',
    params={'limit': 10},
    headers={
        'Authorization': f"Bearer {os.environ['FACTUAREA_API_KEY']}",
        'Accept': 'application/json',
    },
)
resp.raise_for_status()
data = resp.json()

OAuth 2.1

Para integraciones de agente y apps de terceros que actúan en nombre de un usuario de Factuarea, la API también admite el flujo OAuth 2.1 authorization-code con PKCE (code_challenge_method=S256) como alternativa a una API key estática. El catálogo de consentimiento OAuth tiene 73 scopes simples con punto más las macros factuarea.read, factuarea.write y factuarea.full; estos se traducen a los scopes detallados con dos puntos que protegen cada endpoint y tool MCP. La política de rotación aplica también a los secretos de cliente OAuth.

El catálogo de consentimiento incluye price_lists.read/write, facturae.read/write y tax_reports.read/write. La pantalla ofrece solo los scopes solicitados por el cliente, nunca preselecciona los sensibles y el token emitido contiene exactamente el subconjunto aprobado por el usuario. Un scope del catálogo, payroll_exports.write, no se ofrece, porque ninguna tool exige el scope al que se traduce.

Qué alcanza el consentimiento OAuth

El consentimiento concede los datos de negocio de un NIF y nunca la administración de la cuenta. Un scope detallado queda fuera de alcance cuando el catálogo no tiene ningún scope con punto que se traduzca a él, y estos están excluidos a propósito, para que la app de un tercero no pueda obtenerlos aunque el usuario apruebe lo que sea:

Todo lo demás que traduce el catálogo es alcanzable: contactos, catálogo, documentos de venta, compras y facturas recurrentes, informes fiscales, FacturaE, lecturas de VeriFactu, webhooks, automatizaciones y lecturas de jornada, y account:read mediante profile.read. Algunas operaciones quedan fuera de OAuth aunque su scope sea alcanzable, como los webhooks y los registros de peticiones de la cuenta: Tools de MCP muestra el canal de cada tool. Usa una API key para cada scope excluido, también con el servidor MCP. Scopes de MCP lista el catálogo de consentimiento.

Los metadatos de discovery (RFC 8414) se publican en /.well-known/oauth-authorization-server, para que los clientes OAuth resuelvan los endpoints de autorización y token automáticamente:

curl https://api.factuarea.com/.well-known/oauth-authorization-server

El esquema de seguridad OAuth2 — incluidas las URL de autorización y token y la lista completa de scopes — se describe en la Referencia de la API.

Scopes

Cada API key se crea con uno o más scopes que limitan qué endpoints puede invocar. Los scopes son cadenas con la forma <resource>:<action>. El catálogo es cerrado: cualquier scope fuera del conjunto listado falla la validación con 422 invalid_param_value al crear la clave.

El catálogo válido es de solo adición para credenciales existentes, mientras que el subconjunto asignable a una clave nueva sigue la superficie API publicada. Los cuatro scopes reservados de GoCardless/MONEI que aparecen debajo siguen reconociéndose por compatibilidad histórica, pero se omiten de CreateApiKeyV1Request y no pueden asignarse hasta que se publiquen esos proveedores. Después se aplican por separado las restricciones de plan y sandbox mediante scope_not_allowed_by_plan y scope_not_allowed_in_sandbox: un scope se concede solo si el plan de todos los NIF del ámbito de la clave lo permite.

Contactos y catálogo

Cliente y proveedor son dos roles de la misma identidad —el contacto—, así que un solo trío de scopes cubre los dos. Los antiguos clients:* y suppliers:* están retirados y ya no se pueden asignar.

Documentos de venta

Compras y recurrentes

Catálogos y exportación

VeriFactu y FacturaE

Webhooks y eventos

Integraciones y observabilidad

Control horario

Estos scopes requieren el módulo de plan control_horario. Algunos scopes de lectura se pueden conceder por OAuth; las escrituras y transiciones privilegiadas siguen siendo exclusivas de API key.

Tareas y proyectos

projects:* y tasks:* requieren el módulo tasks, que incluyen todos los planes; users:read y notifications:* son transversales. Los scopes projects:delete y tasks:delete son solo de API key: un consentimiento OAuth nunca los concede. Facturar las horas de un proyecto necesita además invoices:write. Consulta Proyectos y tareas.

Cartera de NIF

Scopes detallados para los NIF que tiene tu cuenta. Funcionan sobre /v1/accounts/{account}/companies… y necesitan una API key: el consentimiento nunca los concede. Cualquier cuenta, en cualquier plan, lista y consulta sus propios NIF, así que companies:* no tiene gate de plan. Lo que el plan controla es añadir un NIF que paga la cuenta, y lo hace dentro de la operación (NIF adicionales).

Cartera de NIF describe las operaciones.

Administración de la cuenta

Scopes para lo que tiene la propia cuenta: sus claves, su equipo y su titularidad. Necesitan una API key, salvo account:read, que el consentimiento OAuth concede mediante profile.read. No son privilegiados, así que el super-scope * sí los cubre.

GET /v1/me no necesita ningún scope: cualquier credencial válida puede introspeccionarse. En un plan sin el módulo user_management los scopes members:*, invitations:* y nif_transfers:* no se pueden asignar a una clave, y GET /v1/me lista solo los efectivos. Los planes empresario y enterprise incluyen el módulo.

Las API keys no se gestionan con api_keys:*. Los seis endpoints de /v1/accounts/{account}/api-keys los gobiernan account:read (listar y consultar) y account:write (crear, cambiar los NIF de, rotar el secret y revocar) — consulta API keys y claves acotadas. Cuentas y NIF describe el equipo y los traspasos.

Scopes privilegiados

Dos scopes son privilegiados: accounts:read y accounts:write. Permiten que una cuenta aprovisione, administre y cobre cuentas para sus clientes, lo que describe cuentas gestionadas. Se distinguen de todos los demás scopes:

• Factuarea los concede, cuenta por cuenta. Solo Factuarea puede: la API no tiene ninguna operación que conceda el privilegio. GET /v1/me te dice si tu cuenta lo tiene, en account.is_provider y account.privileged_scopes. No puedes asignártelos: crear una clave que los lista sin el privilegio responde 403 privileged_scope_required y no crea nada.
• Se comprueban en cada petición. La clave debe listar el scope, tu cuenta debe tener hoy el privilegio y la persona que emitió la clave debe seguir siendo titular o administrador de tu cuenta. Si falla cualquiera de las tres, la respuesta es 403 privileged_scope_required, y las dos causas responden igual. Nada sale de una caché: si retiramos el privilegio, o esa persona deja de ser titular o administrador, la misma clave deja de funcionar en su siguiente petición.
• No llegan por OAuth. El consentimiento nunca los concede: usa una API key, también con el servidor MCP.
• Ningún plan los controla. El gate es el privilegio, no el plan.
• * no los cubre. Consulta el super-scope.

Super-scope

Si un request usa un endpoint que requiere un scope no concedido a la clave, la respuesta es 403 con type: authorization_error y code: insufficient_scope.

{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_scope",
    "message": "Esta operación requiere el scope 'account:write'. Tu API key solo tiene los scopes: ninguno.",
    "doc_url": "https://docs.factuarea.com/guides/errors#insufficient_scope",
    "request_id": "req_01JBVH7K9Y4N3CDQ2EHJB1AGSV"
  }
}

Gestión de claves

Las API keys se pueden gestionar desde el dashboard de desarrolladores (app.factuarea.com/settings/developers/api-keys) o mediante los endpoints v1 self-service. Ambas superficies permiten crear, rotar y revocar claves y fijar la lista de acceso por IP al crear una; el dashboard también la edita después. El dashboard es para los titulares y administradores de la cuenta, y las claves que emites nunca llegan a más que tú: quién puede emitir una key lo explica.

Los metadatos de la clave autenticada (id, name, prefix, scopes, tier, environment, last_used_at, expires_at) se pueden leer vía GET /v1/me, junto con los NIF a los que llega la clave — pero el secreto nunca se devuelve.

Política de rotación

Las API keys y los secretos de cliente OAuth son credenciales de larga vida y deben rotarse en un calendario y de inmediato tras cualquier sospecha de filtración.

• Los prefijos son la fuente de verdad del entorno: fact_live_ (producción) y fact_test_ (sandbox). Nunca los mezcles entre entornos.
• Rota desde el dashboard (o mediante los endpoints self-service account:write) para emitir un secreto nuevo. El nuevo secreto se devuelve una sola vez — guárdalo de inmediato, no se vuelve a mostrar.
• Ventana de gracia (doble secreto). Tras una rotación el secreto anterior sigue funcionando durante una ventana de gracia de 24 horas, para que puedas desplegar el nuevo secreto sin tiempo de inactividad. Durante esa ventana se aceptan tanto el nuevo como el anterior; al expirar la ventana el secreto anterior se rechaza y se purga. Un request que siga usando el secreto anterior recibe un header 199 Warning que indica cuántas horas quedan antes de que deje de funcionar.
• Cuándo rotar: en un calendario regular (p. ej. cada 90 días), siempre que un miembro del equipo con acceso se vaya, e inmediatamente si un secreto queda expuesto alguna vez en logs, control de versiones o un cliente público. La rotación deja el secreto anterior válido durante la ventana de gracia de 24 horas, así que, para cortar de golpe un secreto expuesto, revoca la clave en su lugar (la revocación es inmediata) y emite una nueva.
• Revoca para invalidar una clave permanentemente. Cualquier request posterior con ella falla con 401. La revocación no tiene ventana de gracia — es instantánea e irreversible.

Los secretos están ligados a una sola cuenta y alcanzan solo los NIF de su ámbito; nunca deben incrustarse en navegadores, apps móviles ni ningún cliente público — mantenlos solo en el servidor.

Lista de acceso por IP

Cada API key se puede restringir a una lista de IPs o rangos CIDR, desde el dashboard o con ip_allowlist al crear la clave. Si el request llega desde una IP fuera de la lista de acceso, la respuesta es 401 con el código ip_not_allowed y el incidente se registra en el log de auditoría. Deja la lista de acceso vacía para permitir cualquier IP.

Errores de autenticación

Los fallos relacionados con la API key responden con HTTP 401 (o 403 cuando la clave autentica pero no basta) y el envoltorio de error estándar. El campo code distingue el caso:

Cada respuesta incluye un request_id único (también en la cabecera X-Request-Id) que puedes facilitar a soporte al investigar.

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "La API key proporcionada no es válida.",
    "request_id": "req_01JBVH7K9Y4N3CDQ2EHJB1AGSV",
    "doc_url": "https://docs.factuarea.com/guides/errors#invalid_api_key"
  }
}

Buenas prácticas

• Nunca subas API keys a repositorios — usa variables de entorno o un gestor de secretos (AWS Secrets Manager, Doppler, 1Password Service Accounts).
• Crea una clave por integración: facilita rotar y auditar el acceso sin afectar al resto.
• Limita los scopes al mínimo necesario. Un script de exportación solo necesita scopes :read concretos, y a una clave que solo lleva scopes :read le basta con view en sus NIF.
• Da a cada clave solo los NIF que necesita, con scoped_company_ids (claves acotadas).
• Activa la lista de acceso por IP para integraciones servidor a servidor con IPs estables.
• Configura expires_at para claves temporales (p. ej. consultorías, demos).
• Audita el uso desde el dashboard: Developers > API Keys > Activity muestra IPs, rutas y errores por clave.

Credenciales para integraciones

Las operaciones REST y MCP de tiendas requieren una API key con los scopes de tiendas. El consentimiento OAuth no concede estos scopes. Autoriza por separado la conexión del proveedor: una clave de Factuarea no es una credencial de WooCommerce o Shopify. La autenticación MCP también requiere un cliente compatible con la revisión 2026-07-28.