NIF adicionales

Tu cuenta se abre con un NIF, su empresa titular. Cada uno de los demás NIF que opera la cuenta es un NIF adicional, tanto si lo das de alta como si lo reactivas o lo recibes por un traspaso de NIF. Los NIF adicionales se facturan como un add-on mensual, así que añadir uno puede cobrar a tu cuenta en el acto. Esta guía explica lo que pagas, qué planes los admiten, el tope, la regla del trial, la vista previa y los cuatro códigos que rechazan un alta.

Las escrituras y la vista previa viven en el eje de cuenta: {account} es el account.id que lees en GET /v1/me, y {company} es el id de una empresa, un UUID v7 opaco, no su tax_id. La lectura de facturación del final vive en el eje de empresa.

Qué cuenta como NIF adicional

• El primer NIF nunca cuenta. La empresa titular es aquella con la que se abrió la cuenta y la que contrata el plan. El primer NIF que entra en una cuenta sin ningún NIF activo no es un NIF adicional.
• Solo cuentan los NIF active. La cantidad facturada es el número de NIF activos menos la empresa titular. Un NIF inactive o archived, y la empresa sandbox de un NIF, no cuentan.
• Da igual por dónde entre. Un NIF que das de alta por la API o desde la app, uno que reactivas y uno que recibes por traspaso cuestan lo mismo una vez activos.

La cantidad sigue sola a tu cartera, y una reconciliación horaria la mantiene alineada con el número de NIF adicionales activos. La reconciliación corrige la cantidad sin cobrar ni abonar nada.

Precio y planes

Un NIF adicional cuesta 15.00 EUR al mes antes de IVA. Se factura siempre de forma mensual, incluso cuando el plan de la cuenta es anual, y vive en su propia suscripción de la cuenta (additional-nifs), separada de la que paga el plan.

Solo algunos planes admiten NIF adicionales:

El plan de un NIF adicional no sigue al de la cuenta. En una cuenta Profesional (empresario) o Avanzado (integral), cada NIF adicional tiene el plan Profesional (empresario); solo el NIF titular tiene el plan de la cuenta.

La cuenta necesita además un plan vigente. Sin ninguno (cancelado o caducado) la respuesta es 402 additional_nif_plan_required. Un trial cuenta como plan vigente, consulta la regla del trial. El plan se comprueba dentro de cada operación y no a través de los scopes: los scopes companies:* no dependen del plan.

El tope

Tu contrato puede fijar un número máximo de NIF adicionales activos para la cuenta. Se guarda en la cuenta como max_additional_nifs. Por defecto está vacío, lo que significa sin tope, y solo lo fijamos nosotros, por contrato. La API no lo devuelve.

Cuando añadir un NIF más, o varios a la vez, dejaría la cuenta por encima del tope, la respuesta es 422 business_rule_violation con subcode additional_nif_limit_reached, antes de cobrar o cambiar nada. Un lote se rechaza entero: nunca deja pasar unos NIF y frena otros.

{
  "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"
  }
}

Las cuatro escrituras

Cuatro operaciones pueden añadir un NIF adicional activo. Pasan por el mismo gate, con los mismos códigos y en el mismo orden.

Lo que comparten las cuatro:

• Idempotency-Key es obligatoria. Una petición sin ella se rechaza con 422 idempotency_key_required antes de ejecutar ninguna lógica de negocio.
• Quién puede pedirlo. La credencial debe alcanzar la empresa titular de la cuenta, que es la que paga. Para dar de alta o reactivar, la persona que emitió la clave debe tener además el rol de titular (owner) o de administrador (admin) en la cuenta, con la sección user_management disponible; para aceptar un traspaso, necesita un rol administrativo en al menos un NIF de la cuenta receptora. Si no, la respuesta es 403 forbidden_action, antes de cobrar o cambiar nada.
• Una credencial de solo lectura. Si la credencial solo tiene acceso view al NIF, reactivar o aceptar un traspaso devuelve 403 company_read_only.
• El lote es todo o nada. company_ids admite entre 1 y 1000 ids. Cada NIF se valida antes de cobrar nada: debe pertenecer a la cuenta y estar inactive (si no, 422 business_rule_violation), y uno que no sea de la cuenta devuelve 404 para todo el lote. Los NIF adicionales del lote se cobran juntos 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 es la nueva company, con status: "active". Su paid_until es el final del periodo por el que está pagado, o null cuando no se cobró (un trial, por ejemplo). Un tax_id ya registrado en tu cuenta devuelve 409 resource_already_exists; uno que pertenece a otra cuenta devuelve 422 business_rule_violation y se mueve con un traspaso de NIF.

