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()

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

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.

Rotació i revocació

• Rota des del dashboard per emetre un secret nou. Tant el secret antic com el nou continuen sent vàlids durant un període de gràcia perquè puguis desplegar el nou sense temps d'inactivitat.
• Revoca per invalidar una clau a l'instant. Qualsevol request posterior amb ella falla amb 401 api_key_revoked. Útil quan sospites d'una filtració.

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.