Modelo de cuentas

30 de septiembre de 2026 — en Factuarea la cuenta pasa a ser el cliente. Reúne el plan, las credenciales, el equipo y los NIF que facturan. Puede dar a otra cuenta acceso a algunos de esos NIF, y una plataforma puede aprovisionar por API cuentas para sus propios clientes. Esta página recoge lo que añade ese modelo y lo que renombra, tema por tema, con la guía que explica cada uno. Las operaciones que añade o cambia van en tablas al final.

Miembros y grants

El equipo ahora pertenece a la cuenta, no a un NIF. Un miembro lleva un role de cuenta (owner, admin o member), la marca external_advisor, una lista de grants y un bloque permissions que dice qué puede hacer quien lee sobre ese miembro. Un grant (permiso por NIF) es el acceso de un member a un NIF, con el nivel view (solo lectura) u operate. Un owner o un admin alcanza todos los NIF sin grants.

• Operaciones nuevas. GET /v1/accounts/{account}/members/{member} y las cuatro operaciones sobre un grant, bajo /v1/accounts/{account}/members/{member}/grants: listar, consultar, fijar con PUT y revocar.
• Operaciones cambiadas. Crear un miembro recibe grants en lugar de company_id. PATCH /v1/accounts/{account}/members/{member} cambia el role, la marca external_advisor o ambos, y pasar un miembro a admin revoca sus grants.
• Códigos nuevos. grants_only_for_member, grant_company_not_in_account y external_advisor_already_assigned, todos 422.
• Scopes y plan. members:read y members:write necesitan el módulo user_management, y members:* e invitations:* no se conceden nunca por OAuth. Una clave fact_test_ lee la cuenta como una clave de producción, pero las escrituras que cambian la cuenta responden 403 live_credential_required.

El asesor externo es la persona externa a la que una cuenta puede dar acceso, en cualquier plan: siempre es member, hay uno por cuenta y no ocupa plaza. Asesor externo explica cómo marcarlo, y Cuentas y NIF cubre todo el equipo.

Invitaciones de cuenta

Una invitación añade una persona a la cuenta con un rol y los grants con los que empieza, en lugar de nombrar un solo NIF.

• Cuerpo y recurso. POST /v1/accounts/{account}/invitations recibe email, role (admin o member), grants y send_email (true por defecto) en lugar de company_id. La invitación lleva ahora grants, send_email y external_advisor.
• Operación nueva. GET /v1/accounts/{account}/invitations/{invitation} lee una invitación.
• El secreto se muestra una vez. Con send_email: false la respuesta lleva el secret de aceptación y el accept_url exactamente una vez. Cuando el correo entrega el enlace, los dos valen null, y también en una repetición idempotente.
• Reenvío. POST …/invitations/{invitation}/resend emite un secreto nuevo y ahora responde 200 con la invitación, donde antes respondía 204.
• La invitación del asesor se envía solo desde la aplicación web. Por API marcas al miembro después.

Invitaciones recoge los estados y los errores de cada escritura.

Titularidad

La cuenta tiene exactamente un owner. La titularidad se traspasa solo con PATCH /v1/accounts/{account}/owner: exige el scope account:owner, la persona que hay detrás de la credencial tiene que ser el titular actual y es irreversible, así que pide una Idempotency-Key. El titular anterior pasa a admin. Los dos conservan todos los NIF, y no cambia ningún NIF, API key ni plan.

El rol del titular no se cambia con la operación de miembros, y el titular no se puede retirar de la cuenta (member_is_last_owner): traspasa antes la titularidad. El evento account.owner_transferred anuncia el cambio a tus webhooks de cuenta. Titularidad de la cuenta da los detalles.

Traspasos de NIF

Un NIF cambia de cuenta con un traspaso de NIF, que sustituye al «claim token» del contrato anterior. Siempre lo inicia la cuenta que entrega el NIF.

