Referencia de rutas

Sin clave de API ni sesión. Quien verifica presenta el recibo firmado (recibo, el texto que se le entregó al fichar) o el asiento completo (asiento), uno solo. No se busca por un identificador suelto ni por posición: sin el contenido o la firma no hay respuesta, así que recorrer posiciones no descubre qué asientos existen. Responde siempre 200 y la misma forma, exista o no el asiento. integro: coincide con el guardado (devuelve su posición y su resumen, que ya tenías); alterado: el asiento presentado no cuadra con su propio resumen; no_consta: cuadra, pero no hay uno igual en la cadena (no se distingue «no existió» de «existió con otro contenido»); recibo_invalido: el recibo no verifica (firma, algoritmo distinto de EdDSA, clave desconocida o emitido en el futuro). El recibo no caduca. Se comprueba contra todas las claves públicas publicadas, las antiguas incluidas (/.well-known/jwks.json). No devuelve ningún dato personal (art. 5.1.c del RGPD, minimización). Límite: 30 peticiones por minuto y por IP (429 con Retry-After). CORS: orígenes de la web y de la app; desde un servidor, sin restricción de origen.

Recalcula la cadena de asientos que se conserva y dice si es íntegra, cuál es su cabeza (la guardada y si coincide con el último asiento conservado), cuántas roturas hay y dónde está la primera (secuencia y motivo), y el último sello diario y corte por retención. No devuelve ningún asiento.

Sin autenticación de cliente (cliente público con PKCE S256). Se llama desde el servidor de la aplicación: los navegadores de otros orígenes no pueden. Todo error cuenta como fallo del origen y tras 10 se responde 429. El código vale 60 segundos y un solo uso (se gasta en el primer intento, acierte o no). Refrescar entrega un par nuevo e invalida el anterior; presentar un refresco ya usado revoca toda la autorización. Solo lectura: los ámbitos que se pueden conceder son los …:leer y personas:nif.

Revoca toda la autorización a la que pertenece el token. Responde 200 aunque el token no exista o sea de otro cliente.

El NIF sale enmascarado (***5678Z) salvo con personas:nif.

Cuelga de empresa:leer: los ámbitos centros:leer no existen como ámbito de clave.

Cuelga de empresa:leer, como la lista. Un centro de otra empresa o inexistente da el mismo 404 centro_no_encontrado.

Orden estable por secuencia de la cadena. El intervalo es [desde, hasta) sobre el instante sellado; sin parámetros, los últimos 7 días. Como mucho 31 días por llamada (422 rango_demasiado_amplio): para más, varias llamadas. Los campos posicion y nota solo se devuelven si la clave tiene además el ámbito delicado fichajes:posicion (no se puede conceder por OAuth); sin él, los fichajes salen sin esos campos.

Esta lista es una proyección de lectura: no trae todos los campos que entran en el resumen criptográfico del asiento, así que no sirve como entrada del verificador abierto (ver docs/VERIFICADOR.md).

Requiere habilitar la escritura. Está apagada por defecto en todas las empresas: sin la opción de empresa «Escritura por API (fichajes)» activada por su administración, responde 403 escritura_no_habilitada. Además la clave necesita el ámbito fichajes:escribir (403 ambito_insuficiente sin él), que no se concede por defecto a ninguna clave y no existe en OAuth. Una clave de pruebas erj_test_ no escribe (403 escritura_no_disponible_en_pruebas).

Añade UN asiento de entrada o salida a una persona de la empresa de la clave (la empresa sale siempre de la clave; no hay parámetro de empresa). El asiento lo sella el servidor con la misma lógica que el fichaje de la aplicación y del quiosco: solo se añade (no existe ninguna ruta para modificar ni borrar un asiento), entra en la cadena de integridad, con su secuencia y sus huellas, y se rechaza si el mes está cerrado. La hora la pone el servidor: el cuerpo no admite ocurridoEn, ni autor, ni secuencia, ni huellas, ni ningún otro campo (400). Las correcciones de un fichaje ya sellado no se hacen por aquí.

Idempotency-Key es obligatoria. Usa un valor único por intento de fichaje (por ejemplo, un UUID) y repítelo al reintentar tras un corte: con la misma clave y los mismos datos (persona, tipo y posición) se devuelve el mismo asiento, con la cabecera Idempotent-Replayed: true, sin duplicar nada. Con la misma clave y datos distintos, 409 idempotency_key_reutilizada. La clave se acota a la clave de API que la usó.

