Acceso cedido entre cuentas

Una cuenta puede dejar que otra cuenta trabaje con todos o algunos de sus NIF, sin compartir ninguna contraseña y sin mover nada. La cuenta que lo permite es la cuenta cedente, y los NIF siguen siendo suyos. La cuenta que recibe el acceso es la cuenta receptora. Es lo que usa una empresa cuando quiere que su asesoría emita y consulte sus documentos.

Es un solo acceso entre dos cuentas. Tiene un nivel, view u operate, y un alcance: todos los NIF de la cuenta cedente, o solo los que ella elige. La cuenta receptora alcanza esos NIF con sus propias credenciales a través del segmento {company} del eje de NIF. Esta guía explica cómo se cede un acceso, qué puede y qué no puede hacer con él la cuenta receptora y qué pasa con sus claves cuando el acceso se reduce o termina.

No es una cuenta gestionada, que crea un proveedor para su cliente, ni es un grant, que da a un miembro de tu propia cuenta acceso a uno de tus NIF. Cuando el titular de una cuenta gestionada asume el pago, el acceso del proveedor pasa a ser un acceso cedido: precio y cambio de pagador lo explica.

El acceso en resumen

Con all, un NIF que la cuenta cedente añada más adelante entra en el acceso por sí solo, y uno que archive o traspase a otra cuenta sale de inmediato. Con list, el acceso cubre los NIF de la lista que siguen siendo de la cuenta cedente. Un NIF que solo está desactivado se queda en el alcance y responde 403 company_inactive hasta que se reactive.

Ceder, cambiar y revocar en la aplicación web

Ceder, cambiar y revocar un acceso se hace solo en la aplicación web. No existe ninguna ruta de la API ni ninguna herramienta MCP para ello, a propósito: una credencial filtrada no debe poder abrir los NIF de una cuenta a otra. Aceptar, rechazar y renunciar a un acceso también son operaciones de la aplicación web.

• Quién puede. Solo un titular o administrador de la cuenta de cada lado. Un miembro y una persona ajena a la cuenta reciben el mismo 403 forbidden_action.
• Invitar por email o por código de cuenta. Por email, Factuarea envía la invitación a esa dirección, y una persona que aún no tiene cuenta puede registrarse y aceptar con el mismo enlace. Por código de cuenta, la cuenta cedente pega el código de la otra cuenta, que es su account.id, el UUID que devuelve GET /v1/me. La cuenta receptora lo encuentra en Ajustes → Accesos a mi cuenta, y la invitación espera entonces en sus invitaciones pendientes. Cada invitación lleva un nivel y un alcance.
• Un solo acceso abierto por pareja. Invitar a una cuenta que ya tiene contigo un acceso pendiente o vigente responde 422 relation_already_exists, y lo mismo ocurre al aceptar una invitación por email cuando las dos cuentas ya tienen uno abierto. Un código que nombra tu propia cuenta, que no existe o que está mal formado responde el mismo 422 relation_self_grant_not_allowed, para que el campo no sirva para sondear cuentas. Una lista de NIF que nombra alguno que la cuenta cedente no tiene, o que viene vacía, responde 422 relation_company_not_in_grantor y no dice cuál falla.
• Caducidad. Una invitación caduca a los 7 días. Reenviarla emite un secreto y una caducidad nuevos, y el enlace anterior deja de valer. Una invitación caducada sigue pendiente y no se puede aceptar (422 relation_invitation_expired). Una enviada por código de cuenta mantiene ocupada la pareja hasta que se reenvíe o se retire. Invitar y reenviar comparten un mismo límite de peticiones por cuenta cedente.
• Aceptar. Una invitación por código de cuenta se acepta desde la lista de invitaciones pendientes, y una por enlace se acepta eligiendo qué cuenta administra la persona. Una invitación por email la tiene que aceptar la persona con esa dirección. El secreto vale una sola vez: uno vacío, desconocido, ya usado, retirado o dirigido a otra persona responde el mismo 422 relation_invitation_invalid, a propósito.
• Cambiar y terminar. La cuenta cedente puede cambiar el nivel entre view y operate, cambiar los NIF y revocar el acceso en cualquier momento, también mientras la invitación está pendiente. La cuenta receptora puede rechazar una invitación pendiente y renunciar a un acceso vigente. Un cambio que el estado del acceso no admite responde 422 relation_transition_not_allowed.
• Quién recibe aviso. Una invitación, su aceptación, una revocación, un rechazo y una renuncia avisan por correo a la otra cuenta. Cambiar el nivel o los NIF no envía ningún correo, y llega a la cuenta receptora en su siguiente petición.

Alcanzar un NIF cedido

La cuenta receptora alcanza un NIF cedido como uno propio: por el segmento {company}, en /v1/companies/{company}/…. {company} es el id del NIF (UUID v7), nunca su tax_id. El segmento {account} de /v1/accounts/{account}/… sigue siendo tu propia cuenta: la cuenta cedente no es una cuenta que administres, y nombrarla responde el mismo 404 account_not_found que cualquier cuenta que no es tuya. El servidor MCP alcanza los mismos NIF: nombra el NIF con la cabecera X-Company-Id en lugar de un segmento de ruta, con los mismos niveles y los mismos límites.

