Autenticació

L'API de Factuarea autentica cada request amb una API key. Les claus són tokens opacs que emet un titular o administrador del compte al dashboard de desenvolupadors (app.factuarea.com/settings/developers/api-keys), o mitjançant els endpoints v1 self-service. Una clau pertany a un compte, mai a un sol NIF. El seu abast és el seu àmbit: els NIF que té assignats, que poden ser NIF del compte i NIF d'un altre compte que et deixa arribar-hi. Cada ruta de NIF anomena al seu propi path aquell sobre el qual opera (/v1/companies/{company}/…), i cada ruta de compte anomena el teu compte (/v1/accounts/{account}/…). GET /v1/me enumera l'àmbit —una entrada per NIF, amb l'id opac que espera el path i el seu tax_id—, de manera que una credencial mai no ha d'endevinar a quins NIF arriba. 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 els teus NIF reals (producció); fact_test_ arriba només a l'empresa sandbox aïllada del teu compte, 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 o a la resposta de l'API. Si la perds, l'has de rotar.
• Emmagatzematge: el backend només emmagatzema un hash amb clau (HMAC-SHA256) del secret, mai el 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/companies/{company}/contacts \
  -H "Authorization: Bearer fact_live_8KqW3pXnR2VbY7TcA9eFmN5z"

Capçalera X-API-Key

