Comptes i NIF

El teu compte és el client. Reuneix el pla, les credencials, l'equip i els NIF que facturen. Una credencial pertany a un compte, i el segment {account} de /v1/accounts/{account}/… el nomena. Aquesta guia explica què viu al compte, qui pot fer què a dins, com passa un NIF d'un compte a un altre i com llegir la teva pròpia credencial amb GET /v1/me.

Descriu el compte que operes tu. Els comptes dels teus clients tenen les seves pròpies guies: accés cedit quan un altre compte et deixa arribar a alguns dels seus NIF, i comptes gestionats quan aprovisiones tu mateix el compte del client.

Un compte, diversos NIF

Un NIF pertany com a màxim a un compte. El primer NIF d'un compte és el seu NIF titular: l'empresa titular del compte, que no és un NIF addicional i no es pot cedir. Tots els altres són NIF addicionals: els paga el compte, i el pla que els admet, el seu preu i el seu topall tenen la seva pròpia guia.

Les dades d'un NIF (les seves factures, contactes, sèries i registres de VeriFactu) es queden amb aquest NIF. El compte guarda el que es comparteix: l'equip, les invitacions, la titularitat, les API keys, el consum, la cartera de NIF, els traspassos, els webhooks i els registres de peticions. Cada cosa viu en una ruta diferent:

Els dos segments porten l'id opac (UUID v7), mai el tax_id. Per trobar un NIF pel seu identificador fiscal, filtra GET /v1/accounts/{account}/companies amb tax_id.

Consulta la teva credencial amb GET /v1/me

GET /v1/me et diu qui és la teva credencial, a quin compte pertany i quins NIF arriba a tocar, en una sola crida. No necessita cap scope: qualsevol credencial vàlida es pot consultar a si mateixa. És també la manera com qui té un sol NIF descobreix el seu identificador opac.

curl https://api.factuarea.com/v1/me \
  -H "Authorization: Bearer $FACTUAREA_KEY"

{
  "data": {
    "object": "me",
    "account": {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a00",
      "name": "Asesoría Martínez",
      "environment": "live",
      "is_provider": true,
      "privileged_scopes": [
        "accounts:read",
        "accounts:write"
      ]
    },
    "api_key": {
      "id": "019e81ef-e1d4-7208-a51d-94c2c2a54a84",
      "name": "Producción",
      "prefix": "fact_live_1OSf9KdP",
      "scopes": [
        "account:read",
        "series:read",
        "series:write"
      ],
      "tier": "scale",
      "environment": "live",
      "created_at": "2026-01-15T09:30:00Z",
      "last_used_at": "2026-05-25T18:00:00Z",
      "expires_at": null
    },
    "scope": [
      {
        "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",
        "tax_id": "B12345674",
        "name": "Acme Corporation"
      },
      {
        "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02",
        "tax_id": "B87654323",
        "name": "Acme Logística S.L."
      }
    ],
    "client_accounts": [
      {
        "id": "0199a1f0-1c22-7a10-b111-5a5b5c5d5e5f",
        "name": "Construcciones Ruiz",
        "origin": "granted",
        "access_level": "view",
        "status": "active",
        "paid_by_provider": false,
        "environment": "live"
      },
      {
        "id": "0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f",
        "name": "Talleres García",
        "origin": "provisioned",
        "access_level": "operate",
        "status": "provisioned",
        "paid_by_provider": true,
        "environment": "live"
      }
    ],
    "client_accounts_visible": true,
    "client_accounts_has_more": false
  }
}

GET /v1/me no retorna mai ajustos d'un sol NIF, com la personalització, el pla o els add-ons: són de l'eix de NIF.

Què accepta {account}

Les capacitats de compte (equip, claus, cartera de NIF, traspassos, webhooks) són sempre les del teu propi compte, així que {account} ha de ser el compte de la teva credencial. Un compte que és proveïdor de comptes gestionats arriba també als comptes que gestiona, però només en una llista tancada de rutes que descriu comptes gestionats.

