Asesor externo

El asesor externo es la única persona ajena a tu equipo a la que tu cuenta deja trabajar con sus NIF, normalmente quien te lleva la contabilidad. El asesor entra en tu cuenta como member con grants (permisos por NIF) sobre los NIF que elijas, igual que cualquier otro miembro, con tres diferencias: hay uno por cuenta, existe en cualquier plan y no ocupa plaza.

Esta guía explica qué es el rol, cómo darlo desde la aplicación web y desde la API, qué planes solo pueden gestionarlo desde la aplicación web, qué pierde el asesor cuando lo retiras y qué errores esperar. El asesor es una persona dentro de tu cuenta. Si el despacho trabaja desde su propia cuenta, usa en su lugar el acceso cedido, que es una relación entre dos cuentas.

Qué es el rol

En la API, un miembro indica si es el asesor en el campo external_advisor. El listado de miembros no tiene filtro para ello: recorre GET /v1/accounts/{account}/members y busca al miembro con external_advisor: true, del que hay como máximo uno. Para un titular o un administrador que lo lee, su bloque permissions dice can_change_role: false y can_transfer_ownership: false, mientras que can_remove y can_edit_grants siguen en true.

Da acceso al asesor

El asesor entra mediante una invitación enviada desde la aplicación web. Un titular o un administrador abre la sección Asesor externo de la página de gestión de usuarios, elige Invitar asesor, escribe el email, marca los NIF con su nivel (view u operate) y decide si Factuarea envía el correo o muestra el enlace una sola vez para que lo copies. La persona la acepta como cualquier otra invitación y entra como member con la marca.

Para traer al asesor por la API, invita a la persona como member y marca al miembro cuando se haya unido. En una cuenta que ha llegado a su tope de usuarios esa primera invitación responde 422 business_rule_violation, así que usa la aplicación web.

• De uno en uno. Una segunda invitación pendiente del asesor responde 422 external_advisor_already_assigned, y lo mismo ocurre al invitar al asesor cuando la cuenta ya tiene uno. Una invitación ordinaria pendiente no estorba. El mismo código responde cuando la persona acepta y otro asesor ha ocupado el hueco mientras tanto.
• Una invitación caducada sigue ocupando el hueco. Una invitación de asesor que caducó sin revocarse sigue contando hasta que la revocas o invitas a otro asesor, lo que la revoca por ti.
• Síguela desde la API. GET /v1/accounts/{account}/invitations lista una invitación pendiente del asesor con external_advisor: true, y las operaciones que revocan y reenvían una invitación actúan sobre ella como sobre cualquier otra.

Marca a un miembro como asesor

Para convertir a un miembro existente en el asesor, envía external_advisor al miembro:

{member} y member_id son el id del miembro, el que publica el listado de miembros, no el identificador de la persona. Las herramientas MCP del equipo necesitan una API key: el canal OAuth no las alcanza.

curl -X PATCH "https://api.factuarea.com/v1/accounts/$ACCOUNT_ID/members/$MEMBER_ID" \
  -H "Authorization: Bearer $FACTUAREA_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "external_advisor": true }'

{
  "data": {
    "id": "01933a50-2c41-7a8b-9c0d-1e2f3a4b5c03",
    "object": "account_member",
    "name": "Laura Vidal",
    "email": "laura@despacho.example",
    "role": "member",
    "external_advisor": true,
    "grants": [
      {
        "object": "account_member_grant",
        "company_id": "0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e",
        "level": "view"
      }
    ],
    "permissions": {
      "can_change_role": false,
      "assignable_roles": [],
      "can_remove": true,
      "can_transfer_ownership": false,
      "can_edit_grants": true
    }
  }
}

• Quién puede. La persona que emitió la credencial tiene que ser titular o administrador de la cuenta en el momento de la llamada, con la sección user_management disponible, y el ámbito de la credencial tiene que cubrir todos los NIF de la cuenta, porque la marca cambia cuántas plazas ocupa todo el equipo. Si no, la respuesta es 403 forbidden_action.
• Cuerpo. external_advisor, role o ambos, y al menos uno. Los dos cambios se aplican juntos o ninguno: primero se quita la marca, después cambia el rol y la marca se pone al final. Por eso pasar al asesor a admin se hace con una sola petición, { "role": "admin", "external_advisor": false }, y necesita una plaza libre, como explica quitar la marca.
• Marcar. Solo se puede marcar a un member, y solo cuando la cuenta no tiene otro asesor. Volver a marcar al asesor actual no cambia nada. El miembro conserva sus grants y deja de ocupar plaza. Una invitación de asesor pendiente no impide marcar a un miembro, pero responderá 422 external_advisor_already_assigned cuando su persona la acepte.
• Sin aviso. Marcar y quitar la marca no envían ningún email ni publican ningún evento.