curl https://api.factuarea.com/v1/companies/{company}/contacts \
  -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('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

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. El catàleg de consentiment OAuth té 73 scopes simples amb punt més les macros factuarea.read, factuarea.write i factuarea.full; aquests es tradueixen als scopes detallats amb dos punts que protegeixen cada endpoint i tool MCP. La política de rotació també s'aplica als secrets de client OAuth.

El catàleg de consentiment inclou price_lists.read/write, facturae.read/write i tax_reports.read/write. La pantalla ofereix només els scopes sol·licitats pel client, mai no preselecciona els sensibles i el token emès conté exactament el subconjunt aprovat per l'usuari. Un scope del catàleg, payroll_exports.write, no s'ofereix, perquè cap tool exigeix el scope al qual es tradueix.

Què arriba el consentiment OAuth

El consentiment concedeix les dades de negoci d'un NIF i mai l'administració del compte. Un scope detallat queda fora d'abast quan el catàleg no té cap scope amb punt que es tradueixi a ell, i aquests estan exclosos a propòsit, perquè l'app d'un tercer no els pugui obtenir encara que l'usuari aprovi el que sigui:

Tot el que la resta del catàleg tradueix és assolible: contactes, catàleg, documents de venda, compres i factures recurrents, informes fiscals, FacturaE, lectures de VeriFactu, webhooks, automatitzacions i lectures de jornada, i account:read mitjançant profile.read. Algunes operacions queden fora d'OAuth encara que el seu scope sigui assolible, com els webhooks i els registres de peticions del compte: Tools de MCP mostra el canal de cada tool. Fes servir una API key per a cada scope exclòs, també amb el servidor MCP. Scopes de MCP llista el catàleg de consentiment.

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 falla la validació amb 422 invalid_param_value en crear la clau.

El catàleg vàlid és només additiu per a credencials existents, mentre que el subconjunt assignable a una clau nova segueix la superfície API publicada. Els quatre scopes reservats de GoCardless/MONEI que apareixen a continuació es continuen reconeixent per compatibilitat històrica, però s'ometen de CreateApiKeyV1Request i no es poden assignar fins que es publiquin aquests proveïdors. Després s'apliquen per separat les restriccions de pla i sandbox mitjançant scope_not_allowed_by_plan i scope_not_allowed_in_sandbox: un scope es concedeix només si el pla de tots els NIF de l'àmbit de la clau el permet.

Contactes i catàleg

Client i proveïdor són dos rols de la mateixa identitat —el contacte—, de manera que un sol trio de scopes cobreix tots dos. Els antics clients:* i suppliers:* estan retirats i ja no es poden assignar.

Documents de venda

Compres i recurrents

Catàlegs i exportació

VeriFactu i FacturaE

Webhooks i esdeveniments

Integracions i observabilitat

Control horari

Aquests scopes requereixen el mòdul de pla control_horario. Alguns scopes de lectura es poden concedir per OAuth; les escriptures i transicions privilegiades continuen sent exclusives d'API key.

Tasques i projectes

projects:* i tasks:* requereixen el mòdul tasks, que inclouen tots els plans; users:read i notifications:* són transversals. Els scopes projects:delete i tasks:delete són només d'API key: un consentiment OAuth mai no els concedeix. Facturar les hores d'un projecte necessita a més invoices:write. Consulta Projectes i tasques.

Cartera de NIF

Scopes detallats per als NIF que té el teu compte. Funcionen sobre /v1/accounts/{account}/companies… i necessiten una API key: el consentiment mai no els concedeix. Qualsevol compte, en qualsevol pla, llista i consulta els seus propis NIF, així que companies:* no té gate de pla. El que el pla controla és afegir un NIF que paga el compte, i ho fa dins de l'operació (NIF addicionals).

Cartera de NIF descriu les operacions.

Administració del compte

Scopes per al que té el propi compte: les seves claus, el seu equip i la seva titularitat. Necessiten una API key, tret d'account:read, que el consentiment OAuth concedeix mitjançant profile.read. No són privilegiats, així que el super-scope * sí que els cobreix.

GET /v1/me no necessita cap scope: qualsevol credencial vàlida es pot introspeccionar. En un pla sense el mòdul user_management els scopes members:*, invitations:* i nif_transfers:* no es poden assignar a una clau, i GET /v1/me llista només els efectius. Els plans empresario i enterprise inclouen el mòdul.

Les API keys no es gestionen amb api_keys:*. Els sis endpoints de /v1/accounts/{account}/api-keys els governen account:read (llistar i consultar) i account:write (crear, canviar els NIF de, rotar el secret i revocar) — consulta API keys i claus acotades. Comptes i NIF descriu l'equip i els traspassos.

Scopes privilegiats

Dos scopes són privilegiats: accounts:read i accounts:write. Permeten que un compte aprovisioni, administri i cobri comptes per als seus clients, cosa que descriu comptes gestionats. Es distingeixen de tots els altres scopes:

• Factuarea els concedeix, compte per compte. Només Factuarea pot: l'API no té cap operació que concedeixi el privilegi. GET /v1/me et diu si el teu compte el té, a account.is_provider i account.privileged_scopes. No te'ls pots assignar: crear una clau que els llista sense el privilegi respon 403 privileged_scope_required i no crea res.
• Es comproven a cada petició. La clau ha de llistar el scope, el teu compte ha de tenir avui el privilegi i la persona que va emetre la clau ha de continuar sent titular o administrador del teu compte. Si falla qualsevol de les tres, la resposta és 403 privileged_scope_required, i les dues causes responen igual. Res no surt d'una memòria cau: si retirem el privilegi, o aquesta persona deixa de ser titular o administrador, la mateixa clau deixa de funcionar a la petició següent.
• No arriben per OAuth. El consentiment mai no els concedeix: fes servir una API key, també amb el servidor MCP.
• Cap pla els controla. El gate és el privilegi, no el pla.
• * no els cobreix. Consulta el super-scope.

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": "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ó de claus

Les API keys es poden gestionar des del dashboard de desenvolupadors (app.factuarea.com/settings/developers/api-keys) o mitjançant els endpoints v1 self-service. Ambdues superfícies permeten crear, rotar i revocar claus i fixar la llista d'accés per IP en crear-ne una; el dashboard també l'edita després. El dashboard és per als titulars i administradors del compte, i les claus que emets mai no arriben a més que tu: qui pot emetre una key ho explica.

Les metadades de la clau autenticada (id, name, prefix, scopes, tier, environment, last_used_at, expires_at) es poden llegir via GET /v1/me, juntament amb els NIF a què arriba la clau — 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. La rotació deixa el secret anterior vàlid durant la finestra de gràcia de 24 hores, així que, per tallar de cop un secret exposat, revoca la clau en lloc seu (la revocació és immediata) i emet-ne una de nova.
• 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 un sol compte i arriben només als NIF del seu àmbit; no s'han d'incrustar 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 o amb ip_allowlist en crear la clau. Si el request arriba des d'una IP fora de la llista d'accés, la resposta és 401 amb el codi ip_not_allowed 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 quan la clau autentica però no n'hi ha prou) 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, i a una clau que només duu scopes :read li basta view als seus NIF.
• Dona a cada clau només els NIF que necessita, amb scoped_company_ids (claus acotades).
• 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.

Credencials per a integracions

Les operacions REST i MCP de botigues requereixen una API key amb els scopes de botigues. El consentiment OAuth no concedeix aquests scopes. Autoritza per separat la connexió del proveïdor: una clau de Factuarea no és una credencial de WooCommerce o Shopify. L’autenticació MCP també requereix un client compatible amb la revisió 2026-07-28.