API v1

Solo lectura

Conecta tu plataforma con Jornalia

Consulta empleados, horarios y fichajes desde tu propia plataforma. Esta referencia describe los endpoints de lectura, sus parámetros y las respuestas que puedes recibir.

URL basehttps://jornalia.es/api/v1

Todos los endpoints necesitan un token para funcionar

Incluye el token de integración en el header Authorization de cada petición. La empresa se determina por ese token: solo podrás consultar sus empleados y fichajes. Iniciar sesión en la web no sustituye al token.

Header obligatorio en todas las peticiones

Authorization: Bearer <token>

Un administrador de Jornalia genera el token desde la ficha de tu empresa. Su formato es jornalia_live_sec_ seguido de 64 caracteres hexadecimales. Se muestra una sola vez; si se pierde, hay que sustituirlo. Al sustituirlo o revocarlo, el anterior deja de autorizar nuevas peticiones.

Usa el token desde el servidor de tu plataforma y mediante HTTPS. No lo incluyas en URLs ni en código del navegador: permite leer datos personales y PIN de los empleados. Los ejemplos usan $JORNALIA_TOKEN como variable de entorno y nunca contienen credenciales reales.

Paginación y respuestas

Empleados y fichajes devuelven data como un array y pagination con total, limit, offset y next_offset. El tamaño por defecto es 100; puedes solicitar entre 1 y 500. Para continuar, usa el valor de next_offset como offset hasta que sea null. El endpoint de estado devuelve un objeto, sin paginación.

limit=100 & offset=0 → next_offset

La paginación refleja los datos disponibles en cada petición. Las respuestas no se guardan en caché. Los timestamps usan UTC; las horas semanales de los turnos son horas locales.

Endpoints

3 GET

GET

/api/v1/employees

Empleados

Obtén los datos de los empleados de tu empresa, con su PIN, estado y horario asignado. Puedes consultar un correo, varios o listar toda la empresa.

Authorization: Bearer obligatorio

Parámetros de consulta

Parámetros de consulta — /api/v1/employees
Parámetro	Descripción y ejemplo
`email`string · emailOpcional	Filtra por correo. Puedes repetir email o separar los valores por comas, hasta 100 correos. Sin email, o si está vacío, devuelve todos los empleados de la empresa, incluidos los inactivos.`ana@example.com`
`limit`integerOpcional	Número máximo de resultados por página: de 1 a 500. Por defecto: 100.`100`
`offset`integerOpcional	Número de resultados que se omiten: de 0 a 1000000. Por defecto: 0.`0`

Solo aparecen empleados de la empresa del token. Un correo inexistente o perteneciente a otra empresa no aparece en data.
status puede ser active o inactive. login_pin puede ser null; tener un PIN asignado no implica que el acceso por PIN esté habilitado para la empresa.
shift contiene el turno con type: predefined o el horario personalizado vigente con type: custom. Si no hay asignación, es null. El personalizado vigente tiene prioridad; no se expone su historial.
Los tramos de shift.segments usan horas locales y day_of_week de 0 (domingo) a 6 (sábado). Incluyen turnos partidos y centros en los horarios personalizados. Si end_time es anterior a start_time, el tramo termina al día siguiente.

Ejemplo de petición · cURL

curl --get 'https://jornalia.es/api/v1/employees' \
  --header "Authorization: Bearer $JORNALIA_TOKEN" \
  --data-urlencode 'email=ana@example.com' \
  --data-urlencode 'limit=100'

Respuestas

Ejemplos con datos ficticios. Selecciona una respuesta para ver su estructura JSON.

200 · application/json

{
  "success": true,
  "data": [
    {
      "id": "40000000-0000-4000-8000-000000000011",
      "company_id": "40000000-0000-4000-8000-000000000001",
      "first_name": "Ana",
      "last_name": "Example",
      "email": "ana@example.com",
      "phone": "+34600000000",
      "active": true,
      "status": "active",
      "login_pin": "12345",
      "photo_profile_path": null,
      "work_center_id": null,
      "created_at": "2026-10-01T08:00:00Z",
      "updated_at": null,
      "shift": {
        "type": "predefined",
        "id": "40000000-0000-4000-8000-000000000021",
        "name": "Morning",
        "category": "work_shift",
        "schedule_type": "complete",
        "break_minutes": 30,
        "start_time": "08:00:00",
        "end_time": "16:00:00",
        "second_start_time": null,
        "second_end_time": null,
        "created_at": "2026-10-01T08:00:00Z",
        "updated_at": null,
        "segments": [
          {
            "day_of_week": 1,
            "start_time": "08:00",
            "end_time": "16:00",
            "position": 0
          }
        ],
        "holidays": []
      }
    }
  ],
  "pagination": {
    "total": 1,
    "offset": 0,
    "limit": 100,
    "next_offset": null
  }
}

GET

/api/v1/time-records

Fichajes

Consulta los fichajes de un empleado por correo. Puedes limitar el intervalo o recorrer todo su histórico por páginas.

Authorization: Bearer obligatorio

Parámetros de consulta