• Emitir. POST /v1/accounts/{account}/nif-transfers nombra el NIF en company_id y devuelve el secret exactamente una vez. Un traspaso dura 24 horas, o el expires_at que elijas, hasta 7 días.
• Aceptar. La cuenta receptora llama a POST …/nif-transfers/accept con el secret.
• Revocar. POST …/nif-transfers/{nif_transfer}/revoke es nueva: cancela un traspaso que nadie aceptó. GET …/nif-transfers lista los que emitiste.
• Contrato. Emitir, aceptar y revocar son irreversibles y exigen una Idempotency-Key. Los scopes son nif_transfers:read y nif_transfers:write, los códigos son nif_transfer_invalid y nif_transfer_expired, y las cuatro herramientas son create_nif_transfer, list_nif_transfers, accept_nif_transfer y revoke_nif_transfer.
• El precio de recibir. Una cuenta que ya tiene NIF titular recibe el NIF como NIF adicional. La comprobación se hace antes de mover nada.

La palabra reclamación pertenece ahora solo a las cuentas gestionadas. Traspasos de NIF recorre el flujo.

Cartera de NIF, ciclo de vida y NIF adicional

Los NIF de una cuenta forman su cartera. Cada uno que se suma al NIF titular es un NIF adicional.

• Estadísticas. GET /v1/accounts/{account}/companies/stats devuelve una fila por NIF con invoices_count, total_invoiced (una cadena con dos decimales) y last_invoice, para el periodo que pases en date_from y date_to, o el año natural en curso.
• El recurso del NIF. paid_until es el nombre nuevo del campo de cobertura pagada del NIF (mira Renombrados), y suspension_reason y readiness son nuevos. include=readiness añade la aptitud de emisión al listado, con el mismo contrato que issuing-readiness: can_issue y una lista de blockers. verifactu_certificate_missing es uno de esos bloqueos, no un código de error.
• Ciclo de vida. Un NIF está active, inactive o archived. DELETE lo archiva y nunca cobra. La cuenta debe conservar siempre un NIF activo, así que desactivar o archivar el último responde 422 business_rule_violation con el subcódigo account_must_keep_one_nif.
• El NIF adicional. Cada NIF además del titular es un NIF adicional que paga la cuenta. Necesita el plan empresario o enterprise, el trial incluido, y en producción con una suscripción de pago se cobra al momento. El tope de contrato max_additional_nifs responde 422 business_rule_violation con el subcódigo additional_nif_limit_reached, y seat-charge-preview enseña el cargo antes de confirmar.
• Los códigos de la comprobación. additional_nif_plan_required y additional_nif_charge_failed son 402. additional_nif_not_in_plan y billing_managed_by_provider son 403.
• Scopes. companies:read, companies:write y companies:delete funcionan ahora en cualquier plan. El plan se comprueba dentro de la operación que añade un NIF.
• Facturación. GET /v1/companies/{company}/billing conserva el bloque gestoria_seats con su nombre, y ahora describe la suscripción de NIF adicionales. Sus importes son euros en cadenas con dos decimales: la descripción anterior decía céntimos enteros.
• El 409 del alta. POST /v1/accounts/{account}/companies documenta 409 resource_already_exists con el subcódigo managed_company_tax_id_already_exists, y su ejemplo dice ahora Ya existe una empresa con ese NIF/CIF/NIE en la cuenta.

Cartera de NIF y NIF adicionales cubren el alta, el cobro y la reactivación, y el estado de un NIF cubre el ciclo de vida.

Cuentas gestionadas y aprovisionamiento

Un proveedor de cuentas ya puede crear cuentas para sus propios clientes. Una cuenta gestionada es una cuenta normal y separada, con su propio NIF titular y su propio plan. Pasa de provisioned a claimed y después a active, y el cliente se convierte en su owner al reclamarla con un vale. El proveedor conserva el nivel que tenía.