Posición. posicion es opcional y solo se guarda si la empresa tiene activa la ubicación al fichar; es el sello del instante del fichaje, nunca un seguimiento (400 posicion_no_activada si no está activa). La respuesta no la devuelve. No hay biometría: la persona se identifica por su personaId y el sistema que llama es responsable de haberla identificado.

Códigos propios de esta operación: escritura_no_habilitada, plan_sin_escritura (403, la escritura solo está en el plan Ampliada de la API), ambito_insuficiente y escritura_no_disponible_en_pruebas (403), empresa_inactiva (403), idempotency_key_requerida, idempotency_key_invalida, datos_invalidos y posicion_no_activada (400), persona_no_encontrada (404), idempotency_key_reutilizada y conflicto_de_cadena (409; en el segundo, reintenta con la misma Idempotency-Key), mes_cerrado, hora_futura y persona_de_baja (422). Además los generales de la respuesta Error. Cuenta contra los mismos límites de uso que las lecturas.

El tipo se expone; el motivo médico nunca (una baja médica sale como baja).

Requiere habilitar la escritura. Está apagada por defecto en todas las empresas: sin la opción de empresa «Solicitar ausencias por API» activada por su administración, responde 403 escritura_no_habilitada (activar la escritura de fichajes no basta: son opciones independientes). Además la clave necesita el ámbito ausencias:escribir (403 ambito_insuficiente sin él), que no se concede por defecto a ninguna clave y no existe en OAuth. Una clave de pruebas erj_test_ no escribe (403 escritura_no_disponible_en_pruebas).

Crea UNA solicitud de ausencia a nombre de una persona de la empresa de la clave (la empresa sale siempre de la clave; no hay parámetro de empresa). Nunca la aprueba: nace siempre en estado pendiente, con un único evento en su historial (el de la clave), y la administración la resuelve desde la aplicación como cualquier otra solicitud. No existe ninguna ruta para aprobar, rechazar ni modificar una ausencia; lo único que se puede hacer después es retirar la propia solicitud mientras siga pendiente (POST /ausencias/{ausenciaId}/cancelar). El cuerpo no admite estado, historial, motivo, empresa ni ningún otro campo (400).

Tipos admitidos: vacaciones, permiso_retribuido y asuntos_propios. Las bajas médicas no se registran por API (dato de salud): las registra la administración. Un rango no puede abarcar más de 366 días. Se rechaza si el rango toca un mes cerrado (422 mes_cerrado) o se solapa con otra solicitud pendiente o aprobada de la misma persona (422 ausencia_solapada). No comprueba el saldo de vacaciones: quien aprueba lo ve en la aplicación.

Idempotency-Key es obligatoria. Usa un valor único por solicitud (por ejemplo, un UUID) y repítelo al reintentar tras un corte: con la misma clave y los mismos datos (persona, tipo y fechas) se devuelve la misma solicitud, con la cabecera Idempotent-Replayed: true, sin duplicar nada. Con la misma clave y datos distintos, 409 idempotency_key_reutilizada. La clave se acota a la clave de API que la usó.

Códigos propios de esta operación: escritura_no_habilitada, plan_sin_escritura (403, la escritura solo está en el plan Ampliada de la API), ambito_insuficiente y escritura_no_disponible_en_pruebas (403), empresa_inactiva (403), sin_permiso (403), idempotency_key_requerida, idempotency_key_invalida y datos_invalidos (400), persona_no_encontrada (404), idempotency_key_reutilizada y conflicto_al_guardar (409; en el segundo, reintenta con la misma Idempotency-Key), mes_cerrado, ausencia_solapada y persona_de_baja (422). Además los generales de la respuesta Error. Cuenta contra los mismos límites de uso que las lecturas.

Requiere habilitar la escritura. Misma doble llave que POST /ausencias, sin ninguna llave nueva: la opción de empresa «Solicitar ausencias por API» (403 escritura_no_habilitada sin ella) y el ámbito ausencias:escribir (403 ambito_insuficiente). Una clave de pruebas erj_test_ no escribe (403 escritura_no_disponible_en_pruebas).