Qualsevol altre valor respon el mateix 404 account_not_found, amb el mateix body i mai un 403: un compte que no és teu, un compte que no existeix i un valor que no és un identificador de compte no es distingeixen. Un 403 diria que el compte existeix, i repetir-lo amb identificadors diferents convertiria la ruta en un cens dels comptes de la plataforma. Un compte que et va cedir accés tampoc no és teu: arribes als seus NIF pel segment {company}, com explica accés cedit.

{
  "error": {
    "type": "not_found_error",
    "code": "account_not_found",
    "message": "La cuenta indicada no existe o no es la de tu credencial.",
    "param": "account",
    "doc_url": "https://docs.factuarea.com/guides/errors#account_not_found",
    "request_id": "req_01J8Y3M2Q40000000000000006"
  }
}

L'eix de NIF es comporta igual. Un {company} que no existeix o que queda fora de l'àmbit de la teva credencial respon 404 profile_not_found, i un NIF en què el teu nivell d'accés és none respon el mateix 404. Quan el teu nivell és view, el NIF és visible però tota escriptura sobre ell respon 403 company_read_only.

Rols i grants

Cada persona del compte és un membre amb un de tres rols. El rol decideix quins NIF arriba a tocar la persona.

Un grant (permís per NIF) és l'accés d'un membre a un NIF, amb el nivell view o operate. Només un membre porta grants. Passar un membre a admin revoca els seus grants, perquè un administrador ja arriba a tot. Cada membre mostra a més un bloc permissions amb el que pot fer en aquest membre qui llegeix la resposta, de manera que dues credencials poden llegir permisos diferents del mateix membre.

L'assessor extern és la persona externa a qui el teu compte pot donar accés: sempre és member, n'hi ha un per compte, en qualsevol pla, amb grants com qualsevol altre membre i sense ocupar plaça. Assessor extern explica com marcar-lo.

Membres

La pertinença és del compte, no d'un NIF. Aquestes són les operacions del recurs de membres:

Les regles que importen en escriure a l'equip:

• Qui pot. La persona que va emetre la credencial ha de ser titular o administradora del compte, amb la secció user_management disponible. Si no, la resposta és 403 forbidden_action.
• Scope de la credencial. Crear un membre i canviar un rol canvien l'equip de tot el compte, així que l'scope de la credencial ha de cobrir tots els NIF del compte. Si no, la resposta és 403 forbidden_action.
• Crear. El body porta name, email, la password inicial, el role (admin o member) i grants. grants és obligatori i pot anar buit; si falta, respon 400 parameter_missing. Els grants sobre un admin responen 422 grants_only_for_member, i un grant sobre un NIF fora del compte o fora de l'scope de la teva credencial respon 422 grant_company_not_in_account. La persona rep un correu per verificar l'adreça. Un correu que ja està registrat respon 422 business_rule_violation: afegeix les persones que ja existeixen amb una invitació.
• Un grant. PUT reemplaça el grant: repetir-lo amb el mateix nivell deixa el mateix estat i no envia res. Baixar un grant baixa també les API keys d'aquest membre. DELETE respon 204 encara que no hi hagués grant. Un grant sobre un owner o un admin respon 422 grants_only_for_member.
• Retirar. DELETE retira la persona de tots els NIF del compte: hi perd els grants i les sessions i les seves API keys perden aquest scope. Per retirar l'accés a un sol NIF, revoca aquest grant. El titular respon 422 member_is_last_owner: traspassa abans la titularitat. Retirar-te a tu mateix respon 422 business_rule_violation. Exigeix una Idempotency-Key.
• Restriccions de mòduls. restrictions és una llista de denegacions de les capacitats access, delete, send i export per secció, que s'aplica sobre el grant. Un objecte buit vol dir cap restricció, mai cap accés, i mai no concedeix més del que concedeix el grant. PATCH reemplaça el conjunt complet.
• Què llegeixes. Es llisten tots els membres, però només es publiquen els grants sobre NIF que la teva credencial llegeix. Un membre desconegut, d'un altre compte o amb un identificador mal format respon el mateix 404 member_not_found.

