API keys (autoservei)

Més enllà del dashboard de desenvolupador, Factuarea exposa tot el cicle de vida de les API keys del teu compte des de l'API pública v1, perquè aprovisionis i rotis credencials de manera programàtica. Una API key pertany al compte, mai a un dels seus NIF, així que viu a l'eix de compte: sis endpoints sota /v1/accounts/{account}/api-keys cobreixen llistar, crear, recuperar, acotar, rotar el secret i revocar.

{account} és l'id opac del compte al qual pertany la credencial — el llegeixes a account.id de GET /v1/me. Ha de ser el teu propi compte: qualsevol altre valor respon el mateix 404 account_not_found. {api_key} és l'id de la key — un UUID v7 opac, no el seu prefix ni el seu secret. Mira els esquemes complets a la Referència de l'API.

Qui pot emetre una key

Una key l'emet sempre una persona, i el que arriba a fer es mesura contra aquesta persona. Les keys s'emeten en dos llocs:

• El nivell surt de la persona. Un owner i un admin arriben a tots els NIF del compte amb operate. Un member arriba només als NIF en què té un grant, amb el nivell d'aquest grant (rols). Una key pren a cada NIF el nivell de la persona que l'ha emesa, i només baixa.
• Una key emesa per l'API respon davant de dos límits. El seu àmbit no pot superar el de la key que l'emet, i els seus nivells no poden superar el que té avui la persona que hi ha darrere d'aquesta key.
• accounts:read i accounts:write demanen més. Són scopes privilegiats: qui emet ha de ser titular o administrador, i el compte ha de tenir un privilegi que només concedeix Factuarea.

Llista les teves keys

GET /v1/accounts/{account}/api-keys retorna les teves keys amb paginació per cursor. Cada key exposa el seu prefix, scopes, tier, environment i els timestamps del seu cicle de vida — mai el secret. Les keys revocades continuen a la llista, perquè en vegis l'historial.

curl https://api.factuarea.com/v1/accounts/{account}/api-keys \
  -H "Authorization: Bearer fact_live_8KqW3pXnR2VbY7TcA9eFmN5z"

{
  "data": [
    {
      "id": "0190f2b1-1c4e-7a3d-9f10-0a1b2c3d4e5f",
      "object": "api_key",
      "name": "Production sync",
      "prefix": "fact_live_8KqW3pXn",
      "scopes": ["invoices:read", "invoices:write"],
      "tier": "scale",
      "environment": "live",
      "created_at": "2026-06-01T09:30:00Z",
      "last_used_at": "2026-06-23T18:04:11Z",
      "expires_at": null,
      "revoked_at": null,
      "is_active": true,
      "is_revoked": false
    }
  ],
  "has_more": false,
  "next_cursor": null
}

prefix són els primers caràcters de la key — segur de registrar en logs, no autentica. Fes-lo servir per reconèixer una key als teus propis panells sense desar mai el secret.

El llistat, la recuperació, la rotació, la revocació i el canvi d'àmbit treballen sobre les keys l'àmbit complet de les quals cap dins de l'àmbit de la key amb què t'autentiques. Una key que arriba a un NIF al qual la teva no arriba no apareix al teu llistat, i demanar-la respon 404 api_key_not_found.

Crea una key

POST /v1/accounts/{account}/api-keys emet una key nova i retorna el seu secret en text pla exactament un cop. Desa'l en el moment que el reps — no hi ha cap endpoint per tornar-lo a llegir més tard.

curl -X POST https://api.factuarea.com/v1/accounts/{account}/api-keys \
  -H "Authorization: Bearer fact_live_8KqW3pXnR2VbY7TcA9eFmN5z" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Reporting export",
    "scopes": ["invoices:read", "pdfs:read"],
    "scoped_company_ids": [
      "0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e",
      "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01"
    ]
  }'

Resposta (201, amb una capçalera Location que apunta a la key nova):

{
  "data": {
    "id": "0190f2c0-77aa-7b21-8c33-1d2e3f405162",
    "object": "api_key",
    "name": "Reporting export",
    "prefix": "fact_live_1N0Fnyhh",
    "scopes": ["invoices:read", "pdfs:read"],
    "tier": "scale",
    "environment": "live",
    "created_at": "2026-06-24T08:15:00Z",
    "last_used_at": null,
    "expires_at": null,
    "revoked_at": null,
    "is_active": true,
    "is_revoked": false,
    "secret": "fact_live_1N0FnyhhR2VbY7TcA9eFmN5z"
  }
}

