OpenJornada
Comença Gratuïtament
Tornar a la documentació
Referència de l'API

API REST d'OpenJornada

Documentació tècnica completa per integrar OpenJornada amb altres sistemes. API RESTful amb autenticació JWT i respostes en format JSON.

URL base

https://tu-dominio.com/api

Tots els endpoints estan sota el prefix /api. La documentació interactiva està disponible a /api/docs (Swagger UI) i /api/redoc (ReDoc).

Contingut

Autenticació Treballadors Empreses Registres de jornada Tipus de pausa Incidències Sol·licituds de canvi Sol·licituds d'absència Polítiques d'absència Configuració Còpies de seguretat RGPD

Autenticació

L'API utilitza tokens JWT (JSON Web Tokens) per a l'autenticació. Els tokens s'obtenen mitjançant l'endpoint /api/token i s'han d'incloure a la capçalera Authorization de totes les peticions protegides.

POST/api/tokenObtenir token d'accés

Autentica un usuari administrador i retorna un token JWT.

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

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

Ús del token

Inclou el token a totes les peticions protegides:

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

Retorna la informació de l'usuari autenticat actualment.

POST/api/forgot-passwordSol·licitar restabliment de contrasenya

Envia un correu amb instruccions per restablir la contrasenya (usuaris admin).

POST/api/reset-passwordRestablir contrasenya

Restableix la contrasenya utilitzant el token rebut per correu.

Treballadors

Gestió de treballadors: crear, actualitzar, llistar i eliminar treballadors. Els treballadors poden pertànyer a múltiples empreses.

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"
}

Empreses

Gestió d'empreses. Cada treballador ha d'estar associat com a mínim a una empresa. Les empreses no es poden eliminar si tenen treballadors associats.

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)

Registres de jornada

Registre d'entrada, sortida i pauses. El sistema detecta automàticament el tipus de registre basant-se en l'estat actual del treballador.

Tipus de registre

  • entry - Entrada/inici de jornada
  • exit - Sortida/fi de jornada
  • pause_start - Inici de pausa
  • pause_end - Fi 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"
}

Tipus de pausa

Configuració de tipus de pausa per empresa. Cada tipus pot ser "dins de jornada" (compta com a temps treballat) o "fora de jornada".

Tipus de pausa

  • inside_shift - Dins de jornada (descans remunerat)
  • outside_shift - Fora de jornada (no remunerat)
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"
}

Incidències

Sistema de report d'incidències. Els treballadors poden reportar problemes i els administradors poden gestionar-los.

Estats d'incidència

  • pending - Pendent de revisió
  • in_progress - En curs
  • resolved - Resolta
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)"
}

Sol·licituds de canvi

Els treballadors poden sol·licitar correccions als seus registres de temps. Els administradors revisen i accepten/rebutgen les sol·licituds.

Estats de la sol·licitud

  • pending - Pendent de revisió
  • accepted - Acceptada i aplicada
  • rejected - Rebutjada
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)"
}

Sol·licituds d'absència

Gestió d'absències i vacances. Els treballadors creen sol·licituds que els administradors accepten o rebutgen.

GET/absences/ AuthLlista les absències d'una empresa (admin). Filtra per estat, treballador i dates.
Query params:
  • * company_id*, status, worker_id, start_date, end_date
POST/absences/Crea una sol·licitud d'absència. El treballador s'autentica amb correu/contrasenya.
Request body:
{
  "email": "string",
  "password": "string",
  "company_id": "string",
  "absence_type_code": "string",
  "start_date": "YYYY-MM-DD",
  "end_date": "YYYY-MM-DD",
  "worker_comment": "string (optional)"
}
POST/absences/meHistorial d'absències del treballador autenticat.
Request body:
{
  "email": "string",
  "password": "string",
  "company_id": "string (optional)",
  "status_filter": "pending|accepted|rejected|cancelled (optional)",
  "limit": "number (optional)"
}
POST/absences/attachmentsPuja un justificant (PDF o imatge, màx. 5 MB). Retorna attachment_id.
GET/absences/attachments/{attachment_id} AuthDescarrega un justificant per ID. Admin.
GET/absences/calendar AuthCalendari d'absències de l'equip (admin). Només absències acceptades.
Query params:
  • * company_id*, start_date*, end_date*
PATCH/absences/{id} AuthAccepta o rebutja una sol·licitud (admin). Registra auditoria.
Request body:
{
  "status": "accepted | rejected",
  "admin_internal_notes": "string (optional)",
  "admin_public_comment": "string (optional)"
}
POST/absences/me/{id}/cancelCancel·la una sol·licitud pendent del propi treballador.
Request body:
{
  "email": "string",
  "password": "string"
}

Polítiques d'absència

Configuració de la política d'absències per empresa. Esembra automàtica en el primer accés.

GET/absence-policies/{company_id} AuthObté la política d'absències d'una empresa.
PUT/absence-policies/{company_id} AuthCrea o actualitza la política d'absències d'una empresa (admin).
Request body:
{
  "annual_vacation_days": "number",
  "computation_mode": "business_days | calendar_days",
  "reference_year_mode": "calendar | hire_date",
  "minimum_advance_days": "number",
  "allow_half_day": "boolean",
  "allow_hourly": "boolean",
  "max_overlap": "number",
  "absence_types": "array"
}

Configuració

Configuració general de l'aplicació: correu de contacte i configuració de còpies de seguretat automàtiques.

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"
  }
}

Còpies de seguretat

Gestió de còpies de seguretat. Suporta emmagatzematge local, S3 i SFTP. Les còpies es creen en format comprimit amb verificació d'integritat.

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 (Drets ARCO)

Endpoints per al compliment del RGPD. Permeten exportar i anonimitzar dades de treballadors respectant els períodes legals de retenció.

Drets implementats

  • Dret d'accés (Art. 15 RGPD)
  • Dret a la portabilitat de les dades (Art. 20 RGPD)
  • Dret a l'oblit (Art. 17 RGPD) - amb retenció 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

L'anonimització preserva els registres de jornada de forma anònima per complir l'obligació legal de conservar-los durant 4 anys (Art. 34.9 de l'Estatut dels Treballadors).

Codis d'error

CodiDescripció
400Bad Request - Dades no vàlides o que falten
401Unauthorized - Token no vàlid o caducat
403Forbidden - Sense permisos per a aquesta acció
404Not Found - Recurs no trobat
409Conflict - Conflicte amb l'estat actual
429Too Many Requests - Límit de peticions superat
500Internal Server Error - Error del servidor

La documentació interactiva completa està disponible a la teva instància d'OpenJornada.

Tornar a la documentació
API REST OpenJornada - Documentació tècnica i endpoints