Autenticació

L'API de Factuarea autentica cada request amb una API key. Les claus són tokens opacs generats al dashboard de desenvolupadors (app.factuarea.com/settings/developers/api-keys) i vinculats a una empresa concreta. Cada request a https://api.factuarea.com/v1/* ha d'incloure una clau vàlida en un dels dos formats admesos.

Format de l'API key

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

Exemple:

fact_live_8KqW3pXnR2VbY7TcA9eFmN5z
fact_test_3pXnR2VbY7TcA9eFmN5z8KqW

• Prefix: determina l'entorn. fact_live_ opera sobre la teva empresa real (producció); fact_test_ opera sobre una empresa sandbox aïllada amb els efectes externs (VeriFactu → AEAT, FACe, emails, webhooks) desactivats. El prefix et permet identificar l'entorn sense descodificar la clau. Consulta Mode de prova i sandbox.
• Secret: 24 caràcters base62 → ~143 bits d'entropia. Es mostra només una vegada en crear-la al dashboard. Si la perds, l'has de rotar.
• Hash a la BD: el backend només emmagatzema el hash bcrypt cost-12 del secret. No hi ha cap manera de recuperar-lo.

Enviar la clau a cada request

L'API accepta dos formats equivalents. Tria el que millor encaixi amb el teu client:

Authorization Bearer (recomanat)

curl https://api.factuarea.com/v1/clients \
  -H "Authorization: Bearer fact_live_8KqW3pXnR2VbY7TcA9eFmN5z"

Capçalera X-API-Key

curl https://api.factuarea.com/v1/clients \
  -H "X-API-Key: fact_live_8KqW3pXnR2VbY7TcA9eFmN5z"

Envia només una de les dues capçaleres. Si totes dues hi són presents, la capçalera Authorization: Bearer té prioritat.

Exemples per llenguatge

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

$response = $client->get('clients?limit=10');
$body = json_decode((string) $response->getBody(), true);

const res = await fetch('https://api.factuarea.com/v1/clients?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/clients',
    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

Per a integracions d'agent i apps de tercers que actuen en nom d'un usuari de Factuarea, l'API també admet el flux OAuth 2.1 authorization-code amb PKCE (code_challenge_method=S256) com a alternativa a una API key estàtica. Els mateixos scopes protegeixen l'access token, i la política de rotació aplica també als secrets de client OAuth.

Les metadades de discovery (RFC 8414) es publiquen a /.well-known/oauth-authorization-server, perquè els clients OAuth resolguin els endpoints d'autorització i token automàticament:

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

L'esquema de seguretat OAuth2 — incloses les URL d'autorització i token i la llista completa de scopes — es descriu a la Referència de l'API.

Scopes

Cada API key es crea amb un o més scopes que limiten quins endpoints pot invocar. Els scopes són cadenes amb la forma <resource>:<action>. El catàleg és tancat: qualsevol scope fora del conjunt llistat provoca invalid_scope en crear la clau.

Clients i catàleg

Documents de venda

Compres i recurrents

Catàlegs i exportació

VeriFactu i FacturaE

Webhooks i esdeveniments

Empreses gestionades (gestoria)

Scopes detallats per al model de gestoria, on un compte mestre gestiona empreses filles i les seves API keys. Només accessibles amb API key (sense equivalent al consentiment OAuth); companies:* requereix a més el mòdul del pla de gestoria.

Super-scope

Si un request usa un endpoint que requereix un scope no concedit a la clau, la resposta és 403 amb type: authorization_error i code: insufficient_scope.

{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_scope",
    "message": "La API key no tiene el scope requerido para esta operación.",
    "request_id": "req_01JBVH7..."
  }
}

Gestió de claus

Les API keys es gestionen des del dashboard de desenvolupadors (app.factuarea.com/settings/developers/api-keys), no a través de l'API pública. Des d'allà pots crear claus, rotar el seu secret, revocar-les, configurar scopes, un expires_at opcional i una llista d'accés per IP.

Les metadades de la clau autenticada (id, name, prefix, scopes, tier, last_used_at, expires_at) es poden llegir via GET /v1/account — però el secret mai es retorna.

Política de rotació

Les API keys i els secrets de client OAuth són credencials de llarga vida i s'han de rotar en un calendari i de seguida després de qualsevol sospita de filtració.

• Els prefixos són la font de veritat de l'entorn: fact_live_ (producció) i fact_test_ (sandbox). No els barregis mai entre entorns.
• Rota des del dashboard (o mitjançant els endpoints self-service account:write) per emetre un secret nou. El nou secret es retorna una sola vegada — desa'l de seguida, no es torna a mostrar.
• Finestra de gràcia (doble secret). Després d'una rotació el secret anterior continua funcionant durant una finestra de gràcia de 24 hores, perquè puguis desplegar el nou secret sense temps d'inactivitat. Durant aquesta finestra s'accepten tant el nou com l'anterior; en expirar la finestra el secret anterior es rebutja i es purga. Un request que continuï usant el secret anterior rep un header 199 Warning que indica quantes hores queden abans que deixi de funcionar.
• Quan rotar: en un calendari regular (p. ex. cada 90 dies), sempre que un membre de l'equip amb accés marxi, i immediatament si un secret queda exposat alguna vegada en logs, control de versions o un client públic.
• Revoca per invalidar una clau permanentment. Qualsevol request posterior amb ella falla amb 401. La revocació no té finestra de gràcia — és instantània i irreversible.

Els secrets estan lligats a una sola empresa (tenant) i no han d'incrustar-se mai en navegadors, apps mòbils ni cap client públic — mantén-los només al servidor.

Llista d'accés per IP

Cada API key es pot restringir a una llista d'IPs o rangs CIDR des del dashboard. Si el request arriba des d'una IP fora de la llista d'accés, la resposta és 401 i l'incident es registra al log d'auditoria. Deixa la llista d'accés buida per permetre qualsevol IP.

Errors d'autenticació

Les fallades relacionades amb l'API key responen amb HTTP 401 (o 403 per a insufficient_scope) i l'embolcall d'error estàndard. El camp code distingeix el cas:

Cada resposta inclou un request_id únic (també a la capçalera X-Request-Id) que pots facilitar a suport en 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"
  }
}

Bones pràctiques

• Mai pugis API keys a repositoris — usa variables d'entorn o un gestor de secrets (AWS Secrets Manager, Doppler, 1Password Service Accounts).
• Crea una clau per integració: facilita rotar i auditar l'accés sense afectar la resta.
• Limita els scopes al mínim necessari. Un script d'exportació només necessita scopes :read concrets.
• Activa la llista d'accés per IP per a integracions servidor a servidor amb IPs estables.
• Configura expires_at per a claus temporals (p. ex. consultories, demos).
• Audita l'ús des del dashboard: Developers > API Keys > Activity mostra IPs, rutes i errors per clau.