Envia una Idempotency-Key perquè un reintent després d'una fallada de xarxa no creï una segona key. La repetició respon el mateix 201 amb secret a null, perquè mai no desem el secret: si no vas rebre la primera resposta, revoca aquesta key i crea'n una de nova.

Cos de la petició

El tier es deriva del pla del teu compte: no es fixa des del cos i no existeix una compra de capacitat independent. Si envies tier, s'ignora.

En crear una key s'apliquen dos topalls, tots dos per tier i tots dos comptats sobre keys actives. max_api_keys_exceeded (422) diu que l'empresa que desa la key ja té les keys que permet el seu pla. portfolio_max_api_keys_exceeded (422) s'aplica quan el teu compte té dos o més NIF reals i es compta sobre totes les keys actives del compte, no per NIF, així que donar d'alta un NIF no el puja. Revocar una key n'allibera la plaça. Límits de peticions descriu els límits d'una cartera.

El camp environment

Cada key pertany a un dels dos environments, fixat en crear-la i visible a l'objecte de la key:

Passa environment: test en crear una key per emetre una credencial de sandbox; omet-lo per a una key live. El prefix reflecteix l'environment, així que els distingeixes sense descodificar la key. Mira Mode de prova i sandbox per saber què es desactiva en test.

curl -X POST https://api.factuarea.com/v1/accounts/{account}/api-keys \
  -H "Authorization: Bearer fact_live_8KqW3pXnR2VbY7TcA9eFmN5z" \
  -H "Content-Type: application/json" \
  -d '{"name": "Integration tests", "scopes": ["invoices:read", "invoices:write"], "environment": "test"}'

Una key fact_test_ pertany al teu compte real — la seva empresa sandbox viu dins d'ell — i això decideix el que pot fer amb les keys:

• Arriba només a la seva sandbox. Declarar scoped_company_ids juntament amb environment: test falla la validació, perquè una key de proves no té cap altre NIF al qual arribar. Una key live tampoc pot dur la sandbox: barrejar-los respon 422 business_rule_violation amb el subcodi nif_scope_environment_mismatch.
• Llegeix el compte com una key live. Llistar i recuperar keys amb una key de proves respon igual que amb una live.
• Mai no escriu. Crear, rotar, revocar o canviar l'àmbit d'una key amb una key de proves respon 403 live_credential_required i no canvia res. Això inclou demanar una key live, i també demanar una altra key de proves: emet les keys de proves amb una key live o a l'aplicació web.

Provar comptes gestionats explica en quins comptes pot escriure una key de proves.

Els NIF als quals arriba una key

L'àmbit d'una key és la llista de NIF als quals arriba, i GET /v1/me l'enumera a scope. Es fixa en crear la key, i el pots canviar després.

• Sense scoped_company_ids la key arriba als mateixos NIF que la key que la crea, mai a més. Es deixen fora els NIF en què la persona que emet no arriba al nivell que demanen els teus scopes.
• Amb scoped_company_ids la key arriba exactament a aquests NIF, i han de cabre a l'àmbit de la key emissora: anomenar-ne un de fora respon 422 business_rule_violation amb el subcodi nif_scope_exceeds_issuer i enumera els NIF que no hi caben, sense crear res. L'àmbit mai no es retalla en silenci.
• Quins NIF es poden anomenar. Els del teu compte, i els que el teu compte assoleix per una relació vigent: un accés cedit o un compte gestionat. Qualsevol altre, i qualsevol identificador que no existeixi, respon el mateix 422 invalid_param_value amb param scoped_company_ids, perquè la resposta no serveixi per fer cens de NIF.

PATCH /v1/accounts/{account}/api-keys/{api_key}/nif-scope substitueix l'àmbit d'una key que ja vas desplegar. scoped_company_ids és la llista resultant completa, no un delta, amb almenys un NIF:

curl -X PATCH \
  https://api.factuarea.com/v1/accounts/{account}/api-keys/0190f2b1-1c4e-7a3d-9f10-0a1b2c3d4e5f/nif-scope \
  -H "Authorization: Bearer fact_live_8KqW3pXnR2VbY7TcA9eFmN5z" \
  -H "Content-Type: application/json" \
  -d '{"scoped_company_ids": ["0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e", "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01"]}'

