Facturación de plazas de empleado

Los empleados se facturan mediante plazas contratadas, no por el límite users del plan — un empleado nunca computa contra ese límite. El add-on es una suscripción mensual dedicada (employee-seats), totalmente separada de la suscripción del plan: su quantity es el número de plazas contratadas de la cuenta, y son solo facturación: el módulo control_horario lo da el plan (Profesional, Avanzado y Enterprise; un superadmin también puede concederlo a mano) y sin él no se pueden comprar plazas (403 employee_seats_not_in_plan). La suscripción pertenece a la cuenta que paga, no a uno de sus NIF, así que los endpoints viven bajo https://api.factuarea.com/v1/accounts/{account}/employee-seats — {account} es el account.id que lees en GET /v1/me — y usan employees:read (estado, preview) o employees:write (comprar o reducir plazas, contratar, cambiar cantidad, cancelar). Quién paga y quién puede operar explica de qué cuenta se trata.

Plazas contratadas, ocupadas y libres

La cuenta elige cuántas plazas paga, y ese número es lo que factura la suscripción:

• Las plazas contratadas son las que la cuenta ha comprado y por las que se le factura (quantity de la suscripción employee-seats).
• Las plazas ocupadas son los empleados active de todos los NIF de la cuenta.
• Las plazas libres son las contratadas menos las ocupadas.

En una cuenta que se cobra hay siempre al menos tantas plazas contratadas como ocupadas. Desactivar a un empleado libera una plaza, pero no cambia las contratadas ni la factura: para pagar menos, reduce las plazas.

Cómo se facturan las plazas

Dar de alta, activar o reactivar a un empleado ocupa una plaza libre: sin cobro, sin método de pago y sin llamar a la pasarela de pago. Nunca se cobra en el alta de un empleado; solo se cobra al comprar plazas.

• Dar de alta o reactivar a un empleado ocupa una plaza libre. Si no hay ninguna, mira qué pasa sin plaza libre.
• Desactivar a un empleado libera la plaza y deja las contratadas y la factura como están. La plaza sigue disponible para la siguiente incorporación.
• Cada renovación factura las plazas contratadas, estén ocupadas o no.

Una cuenta que ya tenía el add-on empieza con las plazas que pagaba, así que su factura no cambia.

Cuándo se cobran las plazas

Las plazas se cobran solo cuando las compras, nunca al dar de alta o reactivar a un empleado. Comprar se aplica siempre que tu plan factura:

• una suscripción de plan de pago, también cuando está past_due (un pago pendiente no suspende la facturación de plazas);
• un plan Esencial, Profesional o Avanzado concedido por Factuarea sin suscripción abierta.

Solo estas cuentas no se cobran y sus empleados ni consumen ni compran plazas:

GET /v1/accounts/{account}/employee-seats lo informa en seats_billable: true significa que tu plan debe pagar por plaza, false es un estado legítimo sin cobro.

La primera compra de plazas

No necesitas contratar antes de añadir empleados. En una cuenta que se cobra y no tiene suscripción employee-seats, la primera compra de plazas la crea con la nueva cantidad y cobra el primer periodo.

Los empleados que ya estaban activos cuando se creó la suscripción no se cobran además: en una cuenta existente quedan cubiertos por las plazas que ya pagaba, y una cuenta con empleados activos y sin plazas contratadas empieza sin ninguna hasta que las compre.

Comprar plazas

PATCH /v1/accounts/{account}/employee-seats con {"contracted_seats": N} fija las plazas contratadas a un valor absoluto. Cuando N es mayor que las actuales, las que faltan se compran ahora:

• El cobro es inmediato y prorrateado por lo que resta del periodo, con la tarjeta de la cuenta.
• Idempotency-Key es obligatoria: un reintento con la misma clave no cobra dos veces.
• La respuesta es el estado con su bloque seats.
• Sin método de pago la llamada responde 402 employee_seat_payment_method_required y con un cobro rechazado 402 employee_seat_charge_failed; en ambos casos no se compra nada.

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

Desde MCP, la tool update_employee_seats recibe el mismo contracted_seats y un idempotency_key. Previsualiza el cobro antes con contracted_seats. Cualquier compra anula una reducción pendiente.

Reducir plazas

El mismo PATCH con un número menor programa una reducción. Se permite cualquier cantidad, desde 0: no hay suelo.