Una persona de la cuenta receptora alcanza un NIF cedido con este nivel:

En la aplicación web, los NIF cedidos aparecen como cuentas de clientes, aparte de los NIF de tu propia cuenta. Una credencial recibe el nivel de la persona que la emitió, como explica el techo de tus claves.

Una credencial alcanza un NIF cedido solo cuando su ámbito lo nombra. Las claves que ya existían no cambian cuando se cede un acceso, y una clave que creas por la API sin scoped_company_ids alcanza los mismos NIF que la credencial que la crea, y nunca más. Por eso:

• La primera clave se crea en la aplicación web. En Ajustes → Desarrolladores → API Keys, el campo de ámbito de NIF lista los NIF del acceso en un grupo llamado Cuentas de clientes, cada uno con el nivel más alto que admite. Solo un titular o un administrador de la cuenta receptora puede crear claves ahí y, con ello, añadirlos: un miembro no puede, ni siquiera sobre los NIF en los que tiene un grant.
• La API reduce y nunca amplía. POST /v1/accounts/{account}/api-keys con scoped_company_ids y PATCH /v1/accounts/{account}/api-keys/{api_key}/nif-scope, los dos con el scope account:write, solo aceptan NIF que la clave que llama ya alcanza. Pedir uno más responde 422 business_rule_violation con el subcódigo nif_scope_exceeds_issuer, y un NIF de una cuenta que no te ha cedido nada responde 422 invalid_param_value, igual que uno que no existe.

Cuando una clave los alcanza, GET /v1/me los lista en scope. No aparecen en GET /v1/accounts/{account}/companies, que lista solo los NIF de la cuenta del path. El bloque client_accounts de GET /v1/me lista las cuentas que te cedieron acceso (origin granted) solo cuando la clave lleva el scope privilegiado accounts:read en vigor, lo que exige el privilegio de proveedor de cuentas gestionadas de tu cuenta. Si no, va vacío y client_accounts_visible es false.

Qué puedes hacer en cada nivel

El nivel del acceso decide qué puedes hacer en un NIF cedido.

Un acceso operate te hace administrador del NIF, no de la cuenta que lo posee. Trabajas con los datos del NIF dentro de lo que permite el plan de la cuenta cedente, y lo que creas pertenece a ese NIF. El servidor MCP aplica los mismos niveles y responde el mismo 403 company_read_only.

Un POST /v1/companies/{company}/invoices en un NIF con view responde:

{
  "error": {
    "type": "authorization_error",
    "code": "company_read_only",
    "message": "Tu acceso a esta empresa es de solo lectura.",
    "doc_url": "https://docs.factuarea.com/guides/errors#company_read_only",
    "request_id": "req_01J8Y3M2Q40000000000000007"
  }
}

Lo que se queda en la cuenta cedente

Algunas operaciones del eje de NIF pertenecen a la cuenta que posee el NIF, no a los datos del NIF. En un NIF cedido responden 403 forbidden_action antes de leer o cambiar nada, con cualquiera de los dos niveles y también las lecturas. El mensaje no nombra la cuenta cedente.

Un POST /v1/companies/{company}/webhook-endpoints en un NIF cedido responde, con view o con operate:

{
  "error": {
    "type": "authorization_error",
    "code": "forbidden_action",
    "message": "Esta operación solo la puede hacer la cuenta dueña del NIF: con un acceso por relación entre cuentas no está disponible.",
    "doc_url": "https://docs.factuarea.com/guides/errors#forbidden_action",
    "request_id": "req_01J8Y3M2Q40000000000000008"
  }
}

Sus herramientas MCP responden lo mismo. El resto de las operaciones del eje de NIF son datos del NIF y se sirven con tu nivel. La cuenta que posee el NIF llama a estas mismas operaciones como siempre.

Las capacidades de la propia cuenta cedente viven bajo /v1/accounts/{account}/…: su equipo, invitaciones, titularidad, API keys, cartera y traspasos de NIF, webhooks de cuenta y registros de peticiones. {account} tiene que ser tu propia cuenta, así que no puedes dirigirte a ellas. Las operaciones que llevan en el path un NIF de la cuenta también rechazan uno cedido: activar, desactivar, editar o archivar un NIF cedido por la ruta de tu propia cuenta responde 404 resource_not_found, sin cambio de estado ni cargo. La aplicación web bloquea las mismas capacidades mientras un NIF cedido es tu empresa activa: la facturación, el equipo, las invitaciones, la titularidad, las claves, la compra, el traspaso y el archivo de NIF, los webhooks de empresa y los ajustes de la cuenta se quedan con la cuenta cedente.

Tus claves: nivel y techo

