Preu dels comptes gestionats i canvi de pagador

Un compte gestionat és un compte normal amb el seu propi pla, i el teu compte el paga fins que el seu client assumeix el pagament. No hi ha una llista de preus a part per als comptes gestionats: la teva subscripció fa servir els mateixos preus que els plans i els add-ons de qualsevol compte, i el que canvia és qui paga. Aquesta guia explica el que pagues, com tries i canvies el pla, quan et cobrem, què passa quan el pagament passa al client, i què pots fer i què no mentre el teu compte és en trial o té un problema de pagament.

Les operacions d'aquesta guia que fas com a proveïdor de comptes gestionats necessiten el scope privilegiat accounts:read o accounts:write, que * no cobreix: comptes gestionats explica com es concedeixen i es comproven. {account} és l'id del compte gestionat, el que llista GET /v1/accounts, excepte a provisioning-usage, on és el teu propi compte.

Què pagues

Per cada compte gestionat live la gestió del qual és vigent i el client del qual no ha assumit el pagament, el teu compte paga tres coses, sempre mensuals. Totes van en una sola subscripció del teu compte, managed-accounts, que té un ítem per preu i la quantitat de tots els teus comptes gestionats sumada, mai un ítem per compte.

El que decideix l'import:

• El teu nivell d'accés no compta. Un compte en none, view o operate costa el mateix: el nivell canvia el que arriben a fer les teves credencials, no el que pagues.
• El pla és el del propi compte. Es desa al compte gestionat i els seus NIF el segueixen. El teu propi pla mai no el canvia, com explica el teu compte en trial o amb un problema de pagament.
• Les quantitats surten de l'estat real de cada compte. Les recalculem i les enviem sempre al proveïdor de pagament com a nombres absoluts, així que repetir una crida mai no cobra dues vegades.
• Els imports són base imposable. La previsualització del pla retorna la base, sense IVA.

El que no et costa res:

• Un compte gestionat de proves, creat amb una clau fact_test_. Mai no arriba al proveïdor de pagament: consulta provar comptes gestionats.
• Un compte en enterprise. Es factura per contracte, fora de la teva subscripció.
• Un compte que no és operable, perquè el seu NIF titular no és active, per exemple quan la teva facturació està bloquejada.
• Un compte la gestió del qual ha acabat, o el client del qual ha assumit el pagament.

Tria el pla

Tries el pla en aprovisionar el compte: plan és obligatori a POST /v1/accounts, i no hi ha cap interval per triar.

Un compte en enterprise s'acorda amb nosaltres per contracte i es factura per contracte, fora de la teva subscripció. No el pots demanar en aprovisionar i, un cop un compte és sota contracte, tampoc no pots canviar el seu pla amb les operacions de pla: responen el mateix 422 managed_account_plan_not_self_serve.

Quan se't cobra

Et cobrem quan canvia alguna cosa que pagues, sempre a la mateixa subscripció. No hi ha checkout: si el teu compte no té mètode de pagament, l'operació que et cobraria es rebutja abans.

Una reconciliació diària manté les quantitats alineades amb els comptes reals, sense prorrateig.

Canvia el pla

Pots canviar el pla d'un compte gestionat que pagues en qualsevol moment, també després que el client el reclami, mentre continuïs pagant. A més del scope, les dues operacions necessiten que el teu nivell d'accés al compte sigui operate. Previsualitza el canvi primer i després fes-lo.

Les tools MCP necessiten una API key: el canal OAuth no arriba a accounts:*. El canvi és irreversible, així que necessita una Idempotency-Key (idempotency_key a la tool), i una crida sense ella respon 422 idempotency_key_required.

Les dues operacions demanen el mateix:

• El compte és teu i el pagues tu. Ha de ser un compte gestionat aprovisionat pel teu compte, amb la seva gestió vigent i a l'entorn de la clau. El teu propi compte, un altre, un la gestió del qual ha acabat i un el client del qual ha assumit el pagament responen el mateix 404 account_not_found.
• El teu nivell és operate. Amb view o none la resposta és 403 forbidden_action i no canvia res.
• El pla és emprendedor, empresario o integral. enterprise respon 422 managed_account_plan_not_self_serve.

Previsualitza el canvi

curl -G https://api.factuarea.com/v1/accounts/$MANAGED_ACCOUNT_ID/plan/preview \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  --data-urlencode "plan=empresario"

{
  "data": {
    "object": "managed_account_plan_change_preview",
    "from_plan": "emprendedor",
    "to_plan": "empresario",
    "effective": "immediate",
    "effective_at": null,
    "prorated_amount_cents": 1250,
    "next_invoice_amount_cents": 3500,
    "currency": "EUR"
  }
}

