NIF addicionals

El teu compte s'obre amb un NIF, la seva empresa titular. Cadascun dels altres NIF que opera el compte és un NIF addicional, tant si el dónes d'alta com si el reactives o el reps per un traspàs de NIF. Els NIF addicionals es facturen com un add-on mensual, així que afegir-ne un pot cobrar el teu compte a l'acte. Aquesta guia explica el que pagues, quins plans els admeten, el topall, la regla del trial, la previsualització i els quatre codis que rebutgen una alta.

Les escriptures i la previsualització viuen a l'eix de compte: {account} és l'account.id que llegeixes a GET /v1/me, i {company} és l'id d'una empresa, un UUID v7 opac, no el seu tax_id. La lectura de facturació del final viu a l'eix d'empresa.

Què compta com a NIF addicional

• El primer NIF mai no compta. L'empresa titular és aquella amb la qual es va obrir el compte i la que contracta el pla. El primer NIF que entra en un compte sense cap NIF actiu no és un NIF addicional.
• Només compten els NIF active. La quantitat facturada és el nombre de NIF actius menys l'empresa titular. Un NIF inactive o archived, i l'empresa sandbox d'un NIF, no compten.
• És igual per on entri. Un NIF que dónes d'alta per l'API o des de l'app, un que reactives i un que reps per traspàs costen el mateix un cop actius.

La quantitat segueix sola la teva cartera, i una reconciliació horària la manté alineada amb el nombre de NIF addicionals actius. La reconciliació corregeix la quantitat sense cobrar ni abonar res.

Preu i plans

Un NIF addicional costa 15.00 EUR al mes abans d'IVA. Es factura sempre de manera mensual, fins i tot quan el pla del compte és anual, i viu en la seva pròpia subscripció del compte (additional-nifs), separada de la que paga el pla.

Només alguns plans admeten NIF addicionals:

El pla d'un NIF addicional no segueix el del compte. En un compte Profesional (empresario) o Avanzado (integral), cada NIF addicional té el pla Profesional (empresario); només el NIF titular té el pla del compte.

El compte necessita a més un pla vigent. Sense cap (cancel·lat o caducat) la resposta és 402 additional_nif_plan_required. Un trial compta com a pla vigent, consulta la regla del trial. El pla es comprova dins de cada operació i no a través dels scopes: els scopes companies:* no depenen del pla.

El topall

El teu contracte pot fixar un nombre màxim de NIF addicionals actius per al compte. Es guarda al compte com a max_additional_nifs. Per defecte està buit, cosa que vol dir sense topall, i només el fixem nosaltres, per contracte. L'API no el retorna.

Quan afegir un NIF més, o diversos alhora, deixaria el compte per sobre del topall, la resposta és 422 business_rule_violation amb subcode additional_nif_limit_reached, abans de cobrar o canviar res. Un lot es rebutja sencer: mai no deixa passar uns NIF i atura els altres.

{
  "error": {
    "type": "invalid_request_error",
    "code": "business_rule_violation",
    "subcode": "additional_nif_limit_reached",
    "message": "Has alcanzado el máximo de NIF adicionales de tu contrato (5).",
    "doc_url": "https://docs.factuarea.com/guides/errors#business_rule_violation",
    "request_id": "req_c15e7a1c0d9b3f46a28c060000"
  }
}

Les quatre escriptures

Quatre operacions poden afegir un NIF addicional actiu. Passen pel mateix gate, amb els mateixos codis i en el mateix ordre.

El que comparteixen les quatre:

• Idempotency-Key és obligatòria. Una petició sense ella es rebutja amb 422 idempotency_key_required abans d'executar cap lògica de negoci.
• Qui ho pot demanar. La credencial ha d'arribar a l'empresa titular del compte, que és la que paga. Per donar d'alta o reactivar, la persona que va emetre la clau ha de tenir a més el rol de titular (owner) o d'administrador (admin) al compte, amb la secció user_management disponible; per acceptar un traspàs, necessita un rol administratiu en almenys un NIF del compte receptor. Si no, la resposta és 403 forbidden_action, abans de cobrar o canviar res.
• Una credencial de només lectura. Si la credencial només té accés view al NIF, reactivar o acceptar un traspàs retorna 403 company_read_only.
• El lot és tot o res. company_ids admet entre 1 i 1000 ids. Cada NIF es valida abans de cobrar res: ha de pertànyer al compte i estar inactive (si no, 422 business_rule_violation), i un que no sigui del compte retorna 404 per a tot el lot. Els NIF addicionals del lot es cobren junts en una sola factura.

curl -X POST https://api.factuarea.com/v1/accounts/$ACCOUNT_ID/companies \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Talleres García SL",
    "tax_id": "B12345674"
  }'

