Cuentas gestionadas

Una cuenta gestionada es la cuenta que creas para uno de tus clientes. Es una cuenta normal, separada de la tuya: tiene su propio NIF, su propio perfil fiscal, su propio plan y, cuando el cliente la reclama, su propio titular. La aprovisionas por API, la paga tu cuenta y conservas un nivel de acceso sobre ella (none, view u operate) hasta que el cliente toma el relevo. Esta guía está escrita para la cuenta que aprovisiona, el proveedor de cuentas gestionadas. Explica el privilegio que necesitas, cómo crear y leer cuentas gestionadas, cómo las reclama el cliente, cómo funcionan tu nivel y el fin de la gestión, qué rutas abre una gestionada y cómo subir el certificado VeriFactu del cliente para que su NIF pueda emitir.

Lo que pagas por cada cuenta gestionada está en precio de las cuentas gestionadas y cambio de pagador. El flujo completo con una clave fact_test_, sin cobros, está en probar cuentas gestionadas. Para crear muchas de una vez, usa la importación masiva. La cuenta que operas tú mismo, y el segmento {account}, están en cuentas y NIF.

La vida de una cuenta gestionada

Dos campos dicen en qué punto está una cuenta gestionada. status es el estado de la propia cuenta, y el bloque management dice si tu cuenta todavía la gestiona.

Una cuenta cuya gestión termina antes de que nadie la reclame sigue en provisioned.

Scopes privilegiados

Las operaciones de aprovisionamiento de esta guía necesitan accounts:read o accounts:write. Son scopes privilegiados, y se distinguen de cualquier otro scope en cuatro cosas:

• * no los cubre. Una clave que solo tiene * recibe 403 insufficient_scope en estas operaciones. Indica accounts:read y accounts:write de forma explícita, junto a * si quieres también el resto.
• Los concedemos nosotros, cuenta por cuenta. Factuarea concede el privilegio de proveedor de cuentas a una cuenta, y solo Factuarea puede hacerlo. Pídenoslo: la API no tiene ninguna operación que lo conceda. GET /v1/me te dice si lo tienes, con account.is_provider y account.privileged_scopes. Una clave solo puede llevar accounts:* mientras esa lista los nombre, así que crear una clave así sin el privilegio responde 403 privileged_scope_required.
• No llegan por OAuth. Usa una API key, también con el servidor MCP.
• Ningún plan los condiciona. La puerta es el privilegio, no el plan.

La comprobación corre en cada petición y nada sale de una caché. La clave debe listar el scope, tu cuenta debe tener hoy el privilegio y la persona que emitió la clave debe seguir siendo titular o administrador de tu cuenta. Si falla cualquiera de las tres cosas, la respuesta es 403 privileged_scope_required, y las dos causas responden igual. Si revocamos el privilegio, o esa persona deja de ser titular o administrador, la misma clave deja de funcionar en su siguiente petición.

Las operaciones del plan y de la importación tienen sus propias guías: precio de las cuentas gestionadas y cambio de pagador e importación masiva.

El entorno de la clave es el entorno de todo lo que aprovisiona y lee. Una clave fact_live_ trabaja con cuentas gestionadas de producción y una clave fact_test_ con las de pruebas, y cada una ve solo las suyas.

{
  "data": {
    "account": {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a00",
      "name": "Asesoría Martínez",
      "environment": "live",
      "is_provider": true,
      "privileged_scopes": [
        "accounts:read",
        "accounts:write"
      ]
    }
  }
}

El bloque account de GET /v1/me, abreviado. La misma respuesta lista en client_accounts las cuentas gestionadas que alcanza tu cuenta, con origin: "provisioned", hasta 100; GET /v1/accounts las lista todas.

Aprovisiona una cuenta

POST /v1/accounts crea la cuenta, su NIF y la relación con tu cuenta en una sola llamada. No lleva segmento {account}, porque la cuenta todavía no existe. El proveedor es siempre la cuenta de la clave y el entorno es el de la clave: ninguno va en el cuerpo.