Dona a un membre operate sobre un NIF:

curl -X PUT "https://api.factuarea.com/v1/accounts/$ACCOUNT_ID/members/$MEMBER_ID/grants/$COMPANY_ID" \
  -H "Authorization: Bearer $FACTUAREA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "level": "operate" }'

{
  "data": {
    "object": "account_member_grant",
    "company_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",
    "level": "operate"
  }
}

Invitacions

Una invitació afegeix al compte una persona que ja existeix a la plataforma, amb un rol i els grants inicials.

• Body. email, role (admin o member), grants (obligatori, pot anar buit, només per a un member) i send_email, que val true per defecte. Crear i reenviar exigeixen una Idempotency-Key.
• El secret es mostra un cop. Amb send_email: false, la resposta porta el secret d'acceptació i l'accept_url exactament un cop, i lliures tu l'enllaç. Amb send_email: true, el secret viatja només al correu i els dos camps van a null. Una repetició idempotent també retorna null, i cap lectura no els retorna.
• Invitacions d'administrador. Convidar un admin exigeix una credencial l'scope de la qual cobreixi tots els NIF del compte, i el mateix val per reenviar-la.
• Estats. pending, accepted, revoked i expired. Revocar mai no retira una persona que ja s'hi ha unit, i una invitació que ja estava acceptada o revocada respon 422 business_rule_violation. Una de caducada respon 422 invitation_expired en reenviar-la: envia'n una de nova.
• Què pot respondre una escriptura. 422 business_rule_violation quan ja existeix una invitació pendent per a aquella adreça, la persona ja és membre, es repeteix un NIF o el compte ha arribat al límit d'usuaris del seu pla; 422 grants_only_for_member i 422 grant_company_not_in_account igual que amb els membres; i 404 invitation_not_found per a una invitació que no existeix o és d'un altre compte.
• L'assessor extern. La seva invitació només s'envia des de l'aplicació web: una invitació creada per l'API no porta mai aquesta marca. Quan la persona ja s'hi ha unit, pots marcar el membre amb PATCH.

curl -X POST "https://api.factuarea.com/v1/accounts/$ACCOUNT_ID/invitations" \
  -H "Authorization: Bearer $FACTUAREA_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
        "email": "laura@acme.example",
        "role": "member",
        "grants": [
          { "company_id": "0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e", "level": "view" }
        ],
        "send_email": false
      }'

Titularitat del compte

El compte té un titular, i és l'única persona que pot traspassar la titularitat. PATCH /v1/accounts/{account}/owner necessita l'scope account:owner, el privilegi més alt del compte, i la persona darrere de la credencial ha de ser el titular actual. Es comprova en cada petició, així que una credencial no conserva el poder si qui la va crear deixa de ser el titular.

curl -X PATCH "https://api.factuarea.com/v1/accounts/$ACCOUNT_ID/owner" \
  -H "Authorization: Bearer $FACTUAREA_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "owner_user_id": "0199a1f0-1c22-7a10-b111-1a1b1c1d1e1f" }'

{
  "data": {
    "account_id": "0199a1f0-1c22-7a10-b111-0a0b0c0d0e0f",
    "object": "account_owner",
    "owner_user_id": "0199a1f0-1c22-7a10-b111-1a1b1c1d1e1f",
    "previous_owner_user_id": "0199a1f0-1c22-7a10-b111-2a2b2c2d2e2f"
  }
}

• El destí. owner_user_id és l'identificador de la persona, no l'id del recurs de membre. El destí ha de ser membre del compte i no pot ser l'assessor extern.
• Què canvia. En una sola transacció, el titular anterior passa a admin i el destí passa a owner. Tots dos conserven l'accés a tots els NIF, i no canvia cap NIF, API key ni pla. Traspassar al titular actual no canvia res.
• Irreversible. Exigeix una Idempotency-Key i, sense ella, respon 422 idempotency_key_required.
• Errors. 403 owner_transfer_forbidden quan qui crida no és el titular actual; no revela qui ho és ni si el destí existeix. 422 invalid_param_value quan falta owner_user_id o està mal format. 422 business_rule_violation quan el destí no existeix, no és membre o és l'assessor extern, els tres amb el mateix body.