Planes sin gestión de usuarios

Gestionar el equipo por la API y el servidor MCP pertenece al módulo user_management, que incluyen los planes empresario y enterprise y no incluye emprendedor. Sin él, los scopes members:* e invitations:* no se pueden asignar a una clave y las herramientas del equipo quedan fuera de alcance, así que el asesor se gestiona solo desde la aplicación web. En un plan así, GET /v1/me deja esos scopes fuera de los scopes efectivos de la clave.

La aplicación web no tiene ese límite para el asesor. En cualquier plan un titular o un administrador puede invitar al asesor, verlo con sus grants, cambiar esos grants, reenviar o cancelar la invitación, retirar al asesor y quitarle la marca. Todo lo demás de la gestión del equipo sigue bloqueado.

Es una exclusión declarada, no una laguna: permite que una cuenta con un plan sin gestión de equipo dé acceso a quien le lleva la contabilidad. La guía de alcance y limitaciones la recoge junto con lo demás que la API no cubre.

Cambia lo que alcanza el asesor

Los grants del asesor son los de cualquier member: en la aplicación web, en la misma sección donde lo invitaste, y en la API y el servidor MCP con las operaciones de miembros, que necesitan el módulo user_management.

Revocar un grant cierra ese NIF al asesor en la aplicación web, la API y el servidor MCP, y bajarlo de operate a view lo deja en solo lectura. Las dos cosas bajan en consecuencia las API keys de la persona sobre ese NIF, y una clave nunca gana un nivel porque el grant vuelva a subir. Para que el asesor vea menos sin retirarlo, revoca o baja el grant.

Retira al asesor

Hay dos formas de terminar el rol, y hacen cosas distintas. Elige según si la persona sigue trabajando en tu cuenta.

Saca al asesor de la cuenta

curl -X DELETE "https://api.factuarea.com/v1/accounts/$ACCOUNT_ID/members/$MEMBER_ID" \
  -H "Authorization: Bearer $FACTUAREA_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

La respuesta es 204 sin cuerpo. La operación necesita members:write, un titular o un administrador con la sección user_management disponible como emisor y una credencial que cubra todos los NIF de la cuenta. Es irreversible, así que Idempotency-Key es obligatoria y una llamada sin ella responde 422 idempotency_key_required. La herramienta MCP delete_account_member también es irreversible y recibe un idempotency_key. Esto es lo que pierde el asesor, igual en los tres canales:

• Todos los NIF de la cuenta, de golpe. El acceso es un único hecho, la pertenencia a la cuenta, así que retirarla cierra la aplicación web, la API y el servidor MCP a la vez. No queda ningún acceso por canal que limpiar.
• Sus sesiones. Se revocan las sesiones ligadas a cualquier NIF de la cuenta o al sandbox de alguno. Sus sesiones en cualquier otro sitio se mantienen.
• Sus API keys. Las claves de la persona para esta cuenta pierden los NIF de la cuenta, y una clave que se queda sin ninguno se revoca.
• Su usuario, solo si nada más lo vincula. La persona se elimina cuando no tiene otra cuenta, ninguna pertenencia de empleado ni ninguna empresa fuera de esta cuenta. Si no, conserva su usuario y todo lo demás.
• Sin vuelta atrás. Sus grants desaparecen. Para darle acceso de nuevo invitas otra vez a la persona desde la aplicación web, con los grants desde cero. El hueco del asesor queda libre en cuanto vuelve la llamada.

Si solo quieres que el asesor vea menos, baja sus grants en su lugar.

Mantén a la persona y quita la marca

Quitar la marca deja a la persona en la cuenta como member con los mismos grants, y desde entonces ocupa plaza. El plan necesita por tanto una libre: sin ella la respuesta es 422 business_rule_violation con param external_advisor, y no cambia nada. Libera una plaza o retira al asesor en su lugar. Quitar la marca a un miembro que no es el asesor no cambia nada.

Eventos

Retirar al asesor es un cambio de pertenencia como cualquier otro: publica account.member_removed en los endpoints de webhook de cuenta que lo tengan suscrito, y aceptar la invitación publica account.member_added. Marcar y quitar la marca no publican nada, y el payload de los eventos account.member_* lleva el role pero no la marca, así que lee external_advisor del miembro cuando lo necesites. Webhooks de cuenta describe los endpoints y el sobre.

Errores

Relacionado