curl -X POST https://api.factuarea.com/v1/accounts \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "external_ref": "cliente-0042",
    "plan": "empresario",
    "access_level": "operate",
    "tax_id": "B12345674",
    "legal_name": "Talleres García SL",
    "display_name": "Talleres García",
    "language": "es",
    "owner_email": "laura@talleresgarcia.example",
    "send_email": false
  }'

{
  "data": {
    "id": "0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f",
    "object": "managed_account",
    "external_ref": "cliente-0042",
    "status": "provisioned",
    "environment": "live",
    "plan": "empresario",
    "pending_plan": null,
    "billing_interval": "monthly",
    "access_level": "operate",
    "display_name": "Talleres García",
    "language": "es",
    "companies": [
      {
        "id": "0199a1f0-1c22-7a10-b111-7a7b7c7d7e7f",
        "tax_id": "B12345674",
        "name": "Talleres García SL"
      }
    ],
    "claimed": false,
    "claimed_at": null,
    "management": {
      "status": "active",
      "ended_at": null
    },
    "paid_by_provider": true,
    "created_at": "2026-09-27T09:00:00+00:00",
    "claim_token": "c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1",
    "claim_url": "https://app.factuarea.com/account-claims/accept?token=c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1",
    "claim_expires_at": "2026-10-11T09:00:00+00:00"
  }
}

Una cuenta nueva responde 201 Created con Location: /v1/accounts/{id}. El cuerpo es la cuenta gestionada más su vale de reclamación. companies[].id es el {company} que usas en el eje de NIF, e id es el {account} de las rutas que nombran una cuenta gestionada.

La paga tu cuenta. En producción se la cobramos a tu cuenta en la suscripción managed-accounts, y precio de las cuentas gestionadas y cambio de pagador explica cuánto y cuándo. Una clave fact_test_ crea en cambio una cuenta de pruebas: no se cobra nada, no hay vale (claim_token y claim_url son null) y no cuenta para tu tope.

Idempotency-Key es obligatoria, porque el aprovisionamiento no se puede deshacer. Una petición sin ella se rechaza con 422 idempotency_key_required antes de ejecutar ninguna lógica de negocio. Un rechazo no crea nada.

Idempotencia: Idempotency-Key y external_ref

Dos protecciones trabajan juntas, y hacen trabajos distintos.

Idempotency-Key protege una petición. Si se corta la conexión y repites la misma petición con la misma clave, reproducimos la primera respuesta, con la cabecera Idempotent-Replayed: true, y no aprovisionamos dos veces. El vale es la única excepción: nunca lo guardamos en claro, ni siquiera en la caché de idempotencia, así que una repetición responde claim_token y claim_url como null. Si nunca recibiste la primera respuesta, reemite el vale. La misma clave con otro cuerpo es 422 idempotency_key_reused.

external_ref protege la cuenta. Es única para tu cuenta en los dos entornos, así que es la clave natural de tu CRM. Aprovisionar un external_ref que tu cuenta ya aprovisionó, aunque sea con una Idempotency-Key nueva, nunca crea una segunda cuenta:

El vale de reclamación

El vale es lo que necesita el cliente para reclamar la cuenta. Llega en tres campos de la respuesta del aprovisionamiento:

Lo que recibes depende de la llamada:

El vale se emite a nombre de owner_email: una persona que inicie sesión con otra dirección no puede usarlo.

Quién entrega el vale: send_email

Eliges una de dos vías, y el vale nunca viaja por las dos.

• send_email: false (por defecto). La respuesta lleva claim_url una sola vez y lo entregas tú por tu propio canal, por ejemplo tu CRM o tu propio correo. owner_email sigue siendo obligatorio con una clave de producción, porque el vale se emite a su nombre.
• send_email: true. Enviamos el enlace por correo a owner_email, en el language de la cuenta, y la respuesta lleva null en claim_token y claim_url. owner_email es obligatorio.