El nivel de una clave en un NIF cedido se fija cuando el NIF entra en la clave, al emitirla o al cambiar su ámbito, y solo baja. Es el menor entre el nivel del acceso y el nivel que tiene en ese NIF la persona que emite la clave, que para un member queda además limitado por su grant. En cada escritura cuenta el menor entre el nivel guardado en la clave y el que la persona emisora tiene hoy.

• Escribir exige operate. Una clave con cualquier scope que no sea de lectura (:read), incluido el scope *, necesita operate en cada NIF que nombra. Nombrar un NIF que solo tiene view junto con uno de esos scopes responde 422 business_rule_violation con el subcódigo nif_access_level_exceeds_emitter y no crea nada. Si no declaras scoped_company_ids, se dejan fuera los NIF por debajo del nivel que piden los scopes, y cuando no queda ninguno la respuesta es el mismo 422. En la aplicación web, un NIF con view solo admite scopes de lectura.
• Un NIF que quien emite no alcanza. Un NIF cedido en el que un miembro no tiene grant, o uno de una cuenta que no te ha dado acceso, responde 422 invalid_param_value con param scoped_company_ids, igual que un NIF que no existe.
• El plan es el plan del NIF. Un NIF cedido aporta el plan de su propia cuenta. Una clave recibe un scope solo si el plan de todos los NIF de su ámbito lo permite, y el exceso nunca se recorta en silencio: responde 422 scope_not_allowed_by_plan.
• Las claves de pruebas no lo alcanzan. Una clave fact_test_ alcanza solo la empresa sandbox de su cuenta, así que nunca alcanza un NIF cedido y responde 404 profile_not_found. Usa una clave fact_live_.

Cuando el acceso se reduce o termina

Un acceso se reduce cuando la cuenta cedente lo revoca, baja su nivel o le quita NIF, cuando la cuenta receptora renuncia a él, y cuando un NIF sale de la cuenta cedente. Cada una de estas cosas surte efecto en la siguiente petición:

• Se retiran los grants que los miembros de la cuenta receptora tenían sobre los NIF perdidos.
• Cada clave de la cuenta receptora se recalcula a la baja. Un NIF sin nivel sale del ámbito de la clave, un nivel bajado a view convierte las escrituras de esa clave en 403 company_read_only, y una clave que se queda con el ámbito vacío se revoca. El resto de la clave sigue funcionando sobre sus NIF propios.
• Un NIF que la cuenta receptora ya no alcanza responde 404 profile_not_found, igual que uno que no existe, así que la respuesta no revela que existe.

Nada sube por sí solo. Subir el nivel, ampliar los NIF o aceptar un acceso nuevo no toca las claves que ya existen: emite una clave nueva para ese NIF para obtener el nivel nuevo.

Repartir el acceso con tu equipo

Un titular o administrador de la cuenta receptora decide qué miembros de su equipo trabajan con los NIF cedidos. Un miembro recibe un grant con view u operate sobre un NIF del alcance de un acceso vigente, y lo alcanza con el menor entre el grant y el nivel del acceso. La aplicación web lo hace desde la cuenta de cliente, en Accesos recibidos. La API lo replica con las operaciones de los grants de miembro, donde {company} es el NIF cedido:

• Quién y qué. La persona que emitió la credencial tiene que ser titular o administrador de la cuenta, y el ámbito de la credencial tiene que incluir ya ese NIF. Los scopes members:* necesitan el módulo user_management.
• Gana el nivel menor. Dar operate sobre un acceso que es view no se rechaza: el nivel se guarda tal cual y el miembro alcanza el NIF con el menor de los dos.
• Fuera del acceso. Un NIF fuera de un acceso vigente, o uno cuyo acceso terminó, responde 422 grant_company_not_in_account al escribir y 404 member_not_found al leer, sin decir que alguna vez hubo un acceso. Un owner o un admin responde 422 grants_only_for_member, porque ya alcanza todos los NIF del acceso.
• Sin correo. Dar, cambiar o retirar un grant no envía ningún correo.

Seguir el acceso como cuenta cedente

La cuenta cedente puede seguir sus accesos con tres eventos account.* en sus webhooks de cuenta:

Su data es un objeto account_relation con id, origin (granted), level, previous_level, grantor_account_id, grantee_account_id y status. Solo los endpoints de la cuenta cedente los reciben: a la cuenta receptora no se le envía nada de un acceso cedido. Un cambio de los NIF del acceso tampoco se publica.

La cuenta receptora no puede suscribirse a lo que ocurre en un NIF cedido. Los webhook endpoints del eje de NIF responden 403 forbidden_action sobre él, como dice la tabla anterior, y sus webhooks de cuenta cubren solo sus propios NIF y las cuentas que aprovisiona.

Ten en cuenta

• Identidad de envío. Un NIF cedido no hereda nada de la cuenta receptora: su estado de confianza y su comprobación de identidad de envío siguen siendo los de su propia cuenta. Envío de documentos describe la comprobación.
• Automatizaciones. Las automatizaciones de cartera de la empresa titular de la cuenta receptora cubren, además de sus otros NIF, los NIF cedidos en los que el acceso es operate, y ninguno con view. Automatizaciones las explica.

Relacionado