• Operaciones. POST /v1/accounts aprovisiona, GET /v1/accounts y GET /v1/accounts/{account} leen, PATCH …/access-level cambia el nivel del proveedor, DELETE …/management termina la gestión, POST …/claim-tokens reemite el vale, PATCH …/plan y GET …/plan/preview cambian y previsualizan el plan, y GET …/provisioning-usage lee el consumo.
• Scopes privilegiados. accounts:read y accounts:write son privilegiados: el scope * no los cubre, OAuth no los concede nunca, y la cuenta necesita el privilegio de proveedor que GET /v1/me muestra en is_provider y privileged_scopes. Sin él la respuesta es 403 privileged_scope_required.
• Idempotencia y vale. Aprovisionar es irreversible y exige una Idempotency-Key. external_ref es tu referencia: hace la llamada idempotente y es única en los dos entornos. El claim_token y el claim_url vuelven exactamente una vez, o solo por correo con send_email: true.
• Niveles. El proveedor conserva none, view u operate. Puede subir el nivel solo antes de que el cliente reclame la cuenta (422 access_level_raise_forbidden), y puede bajarlo en cualquier momento.
• Precio. El plan es emprendedor o empresario, mensual, cobrado en la suscripción managed-accounts del proveedor. enterprise es por contrato (422 managed_account_plan_not_self_serve), un proveedor en trial solo puede crear cuentas de pruebas (422 managed_account_provider_in_trial), y max_managed_accounts (25 por defecto) responde 422 managed_accounts_limit_reached.
• Mientras pagas tú. El titular de una cuenta gestionada que pagas tú no puede comprar plan, plazas de empleado ni NIF adicionales, y recibe 403 billing_managed_by_provider.
• Cuando el cliente asume el pago. El proveedor conserva su nivel como acceso cedido y el cliente conserva el mismo plan y precio. Con el nivel none no queda nada que ceder, así que la relación termina. No se publica ningún evento account.* por ello. Lo notas porque GET /v1/accounts/{account} responde 404 y la cuenta aparece en client_accounts de GET /v1/me con origin: "granted".
• Terminar la gestión no da al proveedor un acceso cedido. La relación termina y el proveedor pierde todo el acceso a la cuenta desde la siguiente petición.
• Cuentas de pruebas. Con una clave fact_test_, POST /v1/accounts crea una cuenta de pruebas: sin cobro, sin vale y sin reclamación (managed_account_not_claimable).
• El certificado VeriFactu del cliente. Un proveedor con operate lo sube con POST /v1/companies/{company}/verifactu/certificates, y verifactu_certificate_missing aparece como bloqueo en la aptitud de emisión del NIF. El certificado del cliente explica los pasos.
• MCP. Nueve herramientas reflejan estas operaciones, y la importación masiva no tiene ninguna. Solo aparecen para una clave que lista el scope privilegiado, y el recuento de herramientas del catálogo MCP no las incluye.

Los códigos nuevos son managed_account_external_ref_in_other_environment, provisioning_account_claimed y enterprise_contract_transition_required, además de los anteriores. Empieza por Cuentas gestionadas, sigue con precio y cambio de pagador y las pruebas con fact_test_. Las herramientas están en el catálogo MCP.

Importación masiva

Un proveedor puede cargar a sus clientes desde un CSV de una vez. Las tres operaciones son solo de API, sin herramienta MCP por diseño.

• Operaciones. GET /v1/accounts/imports/template descarga la plantilla (accounts:read). POST /v1/accounts/imports/preview revisa los ficheros y calcula el coste de cada fila sin escribir nada. POST /v1/accounts/imports los aplica. Los dos POST exigen accounts:write y reciben multipart/form-data con accounts_file, un customers_file opcional y options.
• Modalidades. Cada fila elige su mode, sin valor por defecto: own_nif añade un NIF a tu propia cuenta como NIF adicional, y managed_account aprovisiona una cuenta separada para tu cliente.
• Límites. 5 MB por fichero, 100 filas en accounts_file y 1.000 en customers_file: import_file_too_large es 413, y import_row_limit_exceeded e import_file_invalid son 422.
• Aplicar. Es irreversible y exige una Idempotency-Key. Las importaciones del mismo proveedor se aplican una a una (409 import_in_progress), y volver a importar el mismo fichero reconcilia por external_ref: nunca duplica una cuenta ni cobra dos veces.
• Claves de pruebas. Las filas managed_account crean cuentas de pruebas. Las filas own_nif salen ERROR con live_credential_required.

