Lotes de empleados y un único checkout de asientos
Da de alta o reactiva hasta 100 empleados con una operación duradera y una cotización de asientos revisada.
Un lote contiene de 1 a 100 empleados concretos. Elige alta o reactivación; no mezcles ambas. Preparar un lote no crea empleados, envía invitaciones ni cobra tu tarjeta. Las importaciones CSV y Excel quedan fuera de este flujo.
Disponibilidad
Puede que los lotes de empleados no estén activados para tu cuenta. Consulta purchase_availability.employee_batches: el endpoint autenticado existente de la aplicación GET /api/features lo publica en data.purchase_availability como booleano del servidor, junto a customer_offers. Si está desactivado o es desconocido, trata los lotes como no activados.
- No activados:
POST /v1/employeesyPOST /v1/employees/{employee}/reactivatemantienen el cobro síncrono del asiento por empleado descrito en Facturación de asientos de empleado. - Activados: esas dos operaciones usan la misma cotización fiable de asientos que los lotes y pueden devolver
503 employee_batch_quote_unavailablecuando no se puede obtener. No se ha creado ni cobrado a nadie: reintenta la misma petición.
Durante una prueba vigente, los empleados se añaden sin cargo. Cuando la empresa empieza a pagar, los empleados creados durante la prueba pasan a inactive sin ningún cobro automático, y reactivar cada uno, de forma individual o en un lote de reactivación, cobra su asiento. Consulta Empleados creados durante la prueba.
Preparar y revisar
Usa POST /v1/employee-batches con employees:write y una cabecera Idempotency-Key. Conserva un row_id estable por persona. El alta envía un profile; la reactivación envía el UUID del empleado existente como employee_id. El cuerpo no permite elegir empresa ni precio: la empresa autenticada es propietaria de la operación.
{
"kind": "reactivate",
"items": [
{"row_id": "row-1", "employee_id": "019c0c2f-b018-7ddf-8c70-546c61c7af1f"}
]
}La respuesta contiene data.id (UUID), quote_version, status, quote y allowed_actions. Revisa el importe de hoy y el total mensual recurrente. Los empleados cubiertos y los asientos pagados reutilizables se cuentan por separado de los asientos que requieren cobro. Los importes son céntimos enteros de EUR; null significa desconocido, nunca gratis. Una cotización sin datos fiables de facturación no autoriza una compra.
El alta valida nombres, email, tipo de jornada, horas, comunidad autónoma y fecha de alta; los identificadores externos opcionales deben ser únicos en la empresa. Un empleado repetido, una fila inválida, un empleado activo seleccionado para reactivar, un tope del plan u otra operación de asientos bloquean todo el lote. La validación por fila devuelve details.row_errors con row_id, field y message; la validación HTTP habitual también puede devolver errors por índice.
Confirmar y recuperar
Envía POST /v1/employee-batches/{id}/confirm con la quote_version revisada y una clave nueva y estable para esa confirmación. Respeta allowed_actions. Una cotización cambiada o caducada exige POST /v1/employee-batches/{id}/quote, con la versión anterior y su propia clave, y otra revisión antes de confirmar.
La confirmación puede devolver 202 mientras el pago o la incorporación de empleados siguen pendientes. Conserva el UUID de la operación y usa GET /v1/employee-batches/{id}; no crees otro lote para reintentar. Una action_url permitida puede requerir autenticación de tarjeta. Un error de método de pago puede incluir una details.payment_setup_url verificada. Al volver, consulta la operación y actualiza su cotización cuando corresponda.
| Resultado | Qué hacer |
|---|---|
completed | Consulta los UUID de empleados resultantes en result. |
processing, requires_action, payment_pending, paid | Consulta la misma operación hasta conocer su resolución. |
compensating, needs_review | Conserva el recibo y espera la recuperación; no repitas la compra. |
failed, cancelled, compensated | Consulta el recibo final antes de decidir si inicias otra operación. |
POST /v1/employee-batches/{id}/cancel solo solicita una acción que el servidor permita en ese momento. Tras un intento financiero, cancelar puede exigir restauración verificada o un reembolso; no promete una devolución inmediata. Lista tus operaciones con GET /v1/employee-batches (employees:read), usando cursor, limit y statuses[] opcional.
Aplicación y MCP
En la aplicación, abre la acción de lote de la lista de empleados, introduce perfiles o selecciona empleados inactivos y revisa el checkout en su página dedicada. Cerrar o recargar un checkout pendiente conserva la operación del servidor. Si después pierdes acceso a empleados, Facturación solo muestra un recibo mínimo y la cancelación permitida; no autoriza otro cobro ni autenticación de tarjeta para el producto inaccesible.
Las herramientas MCP equivalentes son prepare_employee_batch, refresh_employee_batch_quote, confirm_employee_batch, cancel_employee_batch, get_employee_batch y list_employee_batches. Las escrituras reciben idempotency_key; confirmar y cancelar pueden tener efectos financieros. Las restricciones de módulo, plan, pertenencia y sandbox siguen aplicándose en REST y MCP. Un sandbox no puede hacer una compra real.