El rol del titular no es pot canviar amb PATCH sobre el membre (cannot_change_account_owner_role): la titularitat es traspassa, mai no es reassigna.

Traspassos de NIF

Un NIF passa d'un compte a un altre amb un traspàs de NIF. Sempre l'inicia el compte que l'entrega: cap operació no permet que un compte demani el NIF d'un altre.

curl -X POST "https://api.factuarea.com/v1/accounts/$ACCOUNT_ID/nif-transfers" \
  -H "Authorization: Bearer $FACTUAREA_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
        "company_id": "0199a1f0-1c22-7a10-b111-4a4b4c4d4e4f",
        "recipient_account_id": "0199a1f0-1c22-7a10-b111-5a5b5c5d5e5f"
      }'

{
  "data": {
    "id": "0199a1f0-1c22-7a10-b111-3a3b3c3d3e3f",
    "object": "nif_transfer",
    "company_id": "0199a1f0-1c22-7a10-b111-4a4b4c4d4e4f",
    "expires_at": "2026-10-04T09:00:00+00:00",
    "status": "active",
    "recipient_account_id": "0199a1f0-1c22-7a10-b111-5a5b5c5d5e5f",
    "secret": "<secreto en claro, 48 caracteres>"
  }
}

curl -X POST "https://api.factuarea.com/v1/accounts/$ACCOUNT_ID/nif-transfers/accept" \
  -H "Authorization: Bearer $FACTUAREA_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "secret": "EJEMPLOdeTRASPASOnoVALIDOnoSIRVEparaACEPTARnada0" }'

{
  "data": {
    "id": "0199a1f0-1c22-7a10-b111-3a3b3c3d3e3f",
    "object": "nif_transfer",
    "company_id": "0199a1f0-1c22-7a10-b111-4a4b4c4d4e4f",
    "expires_at": "2026-10-04T09:00:00+00:00",
    "status": "consumed",
    "recipient_account_id": null
  }
}

• Caducitat. Sense expires_at, un traspàs dura 24 hores. Passa expires_at per triar un altre instant futur, fins a 7 dies: un valor passat, massa llunyà o que no es pot interpretar respon 422 business_rule_violation.
• Qui pot. L'empresa titular del compte no es pot cedir. Emetre exigeix un rol administratiu en aquest NIF, i una credencial l'accés de la qual a ell és view respon 403 company_read_only. Un NIF que no existeix, és d'un altre compte o queda fora del teu àmbit respon 404 profile_not_found.
• Irreversible. Emetre, acceptar i revocar exigeixen una Idempotency-Key i, sense ella, responen 422 idempotency_key_required.
• Llistat. Mostra només els traspassos que vas emetre tu i només sobre els NIF que la teva credencial arriba a tocar, mai els que vas rebre. status és active, expired, revoked o consumed: es deriva del rellotge en cada lectura, i hi pots filtrar.
• Què fa l'acceptació. En una sola transacció, i com a màxim un cop fins i tot amb peticions concurrents, el NIF passa al compte receptor juntament amb l'empresa sandbox d'aquest NIF quan el compte que l'entrega la té. Les credencials del compte que entrega el perden del seu àmbit, i les persones d'aquest compte que no pertanyen també al compte receptor en perden l'accés, i es tanquen les seves sessions web i els tokens OAuth lligats a ell.
• El preu de rebre. El NIF que arriba és un NIF addicional del compte receptor, tret que aquest compte es registrés sense NIF: aleshores passa a ser el seu NIF titular i no es cobra. El control s'executa abans de moure res, així que un rebuig deixa el traspàs vigent i el NIF on era: 403 billing_managed_by_provider, 402 additional_nif_plan_required, 403 additional_nif_not_in_plan, 422 business_rule_violation amb el subcodi additional_nif_limit_reached, 402 payment_method_required i 402 additional_nif_charge_failed. En producció i amb subscripció de pagament, el càrrec es fa en acceptar, i es compensa si el trasllat falla després.
• Què pot respondre l'acceptació. 422 nif_transfer_invalid quan el secret no coincideix amb cap traspàs, ja s'ha consumit o s'ha revocat, va adreçat a un altre compte o el seu NIF ja ha canviat de compte. Tots aquests casos comparteixen body a propòsit: distingir-los revelaria si aquell secret ha existit mai. 422 nif_transfer_expired és un codi diferent, perquè qui el té sàpiga que ha de demanar un altre secret. 422 business_rule_violation amb el subcodi account_must_keep_one_nif quan el compte que entrega es quedaria sense cap NIF actiu, i 409 resource_conflict quan un compte registrat sense NIF ja guarda dades de negoci a la seva empresa buida.