Els imports són cèntims enters de base imposable, sense IVA. A diferència dels euros com a cadenes de GET …/billing, la previsualització del pla manté els cèntims, com diuen els noms dels camps. Els imports dels exemples són només il·lustratius: demana a la previsualització els reals en lloc de fixar-los al teu codi.

Fes el canvi

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

La resposta és 200 amb el compte gestionat. Una baixada mostra la destinació a pending_plan i conserva el pla actual a plan:

{
  "data": {
    "id": "0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f",
    "object": "managed_account",
    "external_ref": "cliente-0042",
    "status": "claimed",
    "environment": "live",
    "plan": "empresario",
    "pending_plan": "emprendedor",
    "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": true,
    "claimed_at": "2026-09-29T08:00:00+00:00",
    "management": {
      "status": "active",
      "ended_at": null
    },
    "paid_by_provider": true,
    "created_at": "2026-09-27T09:00:00+00:00"
  }
}

• Pujar (emprendedor a empresario). Té efecte i es cobra a l'acte, prorratejat, en una sola actualització de la teva subscripció, amb una factura per l'abonament i el càrrec. La resposta ja mostra el plan nou.
• Baixar (empresario a emprendedor). Queda pendent fins al final del període de la teva subscripció managed-accounts. No s'abona res del període en curs, però la factura de la renovació ja porta el pla nou i cap NIF addicional, perquè emprendedor no els admet. Quan el canvi té efecte, es desactiven els NIF addicionals del compte, mai la seva empresa titular.
• Canviar d'idea. Una petició nova substitueix una de pendent, i demanar el pla que el compte ja té la retira. Si el client assumeix el pagament abans, la baixada pendent es descarta i el client continua amb el pla actual.
• Un cobrament fallit. Si el proveïdor de pagament rebutja una pujada, el pla no s'escriu i no queda res cobrat. La resposta continua mostrant el pla anterior, així que llegeix plan i pending_plan en ella i, si no han canviat, repeteix el canvi amb una Idempotency-Key nova.
• Res a cobrar. Un compte de proves, o un que no se't cobra perquè el seu pagador està bloquejat, canvia a l'acte sense càrrec, i la seva previsualització mostra els dos imports a 0.

Llegeix el que pagues

GET /v1/accounts/{account}/provisioning-usage, amb el teu propi account.id com a {account}, compta el que pagues. managed_accounts_by_plan té els teus comptes live de cada pla, on els enterprise no són a la teva subscripció, i provider_paid_additional_nifs i provider_paid_employee_seats tenen els NIF addicionals i les places d'empleat que pagues a més del seu pla. Necessita accounts:read, i comptes gestionats descriu la resposta completa.

L'API no retorna cap import per compte. El llistat de comptes de clients de l'app mostra l'import mensual de cadascun, i la previsualització d'una importació massiva retorna l'import mensual i el prorrateig de cada fila i de tot el fitxer abans que confirmis.

Canvi de pagador

El teu compte paga fins que el client assumeix el pagament. El pagador canvia de les maneres de sota, i en totes el client continua amb el mateix pla i el mateix preu: res no es torna a preuar i no hi ha cap pla nou per triar.

Així passa el pagament de tu al client, perquè res no es cobri dues vegades i no hi hagi buits:

• El client comença a pagar quan acaba el període que ja vas pagar. Creem les seves subscripcions primer, les verifiquem i només després baixem la teva. El primer cobrament del client cau quan aquest període acaba, mai abans. Si aquesta data ja ha passat, el primer cobrament és immediat.
• No se t'abona res i no pagues dues vegades. La teva factura següent surt sense les unitats del compte. No s'abona res del que resta del període, perquè el client comença a pagar quan acaba.
• Un error mai no deixa el compte sense pagador. Reintentem, i si el pagament no es pot completar desfem el que hem creat i continues pagant tu.
• El client necessita un mètode de pagament al seu propi compte. L'app li'l demana abans que el client assumeixi el pagament, i no canvia res fins que l'afegeix.
• Una baixada pendent es descarta. El client continua amb el pla que té el compte.

Segueix-ho des del teu costat

paid_by_provider et diu qui paga mentre la gestió és vigent. Per adonar-te que el client ha assumit el pagament, busca aquests senyals:

• GET /v1/accounts/{account} respon 404 account_not_found, i el compte ja no és a GET /v1/accounts.
• GET /v1/me llista el compte a client_accounts com un accés cedit, amb origin: "granted" i paid_by_provider: false:

{
  "id": "0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f",
  "name": "Talleres García",
  "origin": "granted",
  "access_level": "operate",
  "status": "active",
  "paid_by_provider": false,
  "environment": "live"
}

Quan la gestió acaba, en canvi, sí que publiquem account.management_ended als endpoints de webhook del teu compte.

Enterprise per contracte

Un compte sota un contracte enterprise no té pla on continuar fins que el fixem nosaltres. Si acabes la gestió, o el seu client intenta assumir el pagament, abans que l'hàgim fixat, la resposta és 422 enterprise_contract_transition_required: no canvia res i la gestió continua vigent. Val també abans de la reclamació, perquè el client necessitarà el mateix pla quan reclami el compte. Contacta amb nosaltres, fixem el pla en què continua el compte i repeteixes l'operació. Si aquest pla és emprendedor, es desactiven els NIF addicionals del compte, perquè aquest pla no els admet.

Acaba la gestió

DELETE /v1/accounts/{account}/management acaba la gestió, com explica comptes gestionats. El que passa amb el pagament depèn de si el client havia reclamat el compte: consulta la taula de canvi de pagador. Necessita una Idempotency-Key, i la tool MCP és end_account_management. La resposta és 200 amb el compte i management.status: "ended", i des de la petició següent el teu compte perd l'accés.

El teu compte en trial o amb un problema de pagament

Aprovisionar un compte gestionat live comprova tres coses, en aquest ordre, abans de crear o cobrar res:

1. En trial. Un compte gestionat live es cobra des del primer dia, així que un compte en el seu trial només pot crear comptes gestionats de proves. Un de live respon 422 managed_account_provider_in_trial. El teu compte és en trial durant la seva finestra de prova sense subscripció, o mentre la seva subscripció del pla és en el seu període de prova. Quan el trial acaba i comences a pagar, el següent aprovisionament live passa a la comprovació següent. Una clau fact_test_ crea comptes de proves durant el trial, sense càrrec.
2. El topall. En el teu topall de comptes gestionats live, la resposta és 422 managed_accounts_limit_reached. Els comptes de proves no compten: limit i remaining a provisioning-usage et diuen on ets.
3. El mètode de pagament. Un compte live necessita un mètode de pagament al teu compte. Sense ell, la resposta és 402 payment_method_required. Dona'n d'alta un al portal de facturació de l'app i repeteix la crida.

El mateix ordre s'aplica quan reactives, per external_ref, una gestió que va acabar abans de la reclamació.

Si el teu compte deixa de pagar, els comptes gestionats que pagues deixen de ser operables. No s'esborra res. Passa quan el teu propi pla queda impagat, quan caduca sense cap subscripció activa, o quan la teva subscripció managed-accounts acaba unpaid o canceled després dels reintents de cobrament. Una renovació fallida no bloqueja a l'acte: abans s'executen els reintents habituals. L'efecte és:

• Tots els NIF d'aquests comptes passen a inactive, amb suspension_reason: "payer_blocked", com descriu l'estat d'un NIF. Les crides sobre ells responen 403 company_inactive.
• Es reprenen sols quan la teva facturació torna a estar al dia, o quan el client assumeix el pagament. Només es reprenen els NIF que va suspendre el bloqueig: un que el propi compte va desactivar es queda com estava.
• Els comptes gestionats de proves no es veuen afectats.

Per la resta, el teu propi pla és independent dels teus comptes gestionats: pujar-lo, baixar-lo o programar-ne la cancel·lació no canvia res en ells, i la seva subscripció, managed-accounts, no es toca.

El que el client no pot comprar mentre pagues

Mentre pagues i la gestió és vigent, el client no compra res al seu propi compte, perquè el que compraria va a la teva factura. Les seves credencials, i les seves persones a l'app i a MCP, reben 403 billing_managed_by_provider en aquestes operacions, sense càrrec i sense canvis. En aquesta taula {account} és el propi compte del client:

Llegir la facturació no és un error: GET /v1/companies/{company}/billing d'un NIF d'un compte així respon managed: true sense gestoria_seats ni payment_method, així que el que pagues mai no arriba a les claus del client.

Per la teva part, no compres places d'empleat per a un compte gestionat: la quantitat segueix els seus empleats actius. Els NIF addicionals els dona d'alta el teu compte, amb l'{account} del compte gestionat i nivell operate, i el càrrec va a la teva subscripció: consulta NIF addicionals. Quan el client assumeix el pagament, el compte es paga a si mateix i el seu titular i els seus administradors poden tornar a fer servir aquestes operacions.

Errors

Relacionat