11 operaciones · base https://api.bestdoctorsrd.com
POST/v1/marcaje-asistencia/clock-in
Clock In
Fichar entrada. SIN permiso de módulo para el marcaje propio, y a propósito.
Todo empleado autenticado registra su propia jornada. Pedir `ATTENDANCE` aquí
dejaría sin registro justo a quien la Ley 16-92 obliga a registrarlo, y
convertiría un derecho laboral en una concesión que un administrador puede
olvidar conceder.
Marcar POR OTRO (`employeeId`) sí exige `ATTENDANCE` + `CREATE`: es lo que
permite fichar al personal sin cuenta del portal —cocina, limpieza,
camilleros—, y quien lo hace está registrando la jornada de un tercero.
Parámetros
Nombre
En
Tipo
Obl.
tenant_id
query
string o nulo
No
Cuerpo obligatorioClockIn
Campo
Tipo
Obl.
shiftRosterId
string o nulo
No
employeeId
string o nulo
No
method
string
No
geo
string o nulo
No
Respuestas
Código
Descripción
Devuelve
201
Respuesta correcta
AttendanceOut
422
Error de validación
HTTPValidationError
POST/v1/marcaje-asistencia/clock-out
Clock Out
Fichar salida y calcular la jornada.
Mismo reparto que la entrada: la propia sin permiso, la de otro con
`ATTENDANCE` + `CREATE`. `CREATE` y no `UPDATE` porque cerrar la jornada de
quien no tiene cuenta es registrar un hecho cuando ocurre, no corregir un
registro cerrado — para eso está `PATCH /registros/{id}`, con motivo
obligatorio y a nombre de quien corrige.
Parámetros
Nombre
En
Tipo
Obl.
tenant_id
query
string o nulo
No
Cuerpo obligatorioClockOut
Campo
Tipo
Obl.
employeeId
string o nulo
No
method
string
No
geo
string o nulo
No
notes
string o nulo
No
Respuestas
Código
Descripción
Devuelve
200
Respuesta correcta
AttendanceOut
422
Error de validación
HTTPValidationError
GET/v1/marcaje-asistencia/cuadricula
Roster Grid
La semana completa de una unidad: personal, asignaciones y turnos disponibles.
`VIEW` y no `CREATE`, igual que `GET /roster`: la cobertura de un servicio es información de
operación y no dato personal de asistencia. Quien no tenga `CREATE` verá la cuadrícula y no
podrá tocarla —eso lo cierra el POST, no esta lectura—.
LA SEMANA LA NORMALIZA EL SERVIDOR. Llega un día cualquiera y se devuelve su lunes con los
siete días: así «anterior» y «siguiente» son aritmética de calendario del servidor y no del
huso horario del navegador, y un enlace pegado en un chat enseña la misma semana a todo el
mundo.
LO QUE PAGINA SON LAS PERSONAS. Los siete días viajan siempre completos: media semana no es un
rol. Emergencia Adultos ya tiene 15 personas y la planilla del centro demo 116, así que sin
página la pantalla se vuelve impracticable; pero cortar los días haría imposible leer la
cobertura, que es para lo que se mira.
Parámetros
Nombre
En
Tipo
Obl.
unitId
query
string
Sí
weekStart
query
string (date) o nulo
No
page
query
integer
No
page_size
query
integer
No
tenant_id
query
string o nulo
No
Respuestas
Código
Descripción
Devuelve
200
Respuesta correcta
RosterGridOut
422
Error de validación
HTTPValidationError
GET/v1/marcaje-asistencia/mi-marcaje
My Open Attendance
El marcaje abierto de quien pregunta, si lo hay.
Es lo que el reloj del portal necesita para saber si enseña «Entrar» o
«Salir». Sin permiso de módulo: cada quien ve el suyo.
Una cuenta sin ficha de empleado devuelve `null` en vez de un error: la
pantalla la abre todo el personal y no puede romperse por una cuenta que no
corresponde a nadie de la planilla. El error, con su explicación, llega al
intentar fichar.
Parámetros
Nombre
En
Tipo
Obl.
tenant_id
query
string o nulo
No
Respuestas
Código
Descripción
Devuelve
200
Respuesta correcta
AttendanceOut o nulo
422
Error de validación
HTTPValidationError
GET/v1/marcaje-asistencia/mis-turnos
My Published Shifts
MIS TURNOS **PUBLICADOS** — CR-541 (PRD-1831).
Ésta es *la* consulta destinada al personal, y es aquí donde el borrador tiene sus consecuencias:
* **SÓLO LO PUBLICADO.** Una guardia en borrador no sale, y no sale porque el empleado que ve un
rol a medio hacer organiza su vida sobre algo que todavía se está moviendo. El filtro no es un
`if` escrito aquí: lo decide `es_visible_para_el_personal`, que es donde está escrito el
criterio del CR y lo que impide que la próxima consulta del personal lo reinvente distinto.
* **SÓLO LO PROPIO.** Se resuelve por el vínculo de la cuenta con la ficha de empleado
(`employees.userId`), no por un `employeeId` que venga en la petición: con parámetro, cualquiera
leería el rol de cualquiera, que es dato personal de asistencia (Ley 172-13).
* **SIN PERMISO DE MÓDULO**, igual que el marcaje propio y que los datos laborales propios del
CR-534. Saber cuándo se trabaja no puede depender de que un administrador se acuerde de
habilitar un módulo: en un servicio 24/7 ese olvido se descubre de madrugada.
Lo CANCELADO tampoco sale: es historial del rol, no un turno que haya que ir a trabajar.
Una cuenta sin ficha de empleado devuelve la página VACÍA y no un error, por lo mismo que
`mi-marcaje`: hay cuentas que no son de nadie que fiche —un integrador, un administrador de la
red— y la pantalla la abre todo el mundo.
**LO QUE ESTA RUTA NO ES:** la pantalla de «Mis turnos» del personal, con su exportación y su
aviso de cambios. Eso son las historias 37 a 39 del PRD y su propio CR. Aquí está la puerta, y
está cerrada por defecto.
Parámetros
Nombre
En
Tipo
Obl.
dateFrom
query
string (date) o nulo
No
dateTo
query
string (date) o nulo
No
page
query
integer
No
page_size
query
integer
No
tenant_id
query
string o nulo
No
Respuestas
Código
Descripción
Devuelve
200
Respuesta correcta
PagedResponse_ShiftRosterOut_
422
Error de validación
HTTPValidationError
GET/v1/marcaje-asistencia/registros
List Attendance
Marcajes de la institución.
Leer la asistencia AJENA exige `VIEW` sobre el módulo: son datos personales
del empleado (Ley 172-13), no información de operación. Quien no lo tenga
puede consultar los suyos pasando su propio `employeeId` — el de su FICHA de
empleado desde el CR-528, que es lo que devuelve `/mi-marcaje`.
Paginado en servidor y con el MISMO sobre y el MISMO nombre de parámetro que el rol y que la
planilla (`page_size`). Ya cortaba la lista, pero sin decir el total —así que la pantalla no
podía saber si había más— y con `pageSize`, que era el único de los tres que se escribía
distinto. Que las tres rutas se lean igual importa más que cuál de las dos grafías era mejor.
Parámetros
Nombre
En
Tipo
Obl.
employeeId
query
string o nulo
No
dateFrom
query
string (date) o nulo
No
dateTo
query
string (date) o nulo
No
page
query
integer
No
page_size
query
integer
No
tenant_id
query
string o nulo
No
Respuestas
Código
Descripción
Devuelve
200
Respuesta correcta
PagedResponse_AttendanceOut_
422
Error de validación
HTTPValidationError
PATCH/v1/marcaje-asistencia/registros/{record_id}
Correct Attendance
Corrección administrativa de un marcaje, con motivo obligatorio.
Es la ÚNICA forma de tocar un registro cerrado, y deja constancia de quién y
por qué. Sin esa distinción, un registro corregido sería indistinguible de uno
fichado por el propio empleado y el marcaje dejaría de probar nada ante una
inspección — que es justo para lo que existe.
Parámetros
Nombre
En
Tipo
Obl.
record_id
path
string
Sí
tenant_id
query
string o nulo
No
Cuerpo obligatorioAttendanceCorrection
Campo
Tipo
Obl.
clockInAt
string (date-time) o nulo
No
clockOutAt
string (date-time) o nulo
No
reason
string
Sí
Respuestas
Código
Descripción
Devuelve
200
Respuesta correcta
AttendanceOut
422
Error de validación
HTTPValidationError
GET/v1/marcaje-asistencia/reporte
Attendance Report
Horas, tardanzas, ausencias y extras por empleado.
Es el insumo que RRHH/Nómina consume, así que las AUSENCIAS se cuentan aquí y
no en el cliente: una ausencia es una guardia planificada SIN marcaje, y eso
sólo se sabe cruzando las dos tablas. Dejarlo al consumidor garantizaría que
cada uno lo calcule distinto.
`EXPORT` y no `VIEW`: un reporte agregado de horas de todo el personal es
exactamente lo que sale del sistema hacia una hoja de cálculo.
Se acota POR UNIDAD desde el CR-536, el mismo eje que el rol: filtrar por un `serviceModule`
que ya nadie teclea obligaría a la pantalla a ofrecer una lista de valores derivados que no
corresponde a ningún desplegable del portal.
Parámetros
Nombre
En
Tipo
Obl.
dateFrom
query
string (date)
Sí
dateTo
query
string (date)
Sí
unitId
query
string o nulo
No
tenant_id
query
string o nulo
No
Respuestas
Código
Descripción
Devuelve
200
Respuesta correcta
AttendanceReportOut
422
Error de validación
HTTPValidationError
GET/v1/marcaje-asistencia/roster
List Roster
Quién está de guardia. `VIEW` basta: es información de cobertura del
servicio, no dato personal de asistencia.
Se filtra POR UNIDAD y por rango de fechas, que son las dos preguntas de quien supervisa: «la
semana que viene en la UCI». El filtro por `serviceModule` se fue con el CR-536 junto con los
ocho valores quemados que lo alimentaban.
Una unidad DESACTIVADA se sigue pudiendo filtrar y leer: lo ya asignado a ella es historial que
hay que poder ver y corregir.
PAGINA EN SERVIDOR y con el mismo sobre que `GET /v1/employees` (`{data, total, page,
page_size}`). No es cosmética: el centro demo pasó de 5 empleados a 116 en 21 unidades, y un mes
de rol de una sola unidad son ya cientos de filas. Cortar en el cliente exigiría traérselas
todas para enseñar veinticinco.
Parámetros
Nombre
En
Tipo
Obl.
unitId
query
string o nulo
No
employeeId
query
string o nulo
No
dateFrom
query
string (date) o nulo
No
dateTo
query
string (date) o nulo
No
includeCancelled
query
boolean
No
page
query
integer
No
page_size
query
integer
No
tenant_id
query
string o nulo
No
Respuestas
Código
Descripción
Devuelve
200
Respuesta correcta
PagedResponse_ShiftRosterOut_
422
Error de validación
HTTPValidationError
POST/v1/marcaje-asistencia/roster
Create Roster
Asigna a alguien a un turno de una unidad.
Las tres comprobaciones son del PROPIO centro y en este orden: la persona, la unidad y el
turno. Cada una con su código, porque cada una se arregla en una pantalla distinta.
EL HORARIO SE COPIA. `shiftLabel`, `startTime` y `endTime` salen de la definición del turno y
se escriben en la fila: es una foto deliberada (PRD-1831), y por eso cambiar después el turno
«Noche» no altera lo que ya se planificó. La alternativa —resolver el horario al leer— haría
que corregir el catálogo en septiembre reescribiera el rol de agosto, y el marcaje de agosto se
comparó contra el horario de agosto.
Parámetros
Nombre
En
Tipo
Obl.
tenant_id
query
string o nulo
No
Cuerpo obligatorioShiftRosterIn
Campo
Tipo
Obl.
employeeId
string
Sí
unitId
string
Sí
shiftDefinitionId
string
Sí
shiftDate
string (date)
Sí
locationId
string o nulo
No
status
string
No
notes
string o nulo
No
Respuestas
Código
Descripción
Devuelve
201
Respuesta correcta
ShiftRosterOut
422
Error de validación
HTTPValidationError
PATCH/v1/marcaje-asistencia/roster/{roster_id}
Update Roster
Corrige una asignación: la mueve de unidad, le cambia el turno, la cancela o la anota.
La fila se busca SIN mirar el estado de su unidad: una guardia asignada a una unidad que
después se desactivó tiene que poder verse y arreglarse, que es justo lo que pide el CR. Lo que
sí se comprueba es el destino —no se mueve nada A una unidad ni A un turno desactivados—.