L'estat d'un NIF

Cada NIF del compte té un status.

Un NIF active pot passar a inactive o a archived, i un d'inactive pot passar a active o a archived. El compte ha de conservar sempre almenys un NIF active: desactivar o arxivar l'últim active respon 422 business_rule_violation amb el subcodi account_must_keep_one_nif. Arxivar també pot quedar bloquejat per documents fiscals oberts.

Cartera de NIF explica com donar d'alta i editar NIF.

• paid_until. És el final de la cobertura pagada d'un NIF addicional, en ISO 8601. Reactivar el NIF abans d'aquesta data és gratis, i desactivar-lo en conserva la cobertura. Val null quan el NIF no s'ha cobrat mai o la cobertura ha caducat. Només un període nou justifica un càrrec nou, així que reactivar després de caducar la cobertura es cobra com un nou NIF addicional.
• suspension_reason. Diu per què el sistema va suspendre un NIF inactive: payer_blocked quan el compte que paga un compte gestionat té el cobrament bloquejat, i management_ended quan la gestió va acabar abans que ningú assumís el pagament. Val null quan el sistema no suspèn el NIF, per exemple quan l'ha desactivat el mateix compte.
• Qui pot. Donar d'alta, editar, activar, desactivar i arxivar exigeixen un titular o administrador del compte amb la secció user_management disponible: si no, 403 forbidden_action, abans de cobrar o canviar res. Una credencial l'accés de la qual a aquest NIF és view respon 403 company_read_only, i una sense accés respon el mateix 404 que un NIF fora del compte.

Estadístiques per NIF

GET /v1/accounts/{account}/companies/stats retorna una fila company_stats per cada NIF que llegeix la teva credencial, sense els arxivats: invoices_count (factures emeses del període, és a dir, enviades, pagades i vençudes), total_invoiced (una cadena amb dos decimals) i last_invoice, que és l'última factura emesa del NIF sigui quin sigui el període, o null quan encara no n'ha emès cap.

El període és date_from i date_to (YYYY-MM-DD, totes dues opcionals i inclusives). Sense elles és l'any natural en curs, i amb només una de les dues l'altre extrem es queda al mateix any. La llista no es pagina: has_more és sempre false i next_cursor és sempre null. Una data mal formada, o un final anterior a l'inici, respon 422 invalid_param_value.

curl "https://api.factuarea.com/v1/accounts/$ACCOUNT_ID/companies/stats?date_from=2026-01-01&date_to=2026-09-30" \
  -H "Authorization: Bearer $FACTUAREA_KEY"