Parámetros de consulta — /api/v1/time-records
Parámetro	Descripción y ejemplo
`email`string · emailObligatorio	Correo de un único empleado de la empresa. La coincidencia es exacta, sin distinguir mayúsculas.`ana@example.com`
`from`string · ISO 8601Opcional	Inicio opcional del intervalo. Fecha ISO 8601 con zona horaria, Z o un desplazamiento como -03:00. Debe ser anterior a to si se indican ambos.`2026-10-01T00:00:00Z`
`to`string · ISO 8601Opcional	Fin opcional y excluyente del intervalo. Fecha ISO 8601 con zona horaria. Puede usarse sin from.`2026-11-01T00:00:00Z`
`limit`integerOpcional	Número máximo de resultados por página: de 1 a 500. Por defecto: 100.`100`
`offset`integerOpcional	Número de resultados que se omiten: de 0 a 1000000. Por defecto: 0.`0`

Devuelve registros que se solapan con [from, to): start_at < to y end_at > from, o end_at null. Incluye los turnos iniciados antes del intervalo que siguen dentro de él y los turnos nocturnos.
from y to son independientes y opcionales. Sin fechas se devuelve todo el histórico por páginas, ordenado por start_at e id. Los registros sin inicio no coinciden con filtros temporales.
Incluye trabajo y descansos, conserva los campos nulos y excluye los registros eliminados. Los timestamps no se recortan al intervalo solicitado.

Ejemplo de petición · cURL

curl --get 'https://jornalia.es/api/v1/time-records' \
  --header "Authorization: Bearer $JORNALIA_TOKEN" \
  --data-urlencode 'email=ana@example.com' \
  --data-urlencode 'from=2026-10-01T00:00:00Z' \
  --data-urlencode 'to=2026-11-01T00:00:00Z'

Respuestas

Ejemplos con datos ficticios. Selecciona una respuesta para ver su estructura JSON.

200 · application/json

{
  "success": true,
  "data": [
    {
      "id": "40000000-0000-4000-8000-000000000041",
      "start_at": "2026-10-15T08:00:00Z",
      "end_at": null,
      "observation": "work",
      "employee_id": "40000000-0000-4000-8000-000000000011",
      "company_id": "40000000-0000-4000-8000-000000000001",
      "record_type": "full_registration",
      "manual": false,
      "editor_note": null
    }
  ],
  "pagination": {
    "total": 1,
    "offset": 0,
    "limit": 100,
    "next_offset": null
  }
}

GET

/api/v1/employees/status

Estado de fichaje

Consulta si un empleado está trabajando, en pausa o sin fichaje abierto, junto con sus registros abiertos de trabajo y descanso.

Authorization: Bearer obligatorio

Parámetros de consulta

Parámetros de consulta — /api/v1/employees/status
Parámetro	Descripción y ejemplo
`email`string · emailObligatorio	Correo de un único empleado de la empresa. La coincidencia es exacta, sin distinguir mayúsculas.`ana@example.com`

attendance puede ser working, paused o clocked_out. work_record y pause_record contienen el registro correspondiente o null.
active y status expresan el estado de alta del empleado. attendance expresa su fichaje: un empleado inactivo puede conservar un registro abierto.
Busca registros abiertos sin limitarse al día actual, incluidos los turnos nocturnos. Ignora los fichajes eliminados y los descansos anteriores al fichaje actual.

Ejemplo de petición · cURL

curl --get 'https://jornalia.es/api/v1/employees/status' \
  --header "Authorization: Bearer $JORNALIA_TOKEN" \
  --data-urlencode 'email=ana@example.com'

Respuestas

Ejemplos con datos ficticios. Selecciona una respuesta para ver su estructura JSON.

200 · application/json

{
  "success": true,
  "data": {
    "employee_id": "40000000-0000-4000-8000-000000000011",
    "email": "ana@example.com",
    "active": true,
    "status": "active",
    "attendance": "working",
    "work_record": {
      "id": "40000000-0000-4000-8000-000000000041",
      "start_at": "2026-10-15T08:00:00Z",
      "end_at": null,
      "observation": "work"
    },
    "pause_record": null
  }
}

Códigos de error

Los errores de la API devuelven success: false y un objeto error con code y message. La lista de respuestas de cada endpoint muestra sus errores posibles. Una búsqueda de empleados sin coincidencias devuelve 200 con data: [], no un 404.

400

invalid_query

Parámetros desconocidos o duplicados, correo inválido, paginación fuera de límites o fechas sin zona horaria, iguales o invertidas.

401

invalid_token

Falta el token o está mal formado, es desconocido, ha sido sustituido o está revocado. Envía una credencial vigente en Authorization: Bearer.

404

employee_not_found

El empleado no existe en la empresa del token. Este error se devuelve en fichajes y estado; en la búsqueda de empleados se devuelve una lista vacía.

500

internal_error

No se ha podido completar la consulta. La respuesta no expone detalles internos de base de datos. Inténtalo de nuevo.

Esta API de integración solo expone operaciones de lectura. Las peticiones POST, PUT, PATCH y DELETE reciben 405 Method Not Allowed.