Plazas contratadas, paquetes de oferta y prueba

31 de octubre de 2026 — La factura de las plazas de empleado y de las plazas de NIF adicional pasa a ser la factura de las plazas contratadas. Crear, activar o reactivar ocupa una plaza libre y nunca cobra por sí solo; solo cobra comprar plazas. Desactivar libera una plaza sin bajar la factura y una reducción tiene efecto en la renovación, sin abono, eligiendo a quién se desactiva cuando bajas de las plazas ocupadas. Comprar o crear lo que una reducción iba a quitar la anula.

Los paquetes de oferta, hasta tres líneas con un código que se canjea desde la aplicación o por soporte, conservan su precio pactado mientras se mantienen sus mínimos y la suscripción se paga, y terminan enteros, con todas sus líneas de vuelta al precio de catálogo, si no. No se retira ninguna operación.

Operaciones de esta versión

Las operaciones que solo ajustan su esquema están en la tabla del final y en la sección de esquema.

Plazas contratadas

El bloque seats del estado publica contracted, occupied, free, agreed_minimum, agreed_minimum_ends_at, reducible_to, pending_reduction y enforced. reducible_to vale siempre 0 porque una reducción no tiene suelo.

PATCH /v1/accounts/{account}/employee-seats y PATCH /v1/accounts/{account}/additional-nif-seats reciben {"contracted_seats": N}. Un número mayor compra plazas con un cobro prorrateado con la tarjeta de la cuenta y Idempotency-Key es obligatoria. Un número menor es una reducción. La vista previa recibe el mismo parámetro y muestra el importe de hoy, la cantidad de la próxima factura y si anula una reducción pendiente. Consulta las plazas de empleado y las plazas de NIF adicional.

Comprar plazas de empleado exige ahora el control horario: con un plan que no lo incluye, PATCH /v1/accounts/{account}/employee-seats, POST /v1/accounts/{account}/employee-seats/subscribe y POST /v1/accounts/{account}/employee-seats/change-quantity responden el nuevo 403 employee_seats_not_in_plan antes de cobrar nada, mientras que bajar o mantener las plazas sigue permitido. Consulta el error.

Compra automática

Sin una plaza libre, la aplicación responde 422 contracted_seats_exhausted y te lleva a comprar antes. La API REST y el MCP no: crear, activar, reactivar y aceptar un traspaso de NIF compran las plazas que faltan con un cobro prorrateado y después crean, con los mismos 402 de siempre. Un reintento no cobra dos veces y la plaza comprada se queda. Envía Idempotency-Key en cada alta: sin ella, un reintento tras un alta que sí llegó a crearse crea otra entidad. Consulta la compra automática.

Reducción

Una reducción puede llegar hasta 0 y tiene efecto en la renovación, sin abono. Queda como pending_reduction y las plazas siguen disponibles hasta entonces.

• Por debajo de las ocupadas. deactivate es una lista de exactamente ocupadas - contratadas entidades activas. Si no, la respuesta es 422 contracted_seats_selection_required.
• Aviso y renovación. Unos días antes, la propietaria recibe los nombres. En la renovación la tarea desactiva a los elegidos y fija la cantidad.
• Se anula con una compra, o con un alta, activación, reactivación, lote o traspaso que ocupe lo que la reducción iba a quitar, y con un PATCH a la cantidad actual. Un PATCH menor la sustituye.
• A 0. Exige elegir todas las ocupadas y cancela el add-on al final del periodo. cancel es una reducción a 0 y, sin deactivate, desactiva a todos los empleados activos.

Consulta la reducción.

Paquetes de oferta

Un paquete agrupa hasta tres líneas (plan, plazas de empleado y plazas de NIF adicional) bajo un código. Se canjea desde la aplicación o por soporte; en REST y MCP su código responde 422 customer_offer_not_eligible con details.reason product.

• apply_to_existing aplica una oferta de plazas a las plazas que la cuenta ya tiene y no crea nada. El presupuesto publica target_quantity y minimum_quantity.
• Condiciones. El paquete conserva sus precios mientras las plazas contratadas de cada línea se mantienen en su mínimo o por encima y la suscripción se paga. Desactivar no lo rompe; reducir sí.
• El precio pactado rige para todas las plazas contratadas, también las compradas después, incluso por la compra automática.
• Fin. Termina entero, con todas las líneas al precio de catálogo desde la siguiente renovación y sin abono, por reduction_below_minimum, subscription_ended_unpaid, subscription_cancelled, revoked_by_support o duration_elapsed.
• Confirmación. Una reducción que rompería un paquete se previsualiza con offer_package_loss y la escritura exige accept_offer_package_loss: true; sin él, 422 offer_package_loss_unconfirmed.

Consulta los paquetes de oferta y el mínimo pactado.

La prueba

Durante la prueba no se cobra nada y los empleados o NIF no ocupan plazas. Ya puedes elegir las plazas contratadas sin cobro. Un canje de plazas de empleado o de NIF durante la prueba responde 422 customer_offer_not_eligible con details.reason trial_active, en lugar del 409 anterior de los lotes de empleados y de active_population. Cuando la cuenta empieza a pagar, las entidades más antiguas ocupan las plazas contratadas y las que no caben pasan a inactivas, sin cobro; con cero plazas contratadas, todas. Consulta la prueba en las plazas de empleado y la regla de la prueba en las plazas de NIF.

Errores

• customer_offer_not_eligible con reason product responde 422 donde antes respondía 403.
• contracted_seats_selection_required: param deactivate, con details product, requested, occupied, required, selected e invalid. En cancel solo se emite con una lista que no cuadra.
• offer_package_loss_unconfirmed: param accept_offer_package_loss, con details product, package_id, name, effective_at y lines.
• contracted_seats_exhausted solo lo emite la aplicación web. La API REST y el MCP compran en su lugar.
• contracted_seats_below_minimum queda retirado: no llegó a emitirse.

Los tres códigos son subcódigos de business_rule_violation. Consulta el catálogo de errores.

Eventos

account.seats_updated anuncia cada cambio de las plazas contratadas. Su pending_reduction lleva las deactivations y la causa reduction_superseded marca una reducción anulada por una compra o una entrada. account.offer_package_ended anuncia el fin de un paquete, con su motivo y los conceptos de sus líneas, sin importes. Ambos van a los endpoints de la cuenta. Consulta los webhooks de cuenta.

Ajustes de esquema y qué hacer

Varias operaciones solo cambian en el esquema publicado, sin nada distinto en el cable: las que usaban not ahora describen la misma regla de otra forma y los campos obligatorios anidados quedan documentados. No tienes que hacer nada con ellas.

Una serie creada sin number_format nace ahora con {code}-{YYYY}-{0000}, cuatro cifras en lugar de tres. Las series que ya existen conservan su formato.

Como integrador:

1. Envía Idempotency-Key en altas, activaciones, reactivaciones y traspasos, que ahora pueden comprar plazas.
2. Admite included_in_seats en el enum zero_reason de las vistas previas.
3. Trata already_covered como siempre false.
4. Si cancelabas el add-on con empleados activos, envía deactivate: sin él se desactivan todos en la renovación.
5. Cuenta con que una compra o un alta anule una reducción pendiente.
6. Confirma con accept_offer_package_loss la reducción que rompa un paquete.

La tabla siguiente lista las operaciones de esta versión.