Reemite el vale

POST /v1/accounts/{account}/claim-tokens emite un vale nuevo para una cuenta gestionada que su titular todavía no ha reclamado. {account} es el id de la cuenta gestionada. Los vales pendientes dejan de funcionar y el nuevo va al mismo email y en el mismo idioma. El cuerpo es opcional y admite send_email, con el mismo significado que arriba. Necesita una Idempotency-Key.

curl -X POST https://api.factuarea.com/v1/accounts/$MANAGED_ACCOUNT_ID/claim-tokens \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "send_email": false }'

{
  "data": {
    "object": "managed_account_claim",
    "account_id": "0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f",
    "claim_token": "d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2",
    "claim_url": "https://app.factuarea.com/account-claims/accept?token=d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2",
    "expires_at": "2026-10-11T09:00:00+00:00"
  }
}

Con send_email: true, claim_token y claim_url son null, pero expires_at sigue llevando la fecha: la caducidad no es un secreto y una reemisión siempre emite un vale nuevo. Una repetición idempotente devuelve también claim_token y claim_url como null, y conserva expires_at. El vale nuevo dura 14 días, como el primero.

Lista y lee tus cuentas gestionadas

GET /v1/accounts lista las cuentas que aprovisionó tu cuenta, solo en el entorno de la clave: una clave fact_test_ lista tus cuentas de pruebas y una de producción las de producción. Ningún elemento lleva vale.

curl -G https://api.factuarea.com/v1/accounts \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  --data-urlencode "status=provisioned" \
  --data-urlencode "limit=25"