El 201 és la nova company, amb status: "active". El seu paid_until és el final del període pel qual està pagat, o null quan no es va cobrar (un trial, per exemple). Un tax_id ja registrat al teu compte retorna 409 resource_already_exists; un que pertany a un altre compte retorna 422 business_rule_violation i es mou amb un traspàs de NIF.

El gate i els seus quatre codis

Abans de crear, reactivar, moure o cobrar res, cada escriptura passa pel gate del NIF addicional. Comprova en aquest ordre i s'atura al primer error:

1. Qui paga. El compte s'ha de pagar a si mateix.
2. El pla. El compte necessita un pla vigent que admeti NIF addicionals.
3. El topall. El compte s'ha de quedar dins de max_additional_nifs.
4. El càrrec. En mode de producció amb subscripció de pagament, el càrrec s'ha de completar.

Tot rebuig arriba abans de qualsevol càrrec i no escriu res: no es crea, reactiva ni mou cap NIF, i no es cobra res. Els quatre codis del gate:

Altres rebutjos que pots trobar en les mateixes escriptures:

Quan es cobra

En mode de producció amb subscripció de pagament el NIF addicional es cobra a l'acte a la subscripció additional-nifs del compte: prorratejat pel que resta del període actual o, quan és el primer i es crea la subscripció, el primer mes complet. Sense mètode de pagament registrat l'escriptura es rebutja amb 402 payment_method_required:

{
  "error": {
    "type": "payment_required_error",
    "code": "payment_method_required",
    "message": "La cuenta no tiene un método de pago configurado para cobrar el NIF adicional: configúralo y vuelve a intentarlo.",
    "details": {
      "payment_setup_url": "https://billing.stripe.com/p/session/live_YWNjdF8xS2ZHM0RLb0h4RXBGV3lY"
    },
    "doc_url": "https://docs.factuarea.com/guides/errors#payment_method_required",
    "request_id": "req_c15e7a1c0d9b3f46a28c010000"
  }
}

Un cobrament rebutjat és 402 additional_nif_charge_failed. Si la mateixa operació falla després del càrrec, el càrrec es compensa: mai no et quedes pagant un NIF que no es va afegir.

No es cobra res quan el compte és al seu trial, quan és un compte enterprise facturat per contracte sense subscripció de pagament, quan és un compte de proves (el gate no crida el proveïdor de pagament, consulta comptes gestionats de proves) o quan el NIF continua cobert.

Cobertura. paid_until a l'empresa és el final del període pel qual el NIF està pagat. Cada renovació pagada l'amplia, per a tots els NIF addicionals actius, fins al final del nou període. Desactivar un NIF (POST /v1/accounts/{account}/companies/{company}/deactivate) l'allibera sense crèdit però en conserva la cobertura, així que reactivar-lo abans de paid_until és gratis. Quan la cobertura caduca, paid_until és null i reactivar-lo es torna a cobrar. Desactivar mai no es factura ni retorna 402, i el compte ha de conservar almenys un NIF actiu (422 business_rule_violation amb subcode account_must_keep_one_nif).

La regla del trial

Mentre el compte és al seu trial, els NIF addicionals són gratis, s'afegeixin com s'afegeixin. Això cobreix la finestra de prova sense subscripció i una subscripció de pla que és al seu període de prova (amb targeta registrada, estat trialing). La previsualització respon included_in_trial: true sense càrrec.

Quan el compte comença a pagar, perquè el trial acaba i el primer cobrament es completa o perquè se subscriu directament a un pla de pagament, els NIF addicionals que tenia gratis passen a inactive, sense cobrament ni crèdit. Ho fem perquè no es cobri res que no hagis triat. Dos detalls:

• Un NIF el paid_until del qual continua en el futur segueix actiu, perquè ja estava pagat.
• La regla només actua en mode de producció sobre un compte que cobra de debò: un compte de proves conserva els seus NIF.

Després reactives els que vols conservar, un a un o en lot, i cada reactivació es cobra com qualsevol altra.

Quan canvia el teu pla

La vida del pla arrossega els NIF addicionals:

• Un pla que no els admet. Baixar a un pla sense NIF addicionals, o un pla que caduca (un trial vençut, un pagament que no es va poder recuperar, una subscripció eliminada), desactiva els NIF addicionals actius, mai l'empresa titular, i els allibera sense crèdit. Amb la caducitat, la subscripció additional-nifs es cancel·la a més de manera immediata. Passar entre plans que sí els admeten, com d'enterprise a empresario, no canvia res.
• Cancel·lar el pla programa la cancel·lació de la subscripció de NIF addicionals per a la mateixa data, a final de període o de manera immediata, igual que el pla. Reprendre el pla treu aquesta cancel·lació programada mentre el compte conservi NIF addicionals actius.
• No tornen sols. Un NIF desactivat així es reactiva amb un pla que l'admeti, i la reactivació es cobra.