Retira (pasa a cancelada) una solicitud que creó esta misma clave y que sigue pendiente. Nunca una aprobada o rechazada (409 ausencia_no_cancelable), ni una creada por otra clave, por la aplicación o por otra empresa: en esos casos, y si el identificador no existe, la respuesta es la misma 404 ausencia_no_encontrada, para no revelar qué solicitudes existen. Respeta las reglas de la aplicación: una ausencia que ya ha empezado no se retira (422 ausencia_ya_iniciada) ni una cuyo rango toca un mes cerrado (422 mes_cerrado). La solicitud no se borra: el historial conserva la petición y la retirada. No lleva cuerpo ni Idempotency-Key: repetir la retirada de la propia solicitud ya cancelada por esta clave devuelve lo mismo con Idempotent-Replayed: true.

Códigos propios de esta operación: escritura_no_habilitada, plan_sin_escritura (403, la escritura solo está en el plan Ampliada de la API), ambito_insuficiente y escritura_no_disponible_en_pruebas (403), empresa_inactiva (403), sin_permiso (403), ausencia_no_encontrada (404), ausencia_no_cancelable (409), ausencia_ya_iniciada y mes_cerrado (422). Además los generales de la respuesta Error. Cuenta contra los mismos límites de uso que las lecturas.

Ámbito propio modificaciones:leer (el de proponer no sirve para leer). Expedientes de corrección de fichajes de la empresa de la clave (art. 34.9 ET; la propuesta y la respuesta de la otra parte), abiertos desde la aplicación o desde POST /modificaciones, en cualquier estado: pendiente (con esperaA, la parte que tiene que responder), aceptada (el servidor ya selló un fichaje nuevo que apunta al original), discrepancia (la otra parte no la aceptó) o retirada. Solo sale la propuesta (tipo, hora y día laboral) y las fechas de apertura y resolución: nunca el motivo, las notas de cada paso, quién respondió ni la versión de la persona si discrepa (texto libre que puede contener datos personales). Un expediente guardado con una forma inesperada no sale. desde y hasta filtran por el día laboral propuesto. Orden estable por fecha de apertura.

Requiere habilitar la escritura. Está apagada por defecto en todas las empresas: sin la opción de empresa «Proponer correcciones de fichajes por API» activada por su administración, responde 403 escritura_no_habilitada (activar la escritura de fichajes o la de ausencias no basta: son opciones independientes). Además la clave necesita el ámbito modificaciones:escribir (403 ambito_insuficiente sin él), que no se concede por defecto a ninguna clave y no existe en OAuth. Una clave de pruebas erj_test_ no escribe (403 escritura_no_disponible_en_pruebas).

ABRE una propuesta para corregir la hora o el tipo de UN fichaje existente de una persona de la empresa de la clave (la empresa sale siempre de la clave; no hay parámetro de empresa). Nunca la aplica: nace siempre en estado pendiente, abierta en nombre de la empresa, y espera la respuesta de la PERSONA afectada, que la acepta o la rechaza desde la aplicación como cualquier otra. Al aceptarla, el servidor sella un fichaje NUEVO con origen correccion que apunta al original (corrigeA); el original no se modifica ni se borra. No existe ninguna ruta para aceptar, rechazar, retirar ni modificar una propuesta. El cuerpo no admite estado, parte, historial ni empresa (400).

El fichaje se identifica con asientoId y secuencia (ambos salen de GET /fichajes). Hay que indicar ocurridoEn (instante ISO 8601 con zona), tipo (entrada, salida, inicio_pausa o fin_pausa) o ambos, y que algo cambie respecto al fichaje. El motivo es obligatorio (hasta 1000 caracteres): no se corrige un fichaje sin dejar constancia de por qué. Se rechaza una hora futura (422 hora_futura), un fichaje que ya es una corrección o de un tipo no corregible (422 asiento_no_corregible), si el mes del fichaje o el de la hora propuesta está cerrado (422 mes_cerrado; la aplicación sí admite abrir una modificación sobre un mes cerrado, la API no) y si ese fichaje ya tiene una propuesta pendiente (409 modificacion_pendiente). Un fichaje que no existe, que es de otra persona o de otra empresa da el mismo 404 asiento_no_encontrado.

