Lots d’empleats i un únic checkout de seients
Dona d’alta o reactiva fins a 100 empleats amb una operació duradora i una cotització de seients revisada.
Un lot conté d’1 a 100 empleats concrets. Tria alta o reactivació; no barregis totes dues. Preparar un lot no crea empleats, envia invitacions ni cobra la targeta. Les importacions CSV i Excel queden fora d’aquest flux.
Disponibilitat
Pot ser que els lots d’empleats no estiguin activats per al teu compte. Consulta purchase_availability.employee_batches: l’endpoint autenticat existent de l’aplicació GET /api/features el publica a data.purchase_availability com a booleà del servidor, juntament amb customer_offers. Si està desactivat o és desconegut, tracta els lots com a no activats.
- No activats:
POST /v1/employeesiPOST /v1/employees/{employee}/reactivatemantenen el cobrament síncron de la plaça per empleat descrit a Facturació de places d'empleat. - Activats: aquestes dues operacions fan servir la mateixa cotització fiable de places que els lots i poden retornar
503 employee_batch_quote_unavailablequan no es pot obtenir. No s’ha creat ni cobrat ningú: reintenta la mateixa petició.
Durant una prova vigent, els empleats s’afegeixen sense càrrec. Quan l’empresa comença a pagar, els empleats creats durant la prova passen a inactive sense cap cobrament automàtic, i reactivar-ne cadascun, de manera individual o en un lot de reactivació, cobra la seva plaça. Consulta Empleats creats durant la prova.
Preparar i revisar
Fes servir POST /v1/employee-batches amb employees:write i una capçalera Idempotency-Key. Conserva un row_id estable per persona. L’alta envia un profile; la reactivació envia l’UUID de l’empleat existent com a employee_id. El cos no permet triar empresa ni preu: l’empresa autenticada és propietària de l’operació.
{
"kind": "reactivate",
"items": [
{"row_id": "row-1", "employee_id": "019c0c2f-b018-7ddf-8c70-546c61c7af1f"}
]
}La resposta conté data.id (UUID), quote_version, status, quote i allowed_actions. Revisa l’import d’avui i el total mensual recurrent. Els empleats coberts i els seients pagats reutilitzables es compten separadament dels seients que requereixen cobrament. Els imports són cèntims enters d’EUR; null vol dir desconegut, mai gratuït. Una cotització sense dades fiables de facturació no autoritza una compra.
L’alta valida noms, email, tipus de jornada, hores, comunitat autònoma i data d’alta; els identificadors externs opcionals han de ser únics a l’empresa. Un empleat repetit, una fila invàlida, un empleat actiu seleccionat per reactivar, un topall del pla o una altra operació de seients bloquegen tot el lot. La validació per fila retorna details.row_errors amb row_id, field i message; la validació HTTP habitual també pot retornar errors per índex.
Confirmar i recuperar
Envia POST /v1/employee-batches/{id}/confirm amb la quote_version revisada i una clau nova i estable per a aquella confirmació. Respecta allowed_actions. Una cotització canviada o caducada exigeix POST /v1/employee-batches/{id}/quote, amb la versió anterior i la seva pròpia clau, i una altra revisió abans de confirmar.
La confirmació pot retornar 202 mentre el pagament o la incorporació d’empleats continuen pendents. Conserva l’UUID de l’operació i fes servir GET /v1/employee-batches/{id}; no creïs un altre lot per reintentar. Una action_url permesa pot requerir autenticació de targeta. Un error de mètode de pagament pot incloure una details.payment_setup_url verificada. En tornar, consulta l’operació i actualitza’n la cotització quan correspongui.
| Resultat | Què fer |
|---|---|
completed | Consulta els UUID d’empleats resultants a result. |
processing, requires_action, payment_pending, paid | Consulta la mateixa operació fins que en coneguis la resolució. |
compensating, needs_review | Conserva el rebut i espera la recuperació; no repeteixis la compra. |
failed, cancelled, compensated | Consulta el rebut final abans de decidir si inicies una altra operació. |
POST /v1/employee-batches/{id}/cancel només sol·licita una acció que el servidor permeti en aquell moment. Després d’un intent financer, cancel·lar pot exigir restauració verificada o un reemborsament; no promet una devolució immediata. Llista les operacions amb GET /v1/employee-batches (employees:read), fent servir cursor, limit i statuses[] opcional.
Aplicació i MCP
A l’aplicació, obre l’acció de lot de la llista d’empleats, introdueix perfils o selecciona empleats inactius i revisa el checkout a la pàgina dedicada. Tancar o recarregar un checkout pendent conserva l’operació del servidor. Si després perds accés a empleats, Facturació només mostra un rebut mínim i la cancel·lació permesa; no autoritza un altre cobrament ni autenticació de targeta per al producte inaccessible.
Les eines MCP equivalents són prepare_employee_batch, refresh_employee_batch_quote, confirm_employee_batch, cancel_employee_batch, get_employee_batch i list_employee_batches. Les escriptures reben idempotency_key; confirmar i cancel·lar poden tenir efectes financers. Les restriccions de mòdul, pla, pertinença i sandbox continuen aplicant-se a REST i MCP. Un sandbox no pot fer una compra real.