El gate y sus cuatro códigos

Antes de crear, reactivar, mover o cobrar nada, cada escritura pasa por el gate del NIF adicional. Comprueba en este orden y se detiene en el primer fallo:

1. Quién paga. La cuenta tiene que pagarse a sí misma.
2. El plan. La cuenta necesita un plan vigente que admita NIF adicionales.
3. El tope. La cuenta debe quedarse dentro de max_additional_nifs.
4. El cargo. En modo producción con suscripción de pago, el cargo tiene que completarse.

Todo rechazo llega antes de cualquier cargo y no escribe nada: no se crea, reactiva ni mueve ningún NIF, y no se cobra nada. Los cuatro códigos del gate:

Otros rechazos que puedes encontrar en las mismas escrituras:

Cuándo se cobra

En modo producción con suscripción de pago el NIF adicional se cobra en el acto en la suscripción additional-nifs de la cuenta: prorrateado por lo que resta del periodo actual o, cuando es el primero y se crea la suscripción, el primer mes completo. Sin método de pago registrado la escritura se rechaza con 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 cobro rechazado es 402 additional_nif_charge_failed. Si la propia operación falla después del cargo, el cargo se compensa: nunca te quedas pagando un NIF que no se añadió.

No se cobra nada cuando la cuenta está en su trial, cuando es una cuenta enterprise facturada por contrato sin suscripción de pago, cuando es una cuenta de pruebas (el gate no llama al proveedor de pago, consulta cuentas gestionadas de pruebas) o cuando el NIF sigue cubierto.

Cobertura. paid_until en la empresa es el final del periodo por el que el NIF está pagado. Cada renovación pagada lo amplía, para todos los NIF adicionales activos, hasta el final del nuevo periodo. Desactivar un NIF (POST /v1/accounts/{account}/companies/{company}/deactivate) lo libera sin crédito pero conserva su cobertura, así que reactivarlo antes de paid_until es gratis. Cuando la cobertura caduca, paid_until es null y reactivarlo se vuelve a cobrar. Desactivar nunca se factura ni devuelve 402, y la cuenta debe conservar al menos un NIF activo (422 business_rule_violation con subcode account_must_keep_one_nif).

La regla del trial

Mientras la cuenta está en su trial, los NIF adicionales son gratis, se añadan como se añadan. Eso cubre la ventana de prueba sin suscripción y una suscripción de plan que está en su periodo de prueba (con tarjeta registrada, estado trialing). La vista previa responde included_in_trial: true sin cargo.

Cuando la cuenta empieza a pagar, porque el trial termina y el primer cobro se completa o porque se suscribe directamente a un plan de pago, los NIF adicionales que tenía gratis pasan a inactive, sin cobro ni crédito. Lo hacemos para que no se cobre nada que no hayas elegido. Dos detalles:

• Un NIF cuyo paid_until sigue en el futuro continúa activo, porque ya estaba pagado.
• La regla solo actúa en modo producción sobre una cuenta que cobra de verdad: una cuenta de pruebas conserva sus NIF.

Después reactivas los que quieres conservar, uno a uno o en lote, y cada reactivación se cobra como cualquier otra.

Cuando cambia tu plan

La vida del plan arrastra a los NIF adicionales:

