Facturació de places d'empleat

L'add-on de facturació per empleat — una subscripció mensual dedicada el nombre de places de la qual segueix els teus empleats actius, amb una plaça pagada que cobreix tot el període.

Els empleats es facturen mitjançant un add-on per plaça, no pel límit users del pla — un empleat mai computa contra aquest límit. L'add-on és una subscripció mensual dedicada (employee-seats), totalment separada de la subscripció del pla: el seu quantity segueix el nombre d'empleats actius, i contractar-lo activa el mòdul control_horario. Tots els endpoints viuen sota https://api.factuarea.com/v1 i usen employees:read (estat, preview) o employees:write (contractar, canviar quantitat, cancel·lar).

Com es facturen les places

Una plaça pagada cobreix tot el període de facturació. El nombre de places segueix la teva plantilla activa de manera automàtica:

Activar o donar d'alta un empleat la plaça del qual no està coberta cobra una plaça prorratejada pel que resta del període.
Donar de baixa un empleat allibera la plaça sense crèdit (el període ja està pagat) però conserva la seva cobertura, així que reactivar-lo dins del mateix període és gratis.
Cada renovació del període refresca la cobertura dels empleats actius en aquell moment.

La quantitat es manté sincronitzada amb el nombre real d'actius mitjançant esdeveniments de l'empleat i una reconciliació horària, així que rarament necessites fixar-la a mà.

Per a un compte enterprise facturat per contracte (sense subscripció Stripe), l'add-on es concedeix gratis: sense cobrament, sense mètode de pagament exigit, i el mòdul control_horario s'habilita igualment. Cancel·lar retira el mòdul de seguida.

Consultar l'estat de facturació

GET /v1/employee-seats retorna l'estat de l'add-on: si la subscripció està activa (subscribed), quantes places es facturen (quantity), quants empleats estan actius, i el cost recurrent per plaça amb IVA inclòs. Els imports van en cèntims (unitats menors) i són null —mai un 0 enganyós— quan el cost no és resoluble (sense subscriure, sense pla actiu, enterprise fora de Stripe, sandbox).

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

Previsualitzar el càrrec

GET /v1/employee-seats/preview retorna l'import per plaça prorratejat per activar o donar d'alta, calculat des de la pròxima factura de Stripe, sense cobrar. Mai llança error — degrada a un preview neutre.

Paràmetre	Notes
`count`	Preview en lot per a N places (≥1, fins a 1000).
`employee_ids`	Preview conscient de la cobertura per UUID v7: els empleats encara coberts aquest període costen `0` (`already_covered: true`).

amount és la base imposable en cèntims; requires_payment_method és true quan no hi ha mètode de pagament arxivat.

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 contracta (opt-in): crea la subscripció mensual employee-seats amb quantity igual als teus empleats actius i cobra el primer període amb el mètode de pagament arxivat. El cobrament és atòmic — si no qualla, no es contracta res:

Sense mètode de pagament → 402 employee_seat_payment_method_required; l'embolcall d'error porta error.details.payment_setup_url per completar l'alta de la targeta.
Un cobrament rebutjat → 402 employee_seat_charge_failed.

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

Si contractar retorna 402 employee_seat_payment_method_required, envia l'usuari al payment_setup_url de l'error, deixa que hi afegeixi una targeta i reintenta. No es cobra ni es contracta res fins que el primer període qualla.

Sincronitzar la quantitat i cancel·lar

POST /v1/employee-seats/change-quantity reconcilia el nombre de places facturades amb el nombre real d'empleats actius (un SET sense prorrateig ni factura). És idempotent — un no-op quan la quantitat ja coincideix.

POST /v1/employee-seats/cancel cancel·la l'add-on a fi de període: el mes en curs ja està pagat, així que subscribed continua true fins que el període acaba, i la cobertura per empleat es purga aleshores. La subscripció del pla mai es toca.

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

Consulta els esquemes a la Referència d'API.

Flux típic

Previsualitza el càrrec de les places que activaràs.
Contracta l'add-on (primer període cobrat de manera atòmica).
Afegeix o treu empleats — la quantitat s'autosincronitza; reconcilia de manera explícita amb change-quantity si cal.
Llegeix l'estat per mostrar les places facturades i el cost per plaça.
Cancel·la a fi de període quan ja no el necessitis.

Pròxims passos

Visió general del control horari — el rol d'empleat només-portal i tot el sistema.
Empreses gestionades — facturació per plaça de les empreses filles de gestoria.