{
  "data": [
    {
      "object": "company_stats",
      "company_id": "01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c",
      "tax_id": "B12345674",
      "name": "Talleres García SL",
      "invoices_count": 3,
      "total_invoiced": "363.00",
      "last_invoice": {
        "number": "F-2026-003",
        "issued_on": "2026-09-20",
        "total": "121.00"
      }
    },
    {
      "object": "company_stats",
      "company_id": "01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0d",
      "tax_id": "B87654323",
      "name": "Distribuciones Norte SL",
      "invoices_count": 0,
      "total_invoiced": "0.00",
      "last_invoice": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Pot emetre aquest NIF?

GET /v1/accounts/{account}/companies/{company}/issuing-readiness respon si un NIF està a punt per emetre factures. És una lectura fiscal i neutra: can_issue és el veredicte, blockers és la llista de motius llegibles per màquina quan val false, i els altres camps són els senyals amb què es va compondre el veredicte (census_status, has_default_series, fiscal_profile_complete, operable, missing_modules i checked_at). No consulta mai la subscripció, el pla, la quota ni el preu, i no respon mai amb un estat de pagament requerit.

{
  "data": {
    "can_issue": false,
    "blockers": [
      "census_not_identified",
      "no_default_series"
    ],
    "census_status": "not_identified",
    "has_default_series": false,
    "fiscal_profile_complete": true,
    "operable": true,
    "missing_modules": [],
    "checked_at": "2026-05-25T18:00:00+00:00"
  }
}

• Ramifica pel codi. Cada bloqueig és un codi estable, com verifactu_certificate_missing quan VeriFactu està actiu per al NIF i aquest no té un certificat vàlid. Amb el temps es poden afegir motius nous: tracta'n un de desconegut com un bloqueig que no pots resoldre per l'API.
• Al llistat. Afegeix include=readiness a GET /v1/accounts/{account}/companies i cada NIF porta un objecte readiness amb aquest mateix contracte. Qualsevol altre valor d'include respon 422 invalid_param_value.
• Una sola resposta per a cada error. Un NIF que no existeix, és d'un altre compte, queda fora del que llegeix la teva credencial o té un identificador mal format respon el mateix 404 resource_not_found, mai un 403, perquè la resposta no serveixi per fer un cens de NIF per diferència.

Què comparteixen els NIF d'un compte

• Credencials i consum. La majoria dels límits no es comparteixen. El topall de claus (max_api_keys) es compta per NIF, i la quota mensual per clau i NIF efectiu. Només portfolio_max_api_keys, el topall de claus d'un compte que opera una cartera, es compta sobre tot el compte. GET /v1/accounts/{account}/usage informa del consum del compte i el desglossa per NIF sobre el mateix total. Una clau llista i gestiona només les claus l'àmbit de NIF de les quals queda sencer dins del seu, així que una credencial acotada a uns pocs NIF no veu una clau que n'abasta també un altre (qui veu i gestiona una clau). API keys i claus acotades expliquen com acotar una clau a una part dels NIF.
• Límits de cartera. Una credencial opera una cartera quan el seu compte té almenys dos NIF reals. La sandbox del compte no compta: un NIF titular i la seva sandbox no són una cartera. Emetre una credencial per sobre del topall de claus de la cartera respon 422 portfolio_max_api_keys_exceeded. Els límits de peticions d'una cartera (429 portfolio_rate_limit_exceeded i 429 portfolio_monthly_quota_exceeded) funcionen per ara en mode observació (shadow) i encara no rebutgen. Els expliquen els límits de peticions.
• Identitat de correu. Un NIF que no és el titular, perquè el compte el va comprar o el va rebre per traspàs, pren el règim d'un compte nou (account_probation_limit_exceeded) i la comprovació d'identitat del remitent per enviar correu del NIF titular del seu compte. El titular no hereta de ningú. Els NIF d'un compte gestionat hereten del NIF titular del compte del proveïdor mentre duri la gestió, i del seu propi NIF titular quan acaba. Un NIF al qual arribes per accés cedit no hereta res del compte que rep l'accés: la seva confiança continua sent la del NIF titular del seu propi compte. Enviament de documents descriu la comprovació.

Scopes

Cap d'aquests scopes no s'obté per OAuth: el canal OAuth del servidor MCP no arriba a les capacitats de compte, així que fes servir una API key. 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 scopes privilegiats accounts:* que aprovisionen comptes gestionats són una altra família: els descriu comptes gestionats.

Relacionat