OpenJornada
Comenzar Gratis
Volver a documentacion
Referencia de API

API REST de OpenJornada

Documentacion tecnica completa para integrar OpenJornada con otros sistemas. API RESTful con autenticacion JWT y respuestas en formato JSON.

URL Base

https://tu-dominio.com/api

Todos los endpoints estan bajo el prefijo /api. La documentacion interactiva esta disponible en /api/docs (Swagger UI) y /api/redoc (ReDoc).

Contenido

Autenticacion Trabajadores Empresas Registros de Jornada Tipos de Pausa Incidencias Solicitudes de Cambio Configuracion Backups RGPD

Autenticacion

La API utiliza tokens JWT (JSON Web Tokens) para la autenticacion. Los tokens se obtienen mediante el endpoint /api/token y deben incluirse en el header Authorization de todas las peticiones protegidas.

POST/api/tokenObtener token de acceso

Autentica un usuario administrador y devuelve un token JWT.

# Request (form-data)
username: admin@example.com
password: tu_contraseña

# Response
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer"
}

Uso del Token

Incluye el token en todas las peticiones protegidas:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
GET/api/users/meUsuario actual

Devuelve la informacion del usuario autenticado actualmente.

POST/api/forgot-passwordSolicitar reset de password

Envia un email con instrucciones para restablecer la contrasena (usuarios admin).

POST/api/reset-passwordRestablecer password

Restablece la contrasena usando el token recibido por email.

Trabajadores

Gestion de trabajadores: crear, actualizar, listar y eliminar trabajadores. Los trabajadores pueden pertenecer a multiples empresas.

GET/api/workers/ AuthListar todos los trabajadores activos
POST/api/workers/ AuthCrear nuevo trabajador
Request body:
{
  "first_name": "string",
  "last_name": "string",
  "email": "string",
  "password": "string",
  "id_number": "string (DNI/NIE)",
  "phone_number": "string (opcional)",
  "company_ids": [
    "string"
  ],
  "send_welcome_email": "boolean (opcional)"
}
GET/api/workers/{worker_id} AuthObtener trabajador por ID
PUT/api/workers/{worker_id} AuthActualizar trabajador
DELETE/api/workers/{worker_id} AuthEliminar trabajador (soft delete)
PATCH/api/workers/change-passwordCambiar contrasena (endpoint publico para trabajadores)
Request body:
{
  "email": "string",
  "current_password": "string",
  "new_password": "string"
}
POST/api/workers/forgot-passwordSolicitar reset de password de trabajador
POST/api/workers/my-companiesObtener empresas del trabajador autenticado
Request body:
{
  "email": "string",
  "password": "string"
}

Empresas

Gestion de empresas. Cada trabajador debe estar asociado al menos a una empresa. Las empresas no pueden eliminarse si tienen trabajadores asociados.

GET/api/companies/ AuthListar todas las empresas
Query params:
  • • include_deleted: boolean (opcional)
POST/api/companies/ AuthCrear nueva empresa
Request body:
{
  "name": "string"
}
GET/api/companies/{company_id} AuthObtener empresa por ID
PATCH/api/companies/{company_id} AuthActualizar empresa
DELETE/api/companies/{company_id} AuthEliminar empresa (soft delete)

Registros de Jornada

Registro de entrada, salida y pausas. El sistema detecta automaticamente el tipo de registro basandose en el estado actual del trabajador.

Tipos de Registro

  • entry - Entrada/inicio de jornada
  • exit - Salida/fin de jornada
  • pause_start - Inicio de pausa
  • pause_end - Fin de pausa
POST/api/time-records/ AuthCrear registro de tiempo (entrada/salida/pausa)
Request body:
{
  "email": "string",
  "password": "string",
  "company_id": "string",
  "action": "entry | exit | pause_start | pause_end (opcional)",
  "pause_type_id": "string (requerido para pause_start)",
  "timezone": "string (opcional, default: UTC)"
}
GET/api/time-records/ AuthListar todos los registros (admin)
Query params:
  • • start_date: YYYY-MM-DD
  • • end_date: YYYY-MM-DD
  • • company_id: string
  • • worker_name: string
  • • timezone: string
GET/api/time-records/worker/{worker_id} AuthRegistros de un trabajador especifico
Query params:
  • • start_date: YYYY-MM-DD
  • • end_date: YYYY-MM-DD
POST/api/time-records/current-statusEstado actual del trabajador (webapp)
Request body:
{
  "email": "string",
  "password": "string",
  "company_id": "string"
}
POST/api/time-records/worker/historyHistorial del trabajador autenticado
Request body:
{
  "email": "string",
  "password": "string",
  "company_id": "string",
  "start_date": "YYYY-MM-DD",
  "end_date": "YYYY-MM-DD"
}

Tipos de Pausa

Configuracion de tipos de pausa por empresa. Cada tipo puede ser "dentro de jornada" (cuenta como tiempo trabajado) o "fuera de jornada".

Tipos de Pausa

  • inside_shift - Dentro de jornada (descanso remunerado)
  • outside_shift - Fuera de jornada (no remunerado)
GET/api/pause-types/ AuthListar tipos de pausa
Query params:
  • • include_deleted: boolean
  • • company_id: string