{
  "data": {
    "id": "0190f2b1-1c4e-7a3d-9f10-0a1b2c3d4e5f",
    "object": "api_key_nif_scope",
    "scope": [
      { "id": "0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e", "tax_id": "B12345674", "name": "Distribuciones Ejemplo SL" },
      { "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01", "tax_id": "B87654323", "name": "Talleres García SL" }
    ]
  }
}

• Només dins del teu àmbit. Només pots canviar una key l'àmbit actual de la qual cap dins del teu, i l'àmbit nou mai no pot superar el teu.
• Els scopes de la key es comproven de nou. Cada scope que duu la key ha d'estar permès pel pla de tots els NIF de la llista nova. Si no, la resposta és 422 scope_not_allowed_by_plan i no canvia res.
• Nivells. Un NIF que es queda conserva el nivell desat a la key, així que canviar l'àmbit mai no el puja. Un NIF que entra pren el nivell de la persona que va emetre la key.
• Mateixes respostes que en crear. S'apliquen els mateixos errors 422, i una key revocada respon 422 api_key_already_revoked. Una key de proves té un àmbit fix, la seva sandbox: qualsevol altra llista respon nif_scope_environment_mismatch.

Claus acotades explica com usar una key que arriba només a una part del compte.

El sostre de nivell per NIF

Cada NIF d'una key té un nivell, view o operate. Es fixa quan el NIF entra a la key, en emetre-la o en canviar-ne l'àmbit, i només baixa. És el menor de tres: el nivell de la relació, quan el NIF és d'un altre compte al qual arribes per un accés cedit o un compte gestionat; el grant de la persona que emet la key; i el rol d'aquesta persona.

• Escriure exigeix operate. Una key amb qualsevol scope que no sigui de lectura (:read), inclòs *, necessita operate a cada NIF que anomena. A una key que només duu scopes :read li basta view.
• Un NIF que la persona que emet només llegeix. Anomenar-lo juntament amb un scope d'escriptura respon 422 business_rule_violation amb el subcodi nif_access_level_exceeds_emitter i no crea res. Si no declares scoped_company_ids, es deixen fora els NIF per sota del nivell necessari, i quan no en queda cap la resposta és el mateix 422.
• Es mesura de nou a cada petició. Compta el menor entre el nivell desat a la key i el nivell que la persona que emet té en aquell moment. Amb view, una escriptura respon 403 company_read_only, i sense cap nivell, el mateix 404 profile_not_found que un NIF fora de l'àmbit.
• Es recalcula a la baixa. Baixar o retirar un grant baixa les keys d'aquella persona, i reduir o acabar un accés entre comptes baixa les keys del compte receptor a la petició següent. Una key que es queda sense cap NIF es revoca. Res no puja per si sol: per obtenir un nivell més alt, emet una key nova.

{
  "error": {
    "type": "invalid_request_error",
    "code": "business_rule_violation",
    "subcode": "nif_access_level_exceeds_emitter",
    "message": "No puedes dar a la credencial más acceso del que tienes. Sin acceso suficiente en: 01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01. Una credencial con permisos de escritura solo alcanza NIF en los que operas.",
    "param": "scoped_company_ids",
    "doc_url": "https://docs.factuarea.com/guides/errors#business_rule_violation",
    "request_id": "req_01J8Y3M2Q40000000000000011"
  }
}

Accés cedit mostra el sostre d'una key en un NIF que un altre compte et deixa assolir, i què passa amb les keys quan aquest accés es redueix o acaba.

Els scopes que pots assignar

scopes pren valors del catàleg tancat d'Autenticació. Un valor fora d'ell falla la validació amb 422 invalid_param_value.

• El pla decideix, NIF a NIF. Un scope es concedeix només si el pla de tots els NIF de l'àmbit el permet, i l'excés mai no es retalla en silenci: respon 422 scope_not_allowed_by_plan. Un mòdul bloquejat en mode de prova respon 422 scope_not_allowed_in_sandbox. Els scopes members:*, invitations:* i nif_transfers:* necessiten el mòdul user_management.
• accounts:read i accounts:write no te'ls pots assignar tu. Són scopes privilegiats: una key els duu només mentre el compte tingui un privilegi que només concedeix Factuarea, i només si la persona que emet la key és titular o administrador. Si no, la creació respon 403 privileged_scope_required i no es crea cap key.
• * no els cobreix. El super-scope cobreix tots els altres scopes. Amb el privilegi pots llistar * i accounts:* junts a la mateixa key.

