Facturación de asientos de empleado

El add-on de facturación por empleado — una suscripción mensual dedicada cuyo número de asientos sigue a tus empleados activos, con un asiento pagado que cubre todo el periodo.

Los empleados se facturan mediante un add-on por asiento, 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 sigue el número de empleados activos, y contratarlo activa el módulo control_horario. Todos los endpoints viven bajo https://api.factuarea.com/v1 y usan employees:read (estado, preview) o employees:write (contratar, cambiar cantidad, cancelar).

Cómo se facturan los asientos

Un asiento pagado cubre todo el periodo de facturación. El número de asientos sigue tu plantilla activa de forma automática:

Activar o dar de alta un empleado cuyo asiento no está cubierto cobra un asiento prorrateado por lo que resta del periodo.
Dar de baja un empleado libera el asiento sin crédito (el periodo ya está pagado) pero conserva su cobertura, así que reactivarlo dentro del mismo periodo es gratis.
Cada renovación del periodo refresca la cobertura de los empleados activos en ese momento.

La cantidad se mantiene sincronizada con el número real de activos mediante eventos del empleado y una reconciliación horaria, así que rara vez necesitas fijarla a mano.

Para una cuenta enterprise facturada por contrato (sin suscripción Stripe), el add-on se concede gratis: sin cobro, sin método de pago exigido, y el módulo control_horario se habilita igualmente. Cancelar retira el módulo de inmediato.

Consultar el estado de facturación

GET /v1/employee-seats devuelve el estado del add-on: si la suscripción está activa (subscribed), cuántos asientos se facturan (quantity), cuántos empleados están activos, y el coste recurrente por asiento con IVA incluido. Los importes van en céntimos (unidades menores) y son null —nunca un 0 engañoso— cuando el coste no es resoluble (sin suscribir, sin plan activo, enterprise fuera de Stripe, sandbox).

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

Previsualizar el cargo

GET /v1/employee-seats/preview devuelve el importe por asiento prorrateado por activar o dar de alta, calculado desde la próxima factura de Stripe, sin cobrar. Nunca lanza error — degrada a un preview neutro.

Parámetro	Notas
`count`	Preview en lote para N asientos (≥1, hasta 1000).
`employee_ids`	Preview consciente de la cobertura por UUID v7: los empleados aún cubiertos este periodo cuestan `0` (`already_covered: true`).

amount es la base imponible en céntimos; requires_payment_method es true cuando no hay método de pago archivado.

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

POST /v1/employee-seats/subscribe contrata (opt-in): crea la suscripción mensual employee-seats con quantity igual a tus empleados activos y cobra el primer periodo con el método de pago archivado. El cobro es atómico — si no cuaja, no se contrata nada:

Sin método de pago → 402 employee_seat_payment_method_required; el envoltorio 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/employee-seats/subscribe \
  -H "Authorization: Bearer $FACTUAREA_API_KEY"

Si contratar devuelve 402 employee_seat_payment_method_required, envía al usuario al payment_setup_url del error, deja que añada una tarjeta y reintenta. No se cobra ni se contrata nada hasta que el primer periodo cuaja.

Sincronizar la cantidad y cancelar

POST /v1/employee-seats/change-quantity reconcilia el número de asientos facturados con el número real de empleados activos (un SET sin prorrateo ni factura). Es idempotente — un no-op cuando la cantidad ya coincide.

POST /v1/employee-seats/cancel cancela el add-on a fin de periodo: el mes en curso ya está pagado, así que subscribed sigue true hasta que el periodo termina, y la cobertura por empleado se purga entonces. La suscripción del plan nunca se toca.

curl -X POST https://api.factuarea.com/v1/employee-seats/cancel \
  -H "Authorization: Bearer $FACTUAREA_API_KEY"

Consulta los esquemas en la Referencia de API.

Flujo típico

Previsualiza el cargo de los asientos que vas a activar.
Contrata el add-on (primer periodo cobrado de forma atómica).
Añade o quita empleados — la cantidad se autosincroniza; reconcilia de forma explícita con change-quantity si hace falta.
Lee el estado para mostrar los asientos facturados y el coste por asiento.
Cancela a fin de periodo cuando ya no lo necesites.

Próximos pasos

Visión general del control horario — el rol de empleado solo-portal y todo el sistema.
Empresas gestionadas — facturación por asiento de las empresas hijas de gestoría.