POST/api/pause-types/ AuthCrear tipo de pausa
Request body:
{
  "name": "string",
  "type": "inside_shift | outside_shift",
  "description": "string (opcional)",
  "company_ids": [
    "string"
  ]
}
PUT/api/pause-types/{pause_type_id} AuthActualizar tipo de pausa
DELETE/api/pause-types/{pause_type_id} AuthEliminar tipo de pausa (soft delete)
POST/api/pause-types/availablePausas disponibles para trabajador (webapp)
Request body:
{
  "email": "string",
  "password": "string",
  "company_id": "string"
}

Incidencias

Sistema de reporte de incidencias. Los trabajadores pueden reportar problemas y los administradores pueden gestionarlos.

Estados de Incidencia

  • pending - Pendiente de revision
  • in_progress - En proceso
  • resolved - Resuelta
POST/api/incidents/ AuthCrear incidencia (trabajador)
Request body:
{
  "email": "string",
  "password": "string",
  "description": "string"
}
GET/api/incidents/ AuthListar incidencias
Query params:
  • • status: pending|in_progress|resolved
  • • worker_id: string
  • • start_date: YYYY-MM-DD
  • • end_date: YYYY-MM-DD
GET/api/incidents/{incident_id} AuthObtener incidencia por ID
PATCH/api/incidents/{incident_id} AuthActualizar incidencia (admin)
Request body:
{
  "status": "pending | in_progress | resolved",
  "admin_notes": "string (opcional)"
}

Solicitudes de Cambio

Los trabajadores pueden solicitar correcciones en sus registros de tiempo. Los administradores revisan y aprueban/rechazan las solicitudes.

Estados de Solicitud

  • pending - Pendiente de revision
  • accepted - Aceptada y aplicada
  • rejected - Rechazada
POST/api/change-requests/ AuthCrear solicitud de cambio
Request body:
{
  "email": "string",
  "password": "string",
  "time_record_id": "string",
  "company_id": "string",
  "date": "YYYY-MM-DD",
  "new_timestamp": "ISO 8601 datetime",
  "reason": "string"
}
POST/api/change-requests/pending/check AuthVerificar si tiene solicitud pendiente
GET/api/change-requests/ AuthListar solicitudes de cambio
Query params:
  • • status: pending|accepted|rejected
  • • worker_id: string
  • • start_date: YYYY-MM-DD
  • • end_date: YYYY-MM-DD
GET/api/change-requests/{id} AuthObtener solicitud por ID
PATCH/api/change-requests/{id} AuthAprobar o rechazar solicitud
Request body:
{
  "status": "accepted | rejected",
  "admin_internal_notes": "string (opcional)",
  "admin_public_comment": "string (opcional)"
}

Configuracion

Configuracion general de la aplicacion: email de contacto y configuracion de backups automaticos.

GET/api/settings/ AuthObtener configuracion actual
PATCH/api/settings/ AuthActualizar configuracion
Request body:
{
  "contact_email": "string (opcional)",
  "backup_config": {
    "enabled": "boolean",
    "schedule": {
      "hour": "number",
      "minute": "number"
    },
    "retention_days": "number",
    "storage_type": "local | s3 | sftp"
  }
}

Backups

Gestion de copias de seguridad. Soporta almacenamiento local, S3 y SFTP. Los backups se realizan en formato comprimido con verificacion de integridad.

GET/api/backups/ AuthListar todos los backups
POST/api/backups/trigger AuthCrear backup manual
GET/api/backups/{backup_id} AuthObtener detalles de backup
DELETE/api/backups/{backup_id} AuthEliminar backup
POST/api/backups/{backup_id}/restore AuthRestaurar desde backup
Request body:
{
  "confirm": "boolean (debe ser true)"
}
GET/api/backups/{backup_id}/download AuthDescargar backup (local storage)
GET/api/backups/{backup_id}/download-url AuthObtener URL de descarga (S3)
POST/api/backups/test-connection AuthProbar conexion de almacenamiento
GET/api/backups/schedule/status AuthEstado de backups programados

RGPD (Derechos ARCO)

Endpoints para cumplimiento del RGPD. Permiten exportar y anonimizar datos de trabajadores respetando los periodos legales de retencion.

Derechos Implementados

  • Derecho de acceso (Art. 15 RGPD)
  • Derecho a la portabilidad (Art. 20 RGPD)
  • Derecho al olvido (Art. 17 RGPD) - con retencion legal
GET/api/gdpr/worker/{worker_id}/export AuthExportar todos los datos del trabajador
GET/api/gdpr/worker/{worker_id}/data AuthObtener datos personales (simplificado)
POST/api/gdpr/worker/{worker_id}/anonymize AuthAnonimizar datos del trabajador
Request body:
{
  "reason": "string (min 5 caracteres)"
}

Importante

La anonimizacion preserva los registros de jornada de forma anonima para cumplir con la obligacion legal de conservarlos durante 4 anos (Art. 34.9 del Estatuto de los Trabajadores).

Codigos de Error

CodigoDescripcion
400Bad Request - Datos invalidos o faltantes
401Unauthorized - Token invalido o expirado
403Forbidden - Sin permisos para esta accion
404Not Found - Recurso no encontrado
409Conflict - Conflicto con estado actual
429Too Many Requests - Rate limit excedido
500Internal Server Error - Error del servidor

La documentacion interactiva completa esta disponible en tu instancia de OpenJornada.

Volver a documentacion