Comptes gestionats explica què obre el privilegi.

Rota el secret

POST /v1/accounts/{account}/api-keys/{api_key}/rotate-secret genera un prefix + secret nous i retorna el nou secret en text pla exactament un cop. El secret anterior continua funcionant durant una finestra de gràcia de 24 hores perquè puguis desplegar el nou sense downtime. L'environment de la key no canvia.

És irreversible, així que la Idempotency-Key és obligatòria: sense ella la resposta és 422 idempotency_key_required.

curl -X POST \
  https://api.factuarea.com/v1/accounts/{account}/api-keys/0190f2b1-1c4e-7a3d-9f10-0a1b2c3d4e5f/rotate-secret \
  -H "Authorization: Bearer fact_live_8KqW3pXnR2VbY7TcA9eFmN5z" \
  -H "Idempotency-Key: $(uuidgen)"

{
  "data": {
    "id": "0190f2b1-1c4e-7a3d-9f10-0a1b2c3d4e5f",
    "object": "api_key",
    "name": "Production sync",
    "prefix": "fact_live_Zq7mP4xV",
    "scopes": ["invoices:read", "invoices:write"],
    "tier": "scale",
    "environment": "live",
    "created_at": "2026-06-01T09:30:00Z",
    "last_used_at": "2026-06-23T18:04:11Z",
    "expires_at": null,
    "revoked_at": null,
    "is_active": true,
    "is_revoked": false,
    "secret": "fact_live_Zq7mP4xVnR2VbY7TcA9eFmN5z"
  }
}

Revoca una key

POST /v1/accounts/{account}/api-keys/{api_key}/revoke invalida una key de manera permanent. Les peticions posteriors autenticades amb ella fallen amb 401. Un reason opcional (màx 500 caràcters) queda a l'audit log. Igual que la rotació, és irreversible i exigeix una Idempotency-Key.

curl -X POST \
  https://api.factuarea.com/v1/accounts/{account}/api-keys/0190f2b1-1c4e-7a3d-9f10-0a1b2c3d4e5f/revoke \
  -H "Authorization: Bearer fact_live_8KqW3pXnR2VbY7TcA9eFmN5z" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"reason": "Rotated out of the deploy pipeline"}'

Després de la revocació, les peticions amb aquesta key retornen 401 amb el codi api_key_revoked:

{
  "error": {
    "type": "authentication_error",
    "code": "api_key_revoked",
    "message": "Esta API key ha sido revocada.",
    "doc_url": "https://docs.factuarea.com/guides/errors#api_key_revoked",
    "request_id": "req_01JBVH7K9Y4N3CDQ2EHJB1AGSV"
  }
}

El codi és específic perquè el secret encara coincideix: qui l'envia ja té la key. Un secret que no coincideix amb res respon el genèric invalid_api_key, i una key caducada respon api_key_expired.

Scopes i aïllament

Els sis endpoints estan protegits pels scopes d'account:

• account:read — llistar i recuperar keys.
• account:write — crear, canviar l'àmbit de, rotar i revocar keys.

Totes les operacions s'acoten al teu propi compte i, dins d'ell, a l'àmbit de la key amb què t'autentiques. Les respostes no revelen mai el que existeix, i cap és un 403:

• Un {account} que no és teu, no existeix o no és un identificador de compte respon 404 account_not_found.
• L'id d'una key que pertany a un altre compte, no existeix o arriba a un NIF fora del teu àmbit respon 404 api_key_not_found.

Errors

Tools MCP

Les mateixes operacions són tools MCP: list_api_keys, get_api_key, create_api_key, rotate_api_key_secret, revoke_api_key i update_api_key_nif_scope. Les dues lectures també es poden fer servir per OAuth. Les quatre escriptures necessiten una API key, perquè el consentiment OAuth mai no concedeix account:write. Mira Scopes de MCP.

Permisos de botigues

La gestió de botigues fa servir stores:read i stores:write; els scopes del proveïdor són woocommerce_store:read, woocommerce_store:write, shopify_store:read i shopify_store:write. Les proves de connexió requereixen el scope d’escriptura del proveïdor. Aquests scopes s’assignen a API keys i queden fora del consentiment OAuth. Consulta la taula d’operacions de botigues.

Relacionat