El evento account.import_completed avisa a tus webhooks de cuenta de que terminó. Importación masiva describe las columnas, los estados por fila y lo que la importación no hace.

Alcance por relación sobre {company}

Una cuenta puede dejar que otra trabaje con algunos o todos sus NIF. La cuenta receptora los alcanza con su propia credencial por /v1/companies/{company}/…, como si fueran suyos.

• Niveles. view lee y operate también escribe. Una escritura con view responde 403 company_read_only y no crea ni cambia nada.
• Lo que se queda en la cuenta cedente. Un NIF alcanzado por relación nunca abre las capacidades de la cuenta a la que pertenece. En el eje de empresa, las operaciones que son de la cuenta dueña (facturación, webhooks y registros de peticiones de empresa, consumo de automatizaciones y credenciales de Stripe) responden 403 forbidden_action, y las de nivel de cuenta responden 404 account_not_found.
• El segmento de cuenta. {account} en /v1/accounts/{account}/… es siempre la cuenta de tu credencial. Nombrar otra responde el mismo 404 account_not_found, así que los NIF de una cuenta cedente se alcanzan por {company}, nunca por {account}.
• Claves. El nivel de un NIF en una clave se fija al emitirla y solo puede bajar. Cuando el acceso se reduce o termina, las claves de la cuenta receptora se recalculan en la siguiente petición.
• Dónde se gestiona. Ceder, cambiar y revocar un acceso se hace solo en la aplicación web. No existe ruta ni herramienta MCP para ello, a propósito. No exige plan ni módulo y no ocupa plazas de usuario.
• Verlo. GET /v1/me ya no exige ningún scope. Devuelve account con is_provider y privileged_scopes, y client_accounts con las cuentas que alcanzas por relación (origin vale granted o provisioned), que solo se rellena si la clave tiene el scope privilegiado accounts:read, además de client_accounts_visible y client_accounts_has_more.
• Acotar claves. PATCH /v1/accounts/{account}/api-keys/{api_key}/nif-scope sustituye la lista de NIF de una clave con scoped_company_ids, y el nuevo alcance nunca puede superar el tuyo.

Acceso cedido recoge el flujo, y alcanzar un NIF y claves acotadas cubren el lado de la credencial.

Webhooks de cuenta y registros de peticiones

Una cuenta tiene sus propios endpoints de webhook y sus propios registros de peticiones, bajo /v1/accounts/{account}/…. Diez operaciones gestionan los endpoints y dos leen los registros, con los mismos scopes que sus gemelas de empresa (webhooks:read, webhooks:write, webhooks:delete y developers:read). Hay una herramienta MCP por operación, y ninguna está disponible por OAuth.

• Operaciones. POST /v1/accounts/{account}/webhooks crea un endpoint. Las demás lo listan, consultan, actualizan y borran, listan y consultan sus entregas, reintentan una, rotan el secret y envían una prueba. GET …/request-logs y GET …/request-logs/{request_id} leen las peticiones de todas las claves de la cuenta, en el entorno de la clave que pregunta.
• Equivalencia. retry corresponde a replay, secret a rotate-secret y test a test-event. No existe un ping de cuenta. El reintento de una cuenta rearma la misma entrega, mientras que el replay de una empresa crea una nueva.
• Filtro y entorno. account_relationship vale own, managed o all (por defecto). Un endpoint pertenece a un entorno, live o test, y no lo cambia nunca.
• Quién puede. Solo tu propia cuenta, con quien emitió la clave como titular o administrador y una clave que alcance todos los NIF de la cuenta. Crear, editar, rotar, probar, reintentar y borrar exigen una clave de producción.
• Límites. El número de endpoints depende del tramo de quien paga: 402 addon_required cuando no admite ninguno y 422 account_webhook_endpoint_limit_reached al llegar al tope.
• Endpoints de empresa sobre un NIF relacionado. Los webhooks y los registros de peticiones de una empresa responden 403 forbidden_action cuando el NIF se alcanza por relación. Conservan su contrato sobre tus NIF propios.