Idempotency-Key es obligatoria. Usa un valor único por propuesta (por ejemplo, un UUID) y repítelo al reintentar tras un corte: con la misma clave y los mismos datos (persona, fichaje, hora, tipo y motivo) se devuelve la misma propuesta, con la cabecera Idempotent-Replayed: true, sin duplicar nada. Con la misma clave y datos distintos, 409 idempotency_key_reutilizada. La clave se acota a la clave de API que la usó.

Códigos propios de esta operación: escritura_no_habilitada, plan_sin_escritura (403, la escritura solo está en el plan Ampliada de la API), ambito_insuficiente y escritura_no_disponible_en_pruebas (403), empresa_inactiva (403), idempotency_key_requerida, idempotency_key_invalida y datos_invalidos (400), persona_no_encontrada y asiento_no_encontrado (404), idempotency_key_reutilizada, modificacion_pendiente y conflicto_al_guardar (409; en el último, reintenta con la misma Idempotency-Key), mes_cerrado, hora_futura, asiento_no_corregible y persona_de_baja (422). Además los generales de la respuesta Error. Cuenta contra los mismos límites de uso que las lecturas. Emite el evento modificacion.propuesta (solo identificadores) la primera vez, no en un reenvío.

Mismo contenido que en la lista (sin motivo ni notas). Uno de otra empresa, inexistente o guardado con una forma inesperada da el mismo 404 modificacion_no_encontrada. Sirve para seguir una propuesta abierta con POST /modificaciones.

Ámbito propio bolsa:leer. Movimientos de la bolsa de horas de la empresa (art. 34.2 ET): cada uno es la diferencia de un día de una persona, en minutos con signo (positivo, a favor de la persona; negativo, en contra). Los movimientos solo se añaden: un error se compensa con otro de signo contrario. El saldo de una persona es la suma de sus movimientos; la API no aplica el plazo de compensación ni los topes del convenio (los conoce la aplicación, no el servidor). Nunca sale quién apuntó el movimiento ni cuándo. Un movimiento guardado con una forma inesperada no sale. desde y hasta filtran por el día del movimiento. Orden estable por día.

Orden estable por inicio. La excepción escrita de un turno no sale.

Cuelga de empresa:leer. No confundir con GET /calendario (ausencias del equipo por días).

Con calendario:leer solo sale el nombre («ausente», sin tipo); con ausencias:leer también el tipo (una baja médica sale solo como baja, nunca con su motivo). Solo ausencias aprobadas, por días naturales y solo los días con alguien ausente. Rango obligatorio de como mucho 93 días (422 rango_demasiado_amplio). Paginado por días.

Calendario en formato iCalendar (RFC 5545) para leerlo desde otro sistema con la clave en la cabecera Authorization (de servidor a servidor). Para compartirlo con una persona sin clave existe el enlace privado y revocable que se crea en la aplicación. Solo ausencias aprobadas. Sin persona: el equipo, cada ausencia como «Nombre A. · Ausente», sin tipo ni motivo y sin turnos; quien causó baja antes de hoy no sale. Con persona: sus ausencias (con el tipo solo si la clave tiene ausencias:leer; si no, «Ausente») y, si la clave tiene turnos:leer, sus turnos publicados con los cambios de turno aprobados. Por defecto, de 30 días atrás a 365 días adelante; como mucho 400 días por llamada (422 rango_demasiado_amplio). Cada evento lleva un UID estable, así que un cambio actualiza el evento en vez de duplicarlo. Los errores salen en JSON, como en el resto de rutas.