Previsualització del càrrec

GET /v1/accounts/{account}/companies/seat-charge-preview retorna el que costaria la següent alta, calculat amb la propera factura de l'empresa titular, sense cobrar. Requereix companies:read.

curl -G https://api.factuarea.com/v1/accounts/$ACCOUNT_ID/companies/seat-charge-preview \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  --data-urlencode "count=3"

{
  "data": {
    "object": "seat_charge_preview",
    "amount": "7.50",
    "tax_amount": "1.58",
    "total": "9.08",
    "tax_rate": 21,
    "currency": "EUR",
    "next_invoice_date": "2026-04-01T00:00:00Z",
    "requires_payment_method": false,
    "requires_active_plan": false,
    "included_in_trial": false,
    "already_covered": false,
    "is_first_seat": false,
    "recurring_quantity": 3,
    "recurring_base_cents": 4500,
    "recurring_total_cents": 5445
  }
}

La previsualització és una lectura: mai no retorna 402 i no avalua el pla ni el topall de les escriptures. Un NIF que no és addicional, un compte de proves, un compte sense pla vigent i un el pla del qual no admet NIF addicionals previsualitzen 0. Retorna 403 billing_managed_by_provider quan el proveïdor paga la facturació del compte, i 404 quan un valor de company_ids no és un NIF del compte.

Rebre un NIF per traspàs

Acceptar un traspàs de NIF amb POST /v1/accounts/{account}/nif-transfers/accept afegeix el NIF entrant al compte receptor com a NIF addicional. El gate del compte receptor s'executa abans de moure res. Un rebuig deixa el traspàs vigent i el NIF al compte emissor, així que pots arreglar la causa, com un pla o un mètode de pagament, i acceptar de nou amb el mateix secret.

En mode de producció amb subscripció de pagament el NIF es cobra en acceptar, i si el trasllat falla després del càrrec, el càrrec es compensa. La part receptora necessita un rol administratiu en almenys un NIF del seu compte, i una credencial que arribi a l'empresa titular del compte receptor amb accés d'escriptura (403 forbidden_action, o 403 company_read_only quan és de només lectura).

Hi ha una excepció: un compte registrat sense NIF rep el NIF com a empresa titular seva, i no paga res.

Comptes pagats pel seu proveïdor

Un compte gestionat la gestió del qual és vigent i la facturació del qual paga el seu proveïdor no compra res pel seu compte. El seu titular rep 403 billing_managed_by_provider a les quatre escriptures i a la previsualització.

En lloc seu, el proveïdor afegeix els NIF. Les persones del compte del proveïdor amb accés operate al compte gestionat els donen d'alta i els reactiven pels mateixos endpoints, amb l'{account} del compte gestionat, i el càrrec va a la subscripció managed-accounts del proveïdor, prorratejat a l'acte. El gate continua jutjant el propi compte gestionat: el seu pla (emprendedor rep 403 additional_nif_not_in_plan), el seu topall i el mètode de pagament del proveïdor (402 payment_method_required si no en té cap, 402 additional_nif_charge_failed quan es rebutja el cobrament). Els comptes de proves i els comptes gestionats enterprise, facturats per contracte, no es cobren.

Quan el client assumeix el pagament, o la gestió acaba després de la reclamació, el compte torna a pagar-se a si mateix i tot l'anterior s'aplica de nou al seu titular. El que paga el proveïdor es troba a preu dels comptes gestionats i canvi de pagador.

Llegir el que pagues

GET /v1/companies/{company}/billing (scope account:read) retorna la instantània de subscripció del compte. El seu bloc gestoria_seats descriu la subscripció de NIF addicionals. El camp conserva el seu nom públic original per no trencar les integracions existents, i no hi ha àlies: malgrat el nom, compta NIF addicionals i res més.

{
  "gestoria_seats": {
    "status": "active",
    "quantity": 4,
    "active_companies": 4,
    "unit_amount": "15.00",
    "tax_rate": 21,
    "tax_amount": "3.15",
    "total_per_seat": "18.15",
    "recurring_total": "72.60",
    "currency": "EUR",
    "billing_interval": "month",
    "next_invoice_at": "2026-07-15T10:00:00+00:00",
    "ends_at": null
  }
}

Els imports són euros com a cadenes amb dos decimals, no cèntims enters. Són null quan el cost no es pot resoldre (un compte enterprise fora del proveïdor de pagament, una sandbox, sense pla vigent): mai un 0 enganyós. El bloc sencer és null quan el compte no té subscripció de NIF addicionals ni NIF addicionals actius, i en un trial amb NIF addicionals actius mostra status: "none" i quantity: 0. Una empresa la facturació de la qual paga una altra empresa respon managed: true amb gestoria_seats: null, així que el cobrament de qui paga mai no es filtra.

Pròxims passos