{
  "data": [
    {
      "id": "0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f",
      "object": "managed_account",
      "external_ref": "cliente-0042",
      "status": "provisioned",
      "environment": "live",
      "plan": "empresario",
      "pending_plan": null,
      "billing_interval": "monthly",
      "access_level": "operate",
      "display_name": "Talleres García",
      "language": "es",
      "companies": [
        {
          "id": "0199a1f0-1c22-7a10-b111-7a7b7c7d7e7f",
          "tax_id": "B12345674",
          "name": "Talleres García SL"
        }
      ],
      "claimed": false,
      "claimed_at": null,
      "management": {
        "status": "active",
        "ended_at": null
      },
      "paid_by_provider": true,
      "created_at": "2026-09-27T09:00:00+00:00"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Un valor de status desconocido o un external_ref de más de 128 caracteres responde 422, y un parámetro de consulta desconocido o un limit o starting_after mal formado responde 400.

GET /v1/accounts/{account} devuelve una cuenta gestionada por su id, con la misma forma. Funciona con cualquier nivel de acceso, none incluido: las operaciones de aprovisionamiento solo piden que la gestión esté vigente.

Con status=ended, tu cuenta ha perdido el acceso a la cuenta, así que cada elemento se reduce a lo que ya sabías:

{
  "id": "0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f",
  "object": "managed_account",
  "external_ref": "cliente-0042",
  "management": {
    "status": "ended",
    "ended_at": "2026-10-05T10:00:00+00:00"
  }
}

Consumo del aprovisionamiento

GET /v1/accounts/{account}/provisioning-usage te dice cuántas cuentas gestionadas llevas y cuántas más puedes aprovisionar. A diferencia de las rutas anteriores, {account} es tu propia cuenta, el account.id de GET /v1/me: cualquier otro valor responde 404 account_not_found.

{
  "data": {
    "object": "provisioning_usage",
    "managed_accounts": {
      "live": 12,
      "test": 3
    },
    "limit": 50,
    "remaining": 38,
    "managed_accounts_by_plan": {
      "emprendedor": 7,
      "empresario": 5,
      "integral": 0,
      "enterprise": 0
    },
    "provider_paid_additional_nifs": 2,
    "provider_paid_employee_seats": 9
  }
}

La reclamación

El cliente reclama la cuenta en la app, no por la API. El enlace de reclamación abre una página donde el cliente ve la cuenta que le espera, con su plan y su precio. Una persona nueva elige una contraseña, y quien ya tiene una cuenta de Factuarea inicia sesión. En los dos casos debe usar la dirección a la que se emitió el vale (owner_email): otra dirección se rechaza, igual que un vale ya usado, revocado o caducado.

La reclamación tiene estos efectos:

• El cliente pasa a ser el owner de la cuenta. claimed es true, claimed_at queda fijado y status pasa de provisioned a claimed. Si ya habías terminado la gestión, la cuenta pasa directamente a active.
• Conservas tu nivel. La reclamación nunca cambia access_level. Después puedes bajar el nivel, pero ya no subirlo: consulta las reglas del nivel.
• Sigues pagando hasta que el cliente asuma el pago. Mientras paid_by_provider sea true, la cuenta la pagas tú. Precio de las cuentas gestionadas y cambio de pagador explica cómo pasa el pago al cliente.
• Te avisamos. Los titulares y administradores de tu cuenta reciben un correo que dice que la cuenta se ha reclamado.
• El vale se consume. Reemitirlo responde 409 provisioning_account_claimed.

Una cuenta de pruebas no se puede reclamar: 422 managed_account_not_claimable cuando intentas reemitir su vale.

Tu nivel de acceso

PATCH /v1/accounts/{account}/access-level cambia el nivel que conserva tu cuenta sobre una cuenta gestionada. El cuerpo lleva level, que es obligatorio.

curl -X PATCH https://api.factuarea.com/v1/accounts/$MANAGED_ACCOUNT_ID/access-level \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "level": "view" }'

La respuesta es 200 con la cuenta gestionada y su nuevo access_level.

Antes de la reclamación, puedes subir y bajar el nivel las veces que necesites. Después de la reclamación, puedes bajarlo en cualquier momento, pero subirlo responde 422 access_level_raise_forbidden y no cambia nada: solo el titular puede subirlo, desde su panel. Bajarlo surte efecto al instante y recorta lo que tus credenciales alcanzan en sus NIF desde su siguiente petición.

Termina la gestión

DELETE /v1/accounts/{account}/management termina la gestión de una cuenta gestionada. Desde la siguiente petición tu cuenta pierde el acceso a ella y a sus NIF, y todas las rutas responden 404. Necesita una Idempotency-Key, y la respuesta es 200 con la cuenta y management.status: "ended".

curl -X DELETE https://api.factuarea.com/v1/accounts/$MANAGED_ACCOUNT_ID/management \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

{
  "data": {
    "id": "0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f",
    "object": "managed_account",
    "external_ref": "cliente-0042",
    "status": "provisioned",
    "environment": "live",
    "plan": "empresario",
    "pending_plan": null,
    "billing_interval": "monthly",
    "access_level": "operate",
    "display_name": "Talleres García",
    "language": "es",
    "companies": [
      {
        "id": "0199a1f0-1c22-7a10-b111-7a7b7c7d7e7f",
        "tax_id": "B12345674",
        "name": "Talleres García SL"
      }
    ],
    "claimed": false,
    "claimed_at": null,
    "management": {
      "status": "ended",
      "ended_at": "2026-09-28T10:00:00+00:00"
    },
    "paid_by_provider": true,
    "created_at": "2026-09-27T09:00:00+00:00"
  }
}

Lo que pasa después depende de si el cliente había reclamado la cuenta:

• Antes de la reclamación. La cuenta sigue en provisioned y no es operable: todos sus NIF pasan a inactive, con suspension_reason: "management_ended". El vale sigue funcionando. La cuenta queda así hasta que el cliente la reclame, o hasta que aprovisiones de nuevo el mismo external_ref, lo que reactiva la gestión.
• Después de la reclamación. La cuenta pasa a active y el pago pasa al titular. Si el titular no tiene método de pago, la gestión termina igualmente: dejas de pagar y los NIF de la cuenta quedan suspendidos hasta que el titular asuma el pago.
• Una cuenta enterprise por contrato que pagas de verdad necesita un plan en el que continuar. Sin él, la respuesta es 422 enterprise_contract_transition_required y la gestión sigue vigente. Escríbenos para que fijemos el plan y repite la llamada.

Después, GET /v1/accounts?status=ended sigue listando la cuenta con su id, tu external_ref y el bloque management, para que tu CRM pueda cerrar el ciclo. El cliente también puede terminar la gestión desde su panel.

Qué rutas de {account} aceptan una cuenta gestionada

{account} nombra normalmente tu propia cuenta. Una cuenta gestionada se acepta en una lista cerrada de rutas, y solo cuando tu cuenta la aprovisionó, su gestión está vigente y está en el mismo entorno que la clave.

Todo aquello en lo que no se acepta una cuenta gestionada responde el mismo 404 account_not_found, con el mismo cuerpo, en todos los casos: una cuenta que no es tuya, una que no existe, una del otro entorno, una cuya gestión terminó, una que te dio acceso cedido en vez de aprovisionarla tú, y un valor que no es un identificador. Nada en la respuesta los distingue, así que no sirve para averiguar qué cuentas existen.

Los NIF de la cuenta gestionada también se alcanzan en el eje de NIF, en /v1/companies/{company}/…, con el companies[].id que has leído arriba. Tus claves los alcanzan como alcanzan tus propios NIF, limitadas por tu nivel y por el ámbito de NIF de cada clave. Para añadir los NIF del cliente a una clave que ya tienes desplegada, envía la lista completa resultante a PATCH /v1/accounts/{account}/api-keys/{api_key}/nif-scope como scoped_company_ids. Un ámbito nuevo nunca puede exceder el de la credencial que lo cambia.

Cuando el cliente asume el pago, la cuenta paga sus propios NIF: tu relación pasa a ser acceso cedido con el mismo nivel, y registrar, activar, desactivar o archivar NIF corresponde a la cuenta que paga. NIF adicionales explica qué puedes añadir mientras pagas tú.

El lado del cliente es de la app

Lo que el cliente hace con una cuenta gestionada ocurre en la app, y nada de ello tiene una operación /v1 ni una tool MCP. Una credencial tuya no puede decidir por el titular. El cliente usa la app para:

• reclamar la cuenta con el vale;
• ver qué cuenta gestiona la suya y con qué nivel;
• subir o bajar el nivel que conservas, que es la única forma de subirlo tras la reclamación;
• terminar la gestión;
• asumir el pago.

Todo lo demás de esta guía es tu lado, el del proveedor.

El tope: max_managed_accounts

Cada cuenta que aprovisiona tiene un tope de cuentas gestionadas de producción. Por defecto es 25, vive en tu cuenta como max_managed_accounts y solo lo cambiamos nosotros. provisioning-usage lo devuelve como limit.

• Qué se cuenta. Solo las cuentas gestionadas de producción con la gestión vigente. Las cuentas de pruebas nunca lo consumen, ni tampoco las cuentas cuya gestión terminó.
• Al alcanzarlo. Aprovisionar una cuenta de producción más, o reactivar una, responde 422 managed_accounts_limit_reached y no crea nada. Dos peticiones a la vez no pueden superar juntas el tope, porque tu cuenta queda bloqueada mientras se comprueba cada una.
• Cómo hacer hueco. Termina la gestión de una cuenta que ya no llevas, o pídenos que subamos el tope de tu cuenta.

El certificado VeriFactu del cliente

Cada NIF presenta a VeriFactu con su propio certificado. Un proveedor no firma en nombre de sus clientes, y no existe un modo de representación ni de apoderamiento: lo que puedes hacer con operate es subir el certificado del cliente, para que su NIF pueda emitir.

El certificado debe ser el certificado FNMT del propio cliente, en formato PKCS#12, y debe coincidir con el NIF al que se sube. Necesitas una clave cuyo nivel efectivo sobre ese NIF sea operate, con el scope verifactu:write, y el id del NIF, que sale de companies[].id de la cuenta gestionada. Con view la subida responde 403 company_read_only, y con none responde el mismo 404 que cualquier NIF que no puedes alcanzar.

POST /v1/companies/{company}/verifactu/certificates acepta multipart/form-data con certificate_file (.p12 o .pfx, hasta 100 KB) y certificate_password. Necesita una Idempotency-Key. El certificado subido se activa al instante y los anteriores se desactivan.

curl -X POST https://api.factuarea.com/v1/companies/$CLIENT_COMPANY_ID/verifactu/certificates \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "certificate_file=@talleres-garcia.p12" \
  -F "certificate_password=$CERTIFICATE_PASSWORD"

{
  "data": {
    "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a13",
    "object": "verifactu_certificate",
    "subject_nif": "B12345674",
    "subject_name": "Talleres García SL",
    "subject_kind": "juridica",
    "valid_from": "2026-01-01T00:00:00+01:00",
    "valid_to": "2029-01-01T00:00:00+01:00",
    "is_active": true,
    "revoked_at": null,
    "created_at": "2026-01-10T09:00:00+01:00"
  }
}

La subida se rechaza con 422 en estos casos, y error.param nombra el campo:

Qué impide emitir a un NIF

GET /v1/accounts/{account}/companies/{company}/issuing-readiness responde si un NIF puede emitir ahora mismo, y por qué no cuando no puede. Funciona con el {account} de una cuenta gestionada y necesita companies:read. can_issue es el veredicto, y blockers es una lista cerrada de motivos, sin un orden concreto.

{
  "data": {
    "can_issue": false,
    "blockers": [
      "verifactu_certificate_missing"
    ],
    "census_status": "verified",
    "has_default_series": true,
    "fiscal_profile_complete": true,
    "operable": true,
    "missing_modules": [],
    "checked_at": "2026-09-30T10:15:00+00:00"
  }
}

verifactu_certificate_missing es un valor de blockers, no un código de error: la operación responde 200 y el catálogo de códigos de error no tiene página para él. Se suma a lo que ya bloquee al NIF, así que un NIF puede llevar varios a la vez. Solo se aplica mientras VeriFactu esté activo para el NIF. Sube el certificado y vuelve a leer issuing-readiness: el bloqueo desaparece cuando el certificado es vigente.

La lista puede crecer con el tiempo. Trata un motivo que no conozcas como un bloqueo que no puedes resolver por la API. La lectura es neutra: mira el estado fiscal y los módulos, y nunca la suscripción, el plan ni los pagos.

Una cuenta de pruebas no tiene VeriFactu: el módulo no está disponible con una clave de pruebas. Probar cuentas gestionadas explica qué deja fuera el camino de pruebas.

Sigue una cuenta gestionada con eventos

Un endpoint de webhooks de cuenta de tu cuenta recibe los eventos de las cuentas gestionadas que aprovisionas cuando cumplen las reglas de entrega de esa guía: account.managed_account_provisioned, account.managed_account_claimed, account.management_ended y account.access_level_changed. Son la forma de saber, sin consultar de forma periódica, que un cliente reclamó su cuenta o que la gestión terminó.

Desde el servidor MCP

Diez tools MCP reflejan las operaciones del proveedor. Cada una necesita el scope de la operación que refleja, que es siempre privilegiado: usa una API key, porque OAuth no lleva accounts:*.

La importación masiva no tiene tool MCP: lee ficheros subidos, que el servidor MCP no transporta. Tools MCP lista el resto del catálogo.

Próximos pasos