Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:
1

Java Development Kit

Java 25 or later is required. Verify your installation:
java -version
2

Maven

Maven is required for building the project:
mvn -version
3

MariaDB Database

MariaDB server running locally or accessible remotely:
mysql --version

​
Installation

​
1. Clone and Build

# Build the project
mvn clean install

# Run the application
mvn spring-boot:run
The server will start on port 8081 by default.

​
2. Database Configuration

Create the Integra database and schema: 
CREATE DATABASE integra;
CREATE SCHEMA comialex;
Update src/main/resources/application.yml with your database credentials: 
spring:
  datasource:
    driver-class-name: org.mariadb.jdbc.Driver
    url: jdbc:mariadb://localhost:3306/integra?useSSL=false
    username: your_username
    password: your_password
    hikari:
      maximum-pool-size: 30
      connection-timeout: 60000
      idle-timeout: 600000
  jpa:
    hibernate:
      ddl-auto: none
    properties:
      hibernate:
        default_schema: comialex
Make sure to set ddl-auto: none in production and manage schema migrations properly.

​
3. JWT Key Configuration

Integra uses RSA key pairs for JWT signing. Ensure you have the key files in place: 
security:
  jwt:
    private-key: classpath:certs/private.pem
    public-key: classpath:certs/public.pem
    expiration: 2592000         # 30 days in seconds
    refresh-expiration: 2592000 # 30 days in seconds
Place your private.pem and public.pem files in src/main/resources/certs/.
Generate RSA key pairs using OpenSSL:
openssl genrsa -out private.pem 2048
openssl rsa -in private.pem -pubout -out public.pem

​
4. Verify Installation

Once the application is running, verify it’s working: 
curl http://localhost:8081/comialex/api/integra/actuator/health
Expected response: 
{
  "status": "UP"
}

​
Your First API Call

​
Step 1: Authenticate

To access protected endpoints, you need to authenticate and obtain a JWT token. 
curl -X POST http://localhost:8081/comialex/api/integra/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your_username",
    "password": "your_password"
  }'
Response: 
{
  "token": "eyJhbGciOiJSUzI1NiJ9.eyJpZCI6MTIzLCJzdXAiOnRydWUsImVtcGxlYWRvSWQiOjQ1Niwi...",
  "employeeName": {
    "id": 456,
    "nombre": "Juan",
    "apellidos": "Pérez García",
    "nip": "1234",
    "activo": true
  },
  "uiPermissions": [
    "asistencia.ver",
    "empleados.gestionar",
    "reportes.generar"
  ]
}
The token expires after 30 days (2,592,000 seconds) by default. Store it securely on the client side.

​
Step 2: Make an Authenticated Request

Use the token from the login response to access protected endpoints: 
curl -X GET http://localhost:8081/comialex/api/integra/empleados \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJpZCI6MTIzLCJzdXAiOnRydWUsImVtcGxlYWRvSWQiOjQ1Niwi..."
Response: 
{
  "success": true,
  "data": [
    {
      "id": 1,
      "nombre": "María",
      "apellidos": "González López",
      "nip": "5678",
      "activo": true,
      "puesto": "Desarrolladora Senior",
      "departamento": "Tecnología"
    },
    {
      "id": 2,
      "nombre": "Carlos",
      "apellidos": "Martínez Sánchez",
      "nip": "9012",
      "activo": true,
      "puesto": "Gerente de Operaciones",
      "departamento": "Operaciones"
    }
  ],
  "message": "Empleado"
}

​
Step 3: Record Attendance

Register an employee check-in: 
curl -X POST http://localhost:8081/comialex/api/integra/asistencia/iniciar \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "empleadoId": 456,
    "unidadId": 1,
    "unidadAsignadaId": 1,
    "hora": "2026-03-05T08:00:00",
    "foto": null
  }'
Response: 
{
  "success": true,
  "data": null,
  "message": "Jornada iniciada"
}

​
Explore the API

​
Interactive API Documentation

Integra includes Swagger UI for interactive API exploration: 
http://localhost:8081/comialex/api/integra/swagger-ui.html
Here you can:
  • Browse all available endpoints
  • Test API calls directly from your browser
  • View request/response schemas
  • Understand validation requirements

​
Common Endpoints

POST /auth/login
POST /auth/forgot-password
POST /auth/reset-password

​
Next Steps

Authentication

Learn about JWT authentication, token management, and security best practices

API Reference

Explore detailed API endpoint documentation

Employee Management

Manage employee records and organizational structure

Attendance Tracking

Record and manage employee work hours

​
Troubleshooting

Verify that:
  • MariaDB is running: systemctl status mariadb
  • Database credentials in application.yml are correct
  • Database integra and schema comialex exist
  • Network firewall allows connections on port 3306
  • Ensure you’re including the Authorization: Bearer <token> header
  • Check that your token hasn’t expired (30-day default expiration)
  • Verify the token was obtained from a successful /auth/login call
  • Check that the JWT keys (private.pem and public.pem) are correctly configured
Change the server port in application.yml:
server:
  port: 8082
Or specify it when running:
mvn spring-boot:run -Dserver.port=8082
Integra needs CORS configuration for cross-origin requests. Contact your system administrator to configure allowed origins in the security settings.

​
Production Deployment

Before deploying to production:
  • Change all default passwords and credentials
  • Use environment variables for sensitive configuration
  • Enable HTTPS/TLS for all API communication
  • Configure proper database connection pooling
  • Set up monitoring with Actuator and Prometheus
  • Review and adjust token expiration times
  • Implement proper backup and disaster recovery procedures
For production deployment, use the application-prod.yml profile: 
mvn clean package
java -jar target/integra-0.0.1-SNAPSHOT.jar --spring.profiles.active=prod

Build docs developers (and LLMs) love

Get started for freeTalk to us