• Sin llamar a la pasarela de pago y sin abono. La reducción queda como una reducción pendiente que se aplica en la renovación, y las plazas siguen disponibles hasta entonces.
• Por debajo de las ocupadas, envía deactivate: una lista de UUID de exactamente ocupadas − cantidad empleados activos de la cuenta. Si no cuadra, la respuesta es 422 contracted_seats_selection_required con param=deactivate y details product, requested, occupied, required, selected e invalid.
• Paquete de oferta. Si, en la renovación, la reducción deja el producto por debajo del mínimo de una línea de un paquete de oferta aplicado, todo el paquete terminaría. La vista previa publica offer_package_loss y la escritura exige accept_offer_package_loss: true; sin ella la respuesta es 422 offer_package_loss_unconfirmed con param=accept_offer_package_loss y details product, package_id, name, effective_at y lines (cada una con concept, from_price, to_price e interval). El mínimo pactado nunca limita la reducción; solo decide si el paquete termina.
• Reducción pendiente. El estado muestra pending_reduction con contracted, effective_at y deactivations (id y name). Unos días antes de la renovación el titular de la cuenta recibe un aviso con esos nombres, y en la renovación una tarea desactiva a los empleados elegidos y fija la cantidad.
• Anularla o sustituirla. Una compra, un PATCH a la cantidad actual, o un alta, activación, reactivación, lote o traspaso de NIF que ocupe lo que la reducción iba a quitar, la anula; el evento account.seats_updated lleva entonces cause=reduction_superseded. Otro PATCH menor la sustituye.
• Reducir a 0 exige deactivate con todas las plazas ocupadas (y confirmar la pérdida del paquete, si lo hay) y cancela el add-on a fin de periodo.

curl -X PATCH https://api.factuarea.com/v1/accounts/$ACCOUNT_ID/employee-seats \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"contracted_seats": 3, "deactivate": ["0198f2d4-1b7e-7c3a-9d41-6a5e8b2c4f10"]}'

Crear un empleado sin plaza libre

Cuando la cuenta se cobra y no hay plaza libre, decide la superficie:

• La aplicación web responde 422 contracted_seats_exhausted con details product, contracted, occupied, free, required y missing, sin crear ni cobrar nada. La aplicación lleva entonces a comprar plazas primero y a crear después.
• La API v1 y MCP compran las plazas que faltan con un cobro prorrateado y después crean al empleado, con los mismos 402 de siempre cuando no hay tarjeta o el cobro falla (mira los errores de pago). La plaza comprada queda contratada. Un reintento no cobra dos veces.

Envía una Idempotency-Key en las altas: sin ella, un reintento tras un alta que sí llegó a crearse crea otro empleado, porque la API no distingue un reintento de un alta nueva.

Empleados creados durante la prueba

Durante una prueba activa no se cobra nada y los empleados que creas no consumen plazas. Puedes elegir las plazas que contratarás sin cobro: se cobran cuando la empresa empieza a pagar.

Cuando empieza el cobro, los empleados activos ocupan las plazas contratadas que haya. Los más antiguos siguen active y los que no caben pasan a inactive sin cargo; con 0 plazas contratadas, todos. Reactiva a los que quieras conservar cuando hayas comprado plazas.

Añadir una tarjeta durante la prueba no desactiva a nadie; solo lo hace el inicio del cobro.

Errores de pago

Una compra de plazas es atómica: cuando falla, no se compra, no se crea ni se cobra nada.

Quién paga y quién puede operar

La suscripción la tiene la cuenta que paga, que normalmente es la propia cuenta. Se cobra al método de pago de la cuenta, y solo la opera un titular o un administrador:

• Para comprar o reducir plazas, contratar, cancelar o cambiar la cantidad, la persona que emitió la clave tiene que ser hoy titular o administrador de la cuenta.
• Para leer o escribir, el ámbito de la clave tiene que incluir la empresa titular de la cuenta.

Si no, la llamada responde 403 forbidden_action y no cambia nada. Una clave fact_test_ lee el estado y la vista previa, pero la actualización, subscribe, cancel y change-quantity responden 403 live_credential_required sin cambiar nada: mira el modo de prueba.

Una cuenta gestionada que paga su proveedor. Para una cuenta gestionada real que paga su proveedor, las plazas de sus empleados no se compran en la cuenta. Van en la suscripción managed-accounts del proveedor, al precio de la plaza, y su cantidad sigue a los empleados activos de la cuenta sea cual sea el nivel de acceso del proveedor. El cliente no puede operar el add-on, porque lo que cambiaría está en la factura del proveedor:

• La actualización, subscribe, cancel y change-quantity responden 403 billing_managed_by_provider a sus claves, y a sus personas en la aplicación y en MCP, sin cobro y sin cambio.
• status y preview responden el mismo 403, porque la suscripción que leerían es la del proveedor.
• El proveedor tampoco compra esas plazas: {account} de una cuenta gestionada responde 404 account_not_found en estas rutas.

Cuando el cliente asume el pago, la cuenta paga por sí misma y sus titulares y administradores operan el add-on como los de cualquier otra cuenta. Precio de las cuentas gestionadas y cambio de pagador enumera qué más no puede comprar el cliente mientras paga el proveedor.

Consulta el estado de facturación