• Un plan que no los admite. Bajar a un plan sin NIF adicionales, o un plan que caduca (un trial vencido, un pago que no se pudo recuperar, una suscripción eliminada), desactiva los NIF adicionales activos, nunca la empresa titular, y los libera sin crédito. Con la caducidad, la suscripción additional-nifs se cancela además de inmediato. Pasar entre planes que sí los admiten, como de enterprise a empresario, no cambia nada.
• Cancelar el plan programa la cancelación de la suscripción de NIF adicionales para la misma fecha, a fin de periodo o de inmediato, igual que el plan. Reanudar el plan quita esa cancelación programada mientras la cuenta conserve NIF adicionales activos.
• No vuelven solos. Un NIF desactivado así se reactiva con un plan que lo admita, y la reactivación se cobra.

Vista previa del cargo

GET /v1/accounts/{account}/companies/seat-charge-preview devuelve lo que costaría la siguiente alta, calculado con la próxima factura de la empresa titular, sin cobrar. Requiere 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 vista previa es una lectura: nunca devuelve 402 y no evalúa el plan ni el tope de las escrituras. Un NIF que no es adicional, una cuenta de pruebas, una cuenta sin plan vigente y una cuyo plan no admite NIF adicionales previsualizan 0. Devuelve 403 billing_managed_by_provider cuando el proveedor paga la facturación de la cuenta, y 404 cuando un valor de company_ids no es un NIF de la cuenta.

Recibir un NIF por traspaso

Aceptar un traspaso de NIF con POST /v1/accounts/{account}/nif-transfers/accept añade el NIF entrante a la cuenta receptora como NIF adicional. El gate de la cuenta receptora se ejecuta antes de mover nada. Un rechazo deja el traspaso vigente y el NIF en la cuenta emisora, así que puedes arreglar la causa, como un plan o un método de pago, y aceptar de nuevo con el mismo secreto.

En modo producción con suscripción de pago el NIF se cobra al aceptar, y si el traslado falla después del cargo, el cargo se compensa. La parte receptora necesita un rol administrativo en al menos un NIF de su cuenta, y una credencial que alcance la empresa titular de la cuenta receptora con acceso de escritura (403 forbidden_action, o 403 company_read_only cuando es de solo lectura).

Hay una excepción: una cuenta registrada sin NIF recibe el NIF como su empresa titular, y no paga nada.

Cuentas pagadas por su proveedor

Una cuenta gestionada cuya gestión está vigente y cuya facturación paga su proveedor no compra nada por su cuenta. Su titular recibe 403 billing_managed_by_provider en las cuatro escrituras y en la vista previa.

En su lugar, el proveedor añade los NIF. Las personas de la cuenta del proveedor con acceso operate a la cuenta gestionada los dan de alta y los reactivan por los mismos endpoints, con el {account} de la cuenta gestionada, y el cargo va a la suscripción managed-accounts del proveedor, prorrateado en el acto. El gate sigue juzgando a la propia cuenta gestionada: su plan (emprendedor recibe 403 additional_nif_not_in_plan), su tope y el método de pago del proveedor (402 payment_method_required si no tiene ninguno, 402 additional_nif_charge_failed cuando se rechaza el cobro). Las cuentas de pruebas y las cuentas gestionadas enterprise, facturadas por contrato, no se cobran.

Cuando el cliente asume el pago, o la gestión termina tras la reclamación, la cuenta vuelve a pagarse a sí misma y todo lo anterior se aplica de nuevo a su titular. Lo que paga el proveedor está en precio de las cuentas gestionadas y cambio de pagador.

Leer lo que pagas

GET /v1/companies/{company}/billing (scope account:read) devuelve la instantánea de suscripción de la cuenta. Su bloque gestoria_seats describe la suscripción de NIF adicionales. El campo conserva su nombre público original para no romper las integraciones existentes, y no hay alias: pese al nombre, cuenta NIF adicionales y nada 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
  }
}

Los importes son euros como cadenas con dos decimales, no céntimos enteros. Son null cuando el coste no se puede resolver (una cuenta enterprise fuera del proveedor de pago, una sandbox, sin plan vigente): nunca un 0 engañoso. El bloque entero es null cuando la cuenta no tiene suscripción de NIF adicionales ni NIF adicionales activos, y en un trial con NIF adicionales activos muestra status: "none" y quantity: 0. Una empresa cuya facturación paga otra empresa responde managed: true con gestoria_seats: null, así que el cobro de quien paga nunca se filtra.

Próximos pasos