Places contractades, paquets d'oferta i prova

31 d'octubre de 2026 — La factura de les places d'empleat i de les places de NIF addicional passa a ser la factura de les places contractades. Crear, activar o reactivar ocupa una plaça lliure i mai cobra per si sol; només cobra comprar places. Desactivar allibera una plaça sense baixar la factura i una reducció té efecte a la renovació, sense abonament, triant a qui es desactiva quan baixes de les places ocupades. Comprar o crear el que una reducció anava a treure l'anul·la.

Els paquets d'oferta, fins a tres línies amb un codi que es bescanvia des de l'aplicació o per suport, conserven el seu preu pactat mentre es mantenen els seus mínims i la subscripció es paga, i acaben sencers, amb totes les seves línies de tornada al preu de catàleg, si no. No es retira cap operació.

Operacions d'aquesta versió

Les operacions que només ajusten el seu esquema són a la taula del final i a la secció d'esquema.

Places contractades

El bloc seats de l'estat publica contracted, occupied, free, agreed_minimum, agreed_minimum_ends_at, reducible_to, pending_reduction i enforced. reducible_to val sempre 0 perquè una reducció no té sòl.

PATCH /v1/accounts/{account}/employee-seats i PATCH /v1/accounts/{account}/additional-nif-seats reben {"contracted_seats": N}. Un nombre més gran compra places amb un cobrament prorratejat amb la targeta del compte i Idempotency-Key és obligatòria. Un nombre més petit és una reducció. La vista prèvia rep el mateix paràmetre i mostra l'import d'avui, la quantitat de la propera factura i si anul·la una reducció pendent. Consulta les places d'empleat i les places de NIF addicional.

Comprar places d'empleat exigeix ara el control horari: amb un pla que no l'inclou, PATCH /v1/accounts/{account}/employee-seats, POST /v1/accounts/{account}/employee-seats/subscribe i POST /v1/accounts/{account}/employee-seats/change-quantity responen el nou 403 employee_seats_not_in_plan abans de cobrar res, mentre que baixar o mantenir les places continua permès. Consulta l'error.

Compra automàtica

Sense una plaça lliure, l'aplicació respon 422 contracted_seats_exhausted i et porta a comprar abans. L'API REST i el MCP no: crear, activar, reactivar i acceptar un traspàs de NIF compren les places que falten amb un cobrament prorratejat i després creen, amb els mateixos 402 de sempre. Un reintent no cobra dues vegades i la plaça comprada es queda. Envia Idempotency-Key en cada alta: sense ella, un reintent després d'una alta que sí que es va crear crea una altra entitat. Consulta la compra automàtica.

Reducció

Una reducció pot arribar fins a 0 i té efecte a la renovació, sense abonament. Queda com a pending_reduction i les places continuen disponibles fins llavors.

• Per sota de les ocupades. deactivate és una llista d'exactament ocupades - contractades entitats actives. Si no, la resposta és 422 contracted_seats_selection_required.
• Avís i renovació. Uns dies abans, la propietària rep els noms. A la renovació la tasca desactiva els triats i fixa la quantitat.
• S'anul·la amb una compra, o amb una alta, activació, reactivació, lot o traspàs que ocupi el que la reducció anava a treure, i amb un PATCH a la quantitat actual. Un PATCH més petit la substitueix.
• A 0. Exigeix triar totes les ocupades i cancel·la l'add-on al final del període. cancel és una reducció a 0 i, sense deactivate, desactiva tots els empleats actius.

Consulta la reducció.

Paquets d'oferta

Un paquet agrupa fins a tres línies (pla, places d'empleat i places de NIF addicional) sota un codi. Es bescanvia des de l'aplicació o per suport; en REST i MCP el seu codi respon 422 customer_offer_not_eligible amb details.reason product.

• apply_to_existing aplica una oferta de places a les places que el compte ja té i no crea res. El pressupost publica target_quantity i minimum_quantity.
• Condicions. El paquet conserva els seus preus mentre les places contractades de cada línia es mantenen en el seu mínim o per sobre i la subscripció es paga. Desactivar no el trenca; reduir sí.
• El preu pactat regeix per a totes les places contractades, també les comprades després, fins i tot per la compra automàtica.
• Final. Acaba sencer, amb totes les línies al preu de catàleg des de la següent renovació i sense abonament, per reduction_below_minimum, subscription_ended_unpaid, subscription_cancelled, revoked_by_support o duration_elapsed.
• Confirmació. Una reducció que trencaria un paquet es previsualitza amb offer_package_loss i l'escriptura exigeix accept_offer_package_loss: true; sense ell, 422 offer_package_loss_unconfirmed.

Consulta els paquets d'oferta i el mínim pactat.

La prova

Durant la prova no es cobra res i els empleats o NIF no ocupen places. Ja pots triar les places contractades sense cobrament. Un bescanvi de places d'empleat o de NIF durant la prova respon 422 customer_offer_not_eligible amb details.reason trial_active, en lloc del 409 anterior dels lots d'empleats i d'active_population. Quan el compte comença a pagar, les entitats més antigues ocupen les places contractades i les que no hi caben passen a inactives, sense cobrament; amb zero places contractades, totes. Consulta la prova en les places d'empleat i la regla de la prova en les places de NIF.

Errors

• customer_offer_not_eligible amb reason product respon 422 on abans responia 403.
• contracted_seats_selection_required: param deactivate, amb details product, requested, occupied, required, selected i invalid. A cancel només s'emet amb una llista que no quadra.
• offer_package_loss_unconfirmed: param accept_offer_package_loss, amb details product, package_id, name, effective_at i lines.
• contracted_seats_exhausted només l'emet l'aplicació web. L'API REST i el MCP compren en el seu lloc.
• contracted_seats_below_minimum queda retirat: no es va arribar a emetre.

Els tres codis són subcodis de business_rule_violation. Consulta el catàleg d'errors.

Esdeveniments

account.seats_updated anuncia cada canvi de les places contractades. El seu pending_reduction porta les deactivations i la causa reduction_superseded marca una reducció anul·lada per una compra o una entrada. account.offer_package_ended anuncia el final d'un paquet, amb el seu motiu i els conceptes de les seves línies, sense imports. Tots dos van als endpoints del compte. Consulta els webhooks de compte.

Ajustos d'esquema i què fer

Diverses operacions només canvien en l'esquema publicat, sense res de diferent al cable: les que feien servir not ara descriuen la mateixa regla d'una altra manera i els camps obligatoris aniuats queden documentats. No has de fer res amb elles.

Una sèrie creada sense number_format neix ara amb {code}-{YYYY}-{0000}, quatre xifres en lloc de tres. Les sèries que ja existeixen conserven el seu format.

Com a integrador:

1. Envia Idempotency-Key en altes, activacions, reactivacions i traspassos, que ara poden comprar places.
2. Admet included_in_seats a l'enum zero_reason de les vistes prèvies.
3. Tracta already_covered com a sempre false.
4. Si cancel·laves l'add-on amb empleats actius, envia deactivate: sense ell es desactiven tots a la renovació.
5. Compta que una compra o una alta anul·li una reducció pendent.
6. Confirma amb accept_offer_package_loss la reducció que trenqui un paquet.

La taula següent llista les operacions d'aquesta versió.