GET /v1/accounts/{account}/employee-seats devuelve el estado del add-on: si la suscripción está activa ( subscribed ), cuántas plazas se facturan ( quantity, las plazas contratadas), cuántos empleados están activos, y el coste recurrente por plaza con IVA. Los importes son euros como cadena de dos decimales (por ejemplo "1.82") y valen null — nunca un 0 engañoso — cuando el coste no se puede resolver (sin suscripción, sin plan activo, enterprise fuera de Stripe, sandbox).

El bloque seats añade el detalle de las plazas contratadas:

seats es null en una cuenta gestionada que paga su proveedor.

curl https://api.factuarea.com/v1/accounts/$ACCOUNT_ID/employee-seats \
  -H "Authorization: Bearer $FACTUAREA_API_KEY"

Previsualiza el cobro

GET /v1/accounts/{account}/employee-seats/preview devuelve el importe prorrateado de las plazas que compraría una operación, calculado a partir de la próxima factura de Stripe, sin cobrar. Salvo los rechazos de quién paga y la validación de sus parámetros, nunca falla — degrada a una vista previa neutra.

amount es la base imponible en euros como cadena de dos decimales, y tax_amount y total usan el mismo formato; recurring_base_cents y recurring_total_cents siguen en céntimos, como indican sus nombres. requires_payment_method es true cuando no hay método de pago registrado.

La vista previa dice además cómo cubrirían las plazas contratadas la operación:

• free_seats_used, seats_to_buy e included_in_seats (true cuando las plazas libres lo cubren todo, así que amount es 0 y no hace falta tarjeta).
• seats: el bloque seats tras la operación.
• Con contracted_seats, amount y total son el cobro de hoy y recurring_quantity la cantidad de la próxima factura.
• En una reducción, el importe es 0 y la vista previa añade deactivations_required (cuántos empleados debes elegir), cancels_pending_reduction y offer_package_loss.
• already_covered vale siempre false: la cobertura por periodo ya no decide ningún cobro.

curl -G https://api.factuarea.com/v1/accounts/$ACCOUNT_ID/employee-seats/preview \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  --data-urlencode "contracted_seats=8"

Contrata el add-on

POST /v1/accounts/{account}/employee-seats/subscribe garantiza que la suscripción mensual employee-seats existe con las plazas contratadas de la cuenta y cobra el primer periodo con el método de pago registrado. No es obligatorio: la primera compra de plazas crea la suscripción por sí sola. No recibe cantidad: para elegir cuántas plazas quieres, usa PATCH. El cobro es atómico — si no cuaja, no se contrata nada:

• Sin método de pago → 402 employee_seat_payment_method_required; el sobre de error lleva error.details.payment_setup_url para completar el alta de la tarjeta.
• Un cobro rechazado → 402 employee_seat_charge_failed.

curl -X POST https://api.factuarea.com/v1/accounts/$ACCOUNT_ID/employee-seats/subscribe \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Sincroniza la cantidad y cancela

POST /v1/accounts/{account}/employee-seats/change-quantity devuelve la cantidad de la suscripción a las plazas contratadas de la cuenta (un SET sin prorrateo ni factura). Ya no sigue a los empleados activos. Es idempotente — un no-op cuando la cantidad ya coincide.

POST /v1/accounts/{account}/employee-seats/cancel equivale a reducir a 0: cancela el add-on a fin de periodo y acepta los mismos deactivate y accept_offer_package_loss que la reducción.

• Sin deactivate, se desactiva en la renovación a todos los empleados activos (sin 422), y el titular recibe el aviso unos días antes.
• Una lista deactivate que no cuadra con todos responde 422 contracted_seats_selection_required.
• Si cancelar rompe un paquete de oferta no confirmado, la respuesta es 422 offer_package_loss_unconfirmed.

El mes en curso ya está pagado, así que subscribed sigue true hasta que el periodo acaba. La suscripción del plan nunca se toca.

curl -X POST https://api.factuarea.com/v1/accounts/$ACCOUNT_ID/employee-seats/cancel \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Todo cambio de las plazas contratadas o de la reducción pendiente se anuncia con el evento account.seats_updated.

Consulta los esquemas en la Referencia de API, y la operación para fijar las plazas en public-api.v1.employee-seats.update.

Flujo típico

1. Previsualiza el coste de las plazas que quieres con contracted_seats.
2. Asegúrate de que hay un método de pago registrado, para que la compra no se rechace con 402.
3. Compra las plazas con PATCH y una Idempotency-Key.
4. Crea o reactiva empleados: cada uno ocupa una plaza libre, sin cobro.
5. Lee el estado para mostrar las plazas contratadas, ocupadas y libres.
6. Reduce las plazas cuando necesites menos, eligiendo quién sale si hay más empleados que plazas; se aplica en la renovación.

Próximos pasos