Webhooks de cuenta trae la tabla de equivalencias y el sobre, y Deduplicar entregas de webhooks explica por qué el mismo evento conserva el mismo id en los dos tipos de endpoint.

Eventos account.*

Quince eventos te cuentan lo que le pasa a la propia cuenta. Solo pueden suscribirse a ellos los endpoints de cuenta.

No están en GET /v1/event-catalog y nunca disparan una automatización. El sobre de una entrega de cuenta es el sobre de empresa más account, account_relationship y company_id, y las cabeceras añaden Factuarea-Account-Relationship. El evento de un NIF conserva el mismo id que tiene en un endpoint de empresa, mientras que un evento account.* no tiene gemelo de empresa. El catálogo account.* lista cada nombre con su carga, y Eventos explica para qué sirven.

Correcciones del contrato publicado

Cinco puntos del contrato publicado cambian sin que cambie ninguna operación, ningún estado ni ningún código que devuelve la API.

• Scopes del esquema OAuth2. El esquema OAuth2 del documento OpenAPI publica ahora los 66 scopes que ofrece la pantalla de consentimiento, con el vocabulario de punto que acepta el servidor de autorización (invoices.read, factuarea.full). Antes listaba los nombres finos que usan las API keys, como invoices:read, y una petición que nombre uno de ellos se rechaza con invalid_scope. Scopes y permisos recoge el catálogo.
• URLs de OAuth. Las URLs de autorización y de token de ese esquema son ahora las de producción: https://mcp.factuarea.com/api/oauth/authorize y https://mcp.factuarea.com/api/oauth/token.
• Rotación de secreto demasiado pronto. webhook_secret_recently_rotated es ahora un 422 en el catálogo de errores, y ya no un 429. La API ya respondía 422, así que un cliente hecho contra el catálogo lo habría reintentado como un rate limit. rotate_secret de empresa lo documenta ahora.
• seat-charge-preview. La descripción de seat-charge-preview dice que amount, tax_amount y total son euros en cadenas con dos decimales, y que solo recurring_base_cents y recurring_total_cents van en céntimos. Antes decía unidades menores. Los valores no cambian.
• Mensajes del 409 y del 404. El 409 del alta dice ahora Ya existe una empresa con ese NIF/CIF/NIE en la cuenta. y el 404 de un NIF, NIF no encontrado en la cuenta. Antes decían «empresa gestionada», que nombra una cuenta gestionada y no un NIF de tu propia cuenta. portfolio_max_api_keys_exceeded, portfolio_rate_limit_exceeded y portfolio_monthly_quota_exceeded hablan también de la cartera de tu cuenta y ya no de una gestoría. El code, el subcódigo y el param no cambian.

Renombrados

Estos nombres cambian en el contrato. Cada fila muestra el nombre que usaba el contrato anterior y el que lo sustituye.

Dos filas necesitan una nota. El role de un miembro es ahora el rol de cuenta, y el acceso a cada NIF vive en sus grants, así que los campos del miembro se sustituyen en lugar de renombrarse. Y POST /v1/accounts/{account}/claim-tokens reemite ahora el vale de reclamación de una cuenta gestionada, que es una operación distinta del traspaso que nombraba antes. El campo de facturación gestoria_seats conserva su nombre.

Operaciones

Todas las operaciones que el modelo de cuentas añade o cambia, con su página de referencia: