Facturació de places d'empleat

Els empleats es facturen mitjançant places contractades, 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 és el nombre de places contractades del compte, i són només facturació: el mòdul control_horario el dona el pla (Profesional, Avanzado i Enterprise; un superadmin també pot concedir-lo a mà) i sense ell no es poden comprar places (403 employee_seats_not_in_plan). La subscripció pertany al compte que paga, no a un dels seus NIF, així que els endpoints viuen sota https://api.factuarea.com/v1/accounts/{account}/employee-seats — {account} és l'account.id que llegeixes a GET /v1/me — i usen employees:read (estat, preview) o employees:write (comprar o reduir places, contractar, canviar quantitat, cancel·lar). Qui paga i qui pot operar explica de quin compte es tracta.

Places contractades, ocupades i lliures

El compte tria quantes places paga, i aquest nombre és el que factura la subscripció:

• Les places contractades són les que el compte ha comprat i per les quals se li factura (quantity de la subscripció employee-seats).
• Les places ocupades són els empleats active de tots els NIF del compte.
• Les places lliures són les contractades menys les ocupades.

En un compte que es cobra hi ha sempre almenys tantes places contractades com ocupades. Desactivar un empleat allibera una plaça, però no canvia les contractades ni la factura: per pagar menys, redueix les places.

Com es facturen les places

Donar d'alta, activar o reactivar un empleat ocupa una plaça lliure: sense cobrament, sense mètode de pagament i sense cridar la passarel·la de pagament. Mai no es cobra en l'alta d'un empleat; només es cobra en comprar places.

• Donar d'alta o reactivar un empleat ocupa una plaça lliure. Si no n'hi ha cap, consulta què passa sense plaça lliure.
• Desactivar un empleat allibera la plaça i deixa les contractades i la factura tal com són. La plaça continua disponible per a la propera incorporació.
• Cada renovació factura les places contractades, estiguin ocupades o no.

Un compte que ja tenia l'add-on comença amb les places que pagava, així que la seva factura no canvia.

Quan es cobren les places

Les places es cobren només quan les compres, mai en donar d'alta o reactivar un empleat. Comprar s'aplica sempre que el teu pla factura:

• una subscripció de pla de pagament, també quan està past_due (un pagament pendent no suspèn la facturació de places);
• un pla Esencial, Profesional o Avanzado concedit per Factuarea sense subscripció oberta.

Només aquests comptes no es cobren i els seus empleats ni consumeixen ni compren places:

GET /v1/accounts/{account}/employee-seats ho indica a seats_billable: true vol dir que el teu pla ha de pagar per plaça, false és un estat legítim sense càrrec.

La primera compra de places

No cal contractar res abans d'afegir empleats. En un compte que es cobra i no té subscripció employee-seats, la primera compra de places la crea amb la nova quantitat i cobra el primer període.

Els empleats que ja eren actius quan es va crear la subscripció no es cobren a més: en un compte existent queden coberts per les places que ja pagava, i un compte amb empleats actius i sense places contractades comença sense cap fins que les compri.

Comprar places

PATCH /v1/accounts/{account}/employee-seats amb {"contracted_seats": N} fixa les places contractades a un valor absolut. Quan N és més gran que les actuals, les que falten es compren ara:

• El cobrament és immediat i prorratejat pel que resta del període, amb la targeta del compte.
• Idempotency-Key és obligatòria: un reintent amb la mateixa clau no cobra dues vegades.
• La resposta és l'estat amb el seu bloc seats.
• Sense mètode de pagament la crida respon 402 employee_seat_payment_method_required i amb un cobrament rebutjat 402 employee_seat_charge_failed; en tots dos casos no es compra res.

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}'

Des de MCP, la tool update_employee_seats rep el mateix contracted_seats i un idempotency_key. Previsualitza el cobrament abans amb contracted_seats. Qualsevol compra anul·la una reducció pendent.

Reduir places

El mateix PATCH amb un nombre més petit programa una reducció. Es permet qualsevol quantitat, des de 0: no hi ha sòl.

• Sense cridar la passarel·la de pagament i sense abonament. La reducció queda com una reducció pendent que s'aplica a la renovació, i les places continuen disponibles fins aleshores.
• Per sota de les ocupades, envia deactivate: una llista d'UUID d'exactament ocupades − quantitat empleats actius del compte. Si no quadra, la resposta és 422 contracted_seats_selection_required amb param=deactivate i details product, requested, occupied, required, selected i invalid.
• Paquet d'oferta. Si, a la renovació, la reducció deixa el producte per sota del mínim d'una línia d'un paquet d'oferta aplicat, tot el paquet acabaria. La previsualització publica offer_package_loss i l'escriptura exigeix accept_offer_package_loss: true; sense ella la resposta és 422 offer_package_loss_unconfirmed amb param=accept_offer_package_loss i details product, package_id, name, effective_at i lines (cadascuna amb concept, from_price, to_price i interval). El mínim pactat mai no limita la reducció; només decideix si el paquet acaba.
• Reducció pendent. L'estat mostra pending_reduction amb contracted, effective_at i deactivations (id i name). Uns dies abans de la renovació el titular del compte rep un avís amb aquests noms, i a la renovació una tasca desactiva els empleats triats i fixa la quantitat.
• Anul·lar-la o substituir-la. Una compra, un PATCH a la quantitat actual, o una alta, activació, reactivació, lot o traspàs de NIF que ocupi el que la reducció havia de treure, l'anul·la; l'esdeveniment account.seats_updated porta aleshores cause=reduction_superseded. Un altre PATCH menor la substitueix.
• Reduir a 0 exigeix deactivate amb totes les places ocupades (i confirmar la pèrdua del paquet, si n'hi ha) i cancel·la l'add-on a fi de període.

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 empleat sense plaça lliure

Quan el compte es cobra i no hi ha plaça lliure, decideix la superfície:

• L'aplicació web respon 422 contracted_seats_exhausted amb details product, contracted, occupied, free, required i missing, sense crear ni cobrar res. L'aplicació porta aleshores a comprar places primer i a crear després.
• L'API v1 i MCP compren les places que falten amb un cobrament prorratejat i després creen l'empleat, amb els mateixos 402 de sempre quan no hi ha targeta o el cobrament falla (consulta els errors de pagament). La plaça comprada queda contractada. Un reintent no cobra dues vegades.

Envia una Idempotency-Key a les altes: sense ella, un reintent després d'una alta que sí es va arribar a crear en crea un altre, perquè l'API no distingeix un reintent d'una alta nova.

Empleats creats durant la prova

Durant una prova vigent no es cobra res i els empleats que crees no consumeixen places. Pots triar les places que contractaràs sense cobrament: es cobren quan l'empresa comença a pagar.

Quan comença el cobrament, els empleats actius ocupen les places contractades que hi hagi. Els més antics continuen active i els que no hi caben passen a inactive sense càrrec; amb 0 places contractades, tots. Reactiva els que vulguis conservar quan hagis comprat places.

Afegir una targeta durant la prova no desactiva ningú; només ho fa l'inici del cobrament.

Errors de pagament

Una compra de places és atòmica: si falla, no es compra, no es crea ni es cobra res.

Qui paga i qui pot operar

La subscripció la té el compte que paga, que normalment és el propi compte. Es cobra al mètode de pagament del compte, i només l'opera un titular o un administrador:

• Per comprar o reduir places, contractar, cancel·lar o canviar la quantitat, la persona que va emetre la clau ha de ser avui titular o administrador del compte.
• Per llegir o escriure, l'àmbit de la clau ha d'incloure l'empresa titular del compte.

Si no, la crida respon 403 forbidden_action i no canvia res. Una clau fact_test_ llegeix l'estat i la previsualització, però l'actualització, subscribe, cancel i change-quantity responen 403 live_credential_required sense canviar res: consulta el mode de prova.

Un compte gestionat que paga el seu proveïdor. En un compte gestionat de producció que paga el seu proveïdor, les places dels seus empleats no es compren al compte. Van a la subscripció managed-accounts del proveïdor, al preu de la plaça, i la seva quantitat segueix els empleats actius del compte sigui quin sigui el nivell d'accés del proveïdor. El client no pot operar l'add-on, perquè el que canviaria és a la factura del proveïdor:

• L'actualització, subscribe, cancel i change-quantity responen 403 billing_managed_by_provider a les seves claus, i a les seves persones a l'app i a MCP, sense càrrec i sense canvis.
• status i preview responen el mateix 403, perquè la subscripció que llegirien és la del proveïdor.
• El proveïdor tampoc no compra aquestes places: l'{account} d'un compte gestionat respon 404 account_not_found en aquestes rutes.

Quan el client assumeix el pagament, el compte es paga a si mateix i els seus titulars i administradors operen l'add-on com els de qualsevol altre compte. Preu dels comptes gestionats i canvi de pagador enumera què més no pot comprar el client mentre paga el proveïdor.

Consulta l'estat de facturació

GET /v1/accounts/{account}/employee-seats retorna l'estat de l'add-on: si la subscripció és activa ( subscribed ), quantes places es facturen ( quantity, les places contractades), quants empleats són actius, i el cost recurrent per plaça amb IVA. Els imports són euros com a cadena de dos decimals (per exemple "1.82") i valen null — mai un 0 enganyós — quan el cost no es pot resoldre (sense subscripció, sense pla actiu, enterprise fora de Stripe, sandbox).

El bloc seats afegeix el detall de les places contractades:

seats és null en un compte gestionat que paga el seu proveïdor.

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

Previsualitza el cobrament

GET /v1/accounts/{account}/employee-seats/preview retorna l'import prorratejat de les places que compraria una operació, calculat a partir de la propera factura de Stripe, sense cobrar. Llevat dels rebutjos de qui paga i la validació dels seus paràmetres, mai no falla — degrada a una previsualització neutra.

amount és la base imposable en euros com a cadena de dos decimals, i tax_amount i total usen el mateix format; recurring_base_cents i recurring_total_cents continuen en cèntims, com indiquen els seus noms. requires_payment_method és true quan no hi ha mètode de pagament arxivat.

La previsualització diu a més com cobririen les places contractades l'operació:

• free_seats_used, seats_to_buy i included_in_seats (true quan les places lliures ho cobreixen tot, així que amount és 0 i no cal targeta).
• seats: el bloc seats després de l'operació.
• Amb contracted_seats, amount i total són el cobrament d'avui i recurring_quantity la quantitat de la propera factura.
• En una reducció, l'import és 0 i la previsualització afegeix deactivations_required (quants empleats has de triar), cancels_pending_reduction i offer_package_loss.
• already_covered val sempre false: la cobertura per període ja no decideix cap cobrament.

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

Contracta l'add-on

POST /v1/accounts/{account}/employee-seats/subscribe garanteix que la subscripció mensual employee-seats existeix amb les places contractades del compte i cobra el primer període amb el mètode de pagament arxivat. No és obligatori: la primera compra de places crea la subscripció per si sola. No rep quantitat: per triar quantes places vols, usa PATCH. El cobrament és atòmic — si no qualla, no es contracta res:

• Sense mètode de pagament → 402 employee_seat_payment_method_required; el sobre 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/accounts/$ACCOUNT_ID/employee-seats/subscribe \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Sincronitzar la quantitat i cancel·lar

POST /v1/accounts/{account}/employee-seats/change-quantity retorna la quantitat de la subscripció a les places contractades del compte (un SET sense prorrateig ni factura). Ja no segueix els empleats actius. És idempotent — un no-op quan la quantitat ja coincideix.

POST /v1/accounts/{account}/employee-seats/cancel equival a reduir a 0: cancel·la l'add-on a fi de període i accepta els mateixos deactivate i accept_offer_package_loss que la reducció.

• Sense deactivate, es desactiven a la renovació tots els empleats actius (sense 422), i el titular rep l'avís uns dies abans.
• Una llista deactivate que no quadra amb tots respon 422 contracted_seats_selection_required.
• Si cancel·lar trenca un paquet d'oferta no confirmat, la resposta és 422 offer_package_loss_unconfirmed.

El mes en curs ja està pagat, així que subscribed continua true fins que el període acaba. La subscripció del pla mai es 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)"

Tot canvi de les places contractades o de la reducció pendent s'anuncia amb l'esdeveniment account.seats_updated.

Consulta els esquemes a la Referència d'API, i l'operació per fixar les places a public-api.v1.employee-seats.update.

Flux típic

1. Previsualitza el cost de les places que vols amb contracted_seats.
2. Assegura't que hi ha un mètode de pagament arxivat, perquè la compra no es rebutgi amb 402.
3. Compra les places amb PATCH i una Idempotency-Key.
4. Crea o reactiva empleats: cadascun ocupa una plaça lliure, sense cobrament.
5. Llegeix l'estat per mostrar les places contractades, ocupades i lliures.
6. Redueix les places quan en necessitis menys, triant qui surt si hi ha més empleats que places; s'aplica a la renovació.

Pròxims passos