Cumplimiento como servicio: comprueba lo que se envía contra el Estatuto de los Trabajadores (texto refundido, Real Decreto Legislativo 2/2015, https://www.boe.es/buscar/act.php?id=BOE-A-2015-11430) con las mismas reglas que usa la aplicación. Solo calcula: no lee datos de la empresa ni guarda el cuerpo (el registro de llamadas anota la ruta, el estado y la duración, nunca el contenido). Tres modos: cuadrante (turnos): descanso entre jornadas y jornada diaria (art. 34.3, https://www.boe.es/buscar/act.php?id=BOE-A-2015-11430#a34), turnos solapados y turnos mal formados. propuesta (existentes y propuestos): lo mismo, pero solo devuelve lo que provocan los turnos propuestos. jornadas (jornadas, tramos ya trabajados): además, semana por encima de 40 h ordinarias (art. 34.1, cómputo anual, por eso es un aviso), pausa en jornada continuada de más de 6 h (art. 34.4) y descanso semanal (art. 37.1, https://www.boe.es/buscar/act.php?id=BOE-A-2015-11430#a37); el umbral de aviso de 35 h de descanso semanal y el de más de 12 días seguidos son criterios propios de aviso, no cifras de la norma. En este modo todo lo enviado cuenta como jornada ordinaria. Cada incumplimiento lleva cita con el artículo y el enlace al BOE, o null si no hay norma detrás (un turno mal formado o un solape). Es orientativo, no un dictamen: un convenio colectivo o un acuerdo pueden fijar otra distribución (art. 34.2 y 34.3); por eso se aceptan limites y se devuelven los aplicados. Como mucho 500 elementos y 400 días por llamada; el cuerpo, hasta 128 KiB. Con GET, 405 y Allow: POST, OPTIONS.

Solo los meses cerrados, del más antiguo al más reciente, con su estado y un resumen agregado (personas, minutos trabajados y extraordinarios, firmas de las personas y correcciones anotadas). Nunca salen los resúmenes por persona, los hash, quién cerró ni los motivos de las correcciones.

mes con formato AAAA-MM (otro formato da 400 parametro_invalido). Un mes sin cierre sale como abierto, sin resumen.

Cuelga de cierres:leer, como el resumen del cierre (que ya da los recuentos). Una fila por cada persona incluida en el cierre del mes, con su estado (confirmado, discrepa o sin_firmar, según su última firma) y cuándo firmó por última vez. Nunca el motivo de una discrepancia, los hash ni el resumen de la persona. Un mes sin cierre no tiene firmas: lista vacía. mes con formato AAAA-MM (otro formato da 400 parametro_invalido). Orden estable por persona.

Avisos «a revisar» calculados sobre los asientos con el mismo motor que el cierre del mes (tramos sin cerrar, descansos cortos, jornadas largas, pausa no registrada…). No son infracciones: la valoración la hace la empresa. No hay estado «resuelta»: un aviso desaparece cuando el registro se corrige. Rango de fechas laborales: por defecto los últimos 7 días y como mucho 31 días (422 rango_demasiado_amplio).

Listado de los informes y exportaciones de la empresa, del más antiguo al más reciente, con su estado y los metadatos del archivo (nombre, tipo y tamaño). No incluye quién lo pidió, los parámetros internos ni la descarga: el enlace de descarga solo sale en GET /informes/{informeId} y solo para la clave que lo generó con POST /informes; el resto se descarga con la sesión de la empresa en la aplicación.

Pide un informe y responde 202 sin esperar a que se haga, con el informe en estado en_cola y la cabecera Location (/api/v1/informes/{informeId}). Un proceso del servidor lo hace después; consulta GET /informes/{informeId} (con informes:leer) hasta que esté terminado, fallido o caducado. El estado pasa por en_cola → en_proceso → terminado | fallido | caducado; un fallo pasajero se reintenta solo, con espera creciente, hasta 3 intentos. Uno que nadie llega a hacer caduca a las 24 horas.

Hoy solo se genera tipo: exportacion: los asientos de la empresa registrados entre desde y hasta (como mucho 366 días), en CSV y sin el documento de identidad. No modifica ningún dato.

Ámbitos: informes:generar más fichajes:leer y personas:leer (el archivo lleva fichajes y nombres: un informe nunca da más de lo que la clave ya podría leer). informes:generar solo lo concede el panel de Integraciones a la administración de la empresa, nunca OAuth, y solo en los planes de pago de la API: en el resto responde 403 plan_sin_informes. Una clave de pruebas erj_test_ no genera (403 generacion_no_disponible_en_pruebas).

Idempotency-Key es obligatoria. Con la misma clave y los mismos datos se devuelve el mismo informe (200 y Idempotent-Replayed: true) sin crear otro; con la misma clave y otros datos, 409 idempotency_key_reutilizada. La clave se acota a la clave de API que la usó.

Límites: como mucho 10 informes al día por empresa (día UTC, entre todas sus claves; repetir con la misma Idempotency-Key no gasta): si no, 429 limite_diario_informes. Además, como mucho 3 informes sin terminar por clave en el plan Ampliada, y 3 entre todas las claves de la empresa (se reservan huecos para la aplicación): si no, 429 demasiados_informes_abiertos. Cuenta además contra los límites de uso de siempre. El informe lo hace el servidor en su pasada diaria, no al momento.

Códigos propios de esta operación: generacion_no_disponible_en_pruebas, plan_sin_informes, ambito_insuficiente y empresa_inactiva (403), idempotency_key_requerida, idempotency_key_invalida y datos_invalidos (400), idempotency_key_reutilizada (409), demasiados_informes_abiertos y limite_diario_informes (429) y trabajos_sin_configurar (503). Además los generales de la respuesta Error.

404 informe_no_encontrado si no es de esta empresa. Si lo generó ESTA clave con POST /informes, está terminado y la clave tiene los ámbitos de generar, la respuesta trae descarga: el enlace firmado para descargar el archivo, válido 15 minutos como mucho (consulta de nuevo para obtener otro).

Entrega el archivo (hoy, CSV) de un informe generado por ESTA clave con POST /informes. Usa el enlace del campo descarga de GET /informes/{informeId}: la firma ata la descarga a ese informe, a la empresa, a esta clave y a un instante de caducidad (15 minutos como mucho, y nunca más allá de la caducidad del archivo). Hace falta además la cabecera Authorization de la misma clave. Otra clave, aunque sea de la misma empresa, recibe 404 informe_no_encontrado, igual que si no existiera. La respuesta lleva Cache-Control: no-store.

Mismos ámbitos que generar: informes:generar, fichajes:leer y personas:leer.

Códigos propios de esta operación: generacion_no_disponible_en_pruebas, ambito_insuficiente, empresa_inactiva, firma_requerida, firma_invalida y firma_vencida (403), informe_no_encontrado (404), informe_no_listo e informe_fallido (409), informe_caducado (410) y trabajos_sin_configurar y descarga_sin_configurar (503). Además los generales de la respuesta Error.

Ámbito delicado: concédelo solo a quien administra. Solo los eventos de la propia empresa, del más antiguo al más reciente, sin el detalle del evento ni los hash de la cadena (que es de todas las empresas). Incluye los rechazos por ámbito de las claves de API; las lecturas correctas con clave no se anotan. hasta es exclusivo. Cada llamada lee como mucho 1.000 eventos de la empresa: con filtros, una página puede traer menos que limit (o ninguno) y siguiente; sigue pidiendo hasta que siguiente sea null. El cursor cuenta solo los eventos de tu empresa (con los mismos filtros), nunca la numeración de la cadena común, y se admite hasta el evento 20.000: más allá, 400 cursor_invalido; acota con desde/hasta.

Ámbito propio eventos:leer (ningún otro lo sustituye). Alternativa a los webhooks: eventos de la empresa de la clave, del más antiguo al más reciente, solo con identificadores y fechas (sin nombres, NIF ni motivos; quien quiera más datos los pide al recurso con el identificador). Hoy se emiten fichaje.creado, ausencia.solicitada, ausencia.aprobada, cuadrante.publicado, cierre.realizado y modificacion.propuesta. Paginación por cursor: guarda el siguiente de la respuesta y pásalo como desde en la siguiente llamada (con la página vacía, siguiente es el mismo desde: sirve para sondear). hayMas indica si quedan eventos ya registrados. Un desde que no sea un cursor devuelto por la API da 400 parametro_invalido. El orden es el de registro (secuencia por empresa), no el del instante del evento: uno emitido con el reloj atrasado se entrega después de los ya leídos, no se pierde. El cursor es opaco: no lo interpretes ni lo construyas.

La única ruta sin ámbito: no lee datos de la empresa, solo describe la clave (o el token OAuth) con la que se llama: sus ámbitos, su caducidad, el plan de la API de la empresa y su consumo del minuto y del mes, contando esta misma llamada (son las cifras de las cabeceras X-RateLimit-* y X-Monthly-*, que llevan todas las respuestas). Nada de otras claves. Cuenta contra los límites como cualquier llamada. Con una clave erj_test_, entorno es pruebas, plan es null y no hay tope mensual (limite y restantes del mes son null). Una clave de dispositivo (erj_disp_, la de una tableta de fichaje) recibe 403 ambito_insuficiente.