API Pública v1

PMST.si — Documentación de la REST API para integraciones externas.

Autenticación
La API soporta dos métodos de autenticación:
1. JWT Bearer Token: Authorization: Bearer <token>
2. API Key: X-API-Key: <api_key>

Rate Limiting
200 peticiones por hora por IP. Al superar el límite se devuelve HTTP 429.
Headers de respuesta: X-RateLimit-Limit, X-RateLimit-Remaining.

URL Base

https://pmst.si/api/v1

Autenticación

Autenticar usuario y obtener token JWT + refresh token.

Cuerpo de la petición

Campo	Tipo	Requerido	Descripción
`email`	string	required	Email del usuario
`password`	string	required	Contraseña del usuario

Ejemplo Request

curl -X POST https://pmst.si/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "usuario@empresa.com", "password": "mi_password"}'

Ejemplo Response (200)

{
    "success": true,
    "data": {
        "token": "eyJhbGciOiJIUzI1NiIs...",
        "refresh": "eyJhbGciOiJIUzI1NiIs...",
        "token_type": "Bearer",
        "expires_in": 3600,
        "user": {
            "id": 42,
            "email": "usuario@empresa.com",
            "nombre": "Juan García",
            "rol": "empresa"
        }
    },
    "timestamp": 1719398400
}

POST /auth/refresh

Refrescar token JWT usando el refresh token.

Campo	Tipo	Requerido	Descripción
`refresh_token`	string	required	Token de refresco obtenido en login

Ejemplo Request

curl -X POST https://pmst.si/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "eyJhbGciOiJIUzI1NiIs..."}'

Ejemplo Response (200)

{
    "success": true,
    "data": {
        "token": "eyJhbGciOiJIUzI1NiIs...",
        "refresh": "eyJhbGciOiJIUzI1NiIs...",
        "token_type": "Bearer",
        "expires_in": 3600
    },
    "timestamp": 1719398400
}

Nota: El access token expira en 1 hora. El refresh token expira en 7 días. Usa el endpoint POST /auth/refresh antes de que expire el access token.

Empresas

GET /empresas

Listar las empresas asociadas al usuario autenticado.

Parámetros de query

Parámetro	Tipo	Requerido	Descripción
`page`	int	optional	Página (default: 1)
`limit`	int	optional	Resultados por página (default: 25, max: 100)

Ejemplo Request

curl -X GET "https://pmst.si/api/v1/empresas?page=1&limit=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Ejemplo Response (200)

{
    "success": true,
    "data": {
        "empresas": [
            {
                "iId": 8,
                "sName": "EMPRESA EJEMPLO SL",
                "sCIF": "B12345678",
                "sSector": "Servicios",
                "iNumTrabajadores": 15,
                "dtCreatedAt": "2024-01-15 10:00:00"
            }
        ],
        "pagination": {
            "total": 1,
            "page": 1,
            "limit": 10,
            "pages": 1
        }
    },
    "timestamp": 1719398400
}

GET /empresas/{id}

Obtener detalle completo de una empresa.

Parámetros de ruta

Parámetro	Tipo	Requerido	Descripción
`id`	int	required	ID de la empresa

Ejemplo Request

curl -X GET "https://pmst.si/api/v1/empresas/8" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Ejemplo Response (200)

{
    "success": true,
    "data": {
        "empresa": {
            "iId": 8,
            "sName": "EMPRESA EJEMPLO SL",
            "sCIF": "B12345678",
            "sSector": "Servicios",
            "iNumTrabajadores": 15,
            "dtCreatedAt": "2024-01-15 10:00:00",
            "sAddress": "Calle Mayor 1",
            "sPostalCode": "28001",
            "sCity": "Madrid",
            "sProvince": "Madrid"
        }
    },
    "timestamp": 1719398400
}

Errores comunes: 404 Empresa no encontrada, 403 Acceso denegado.

Trabajadores

GET /trabajadores?empresa={id}

Listar trabajadores de una empresa concreta.

Parámetros de query

Parámetro	Tipo	Requerido	Descripción
`empresa`	int	required	ID de la empresa
`page`	int	optional	Página (default: 1)
`limit`	int	optional	Resultados por página (default: 25, max: 100)

Ejemplo Request

curl -X GET "https://pmst.si/api/v1/trabajadores?empresa=8&page=1&limit=25" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Ejemplo Response (200)

{
    "success": true,
    "data": {
        "trabajadores": [
            {
                "iId": 101,
                "sName": "María",
                "sLastName": "López García",
                "sEmail": "mlopez@empresa.com",
                "sPhone": "684762300",
                "sDepartment": "Recursos Humanos",
                "sPuesto": "Técnica de prevención",
                "bActive": 1,
                "dtCreatedAt": "2024-03-01 09:00:00"
            }
        ],
        "pagination": {
            "total": 15,
            "page": 1,
            "limit": 25,
            "pages": 1
        }
    },
    "timestamp": 1719398400
}

Estadísticas

GET /estadisticas/dashboard?empresa={id}

Obtener estadísticas del dashboard para una empresa.

Parámetro	Tipo	Requerido	Descripción
`empresa`	int	required	ID de la empresa

Ejemplo Request

curl -X GET "https://pmst.si/api/v1/estadisticas/dashboard?empresa=8" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Ejemplo Response (200)

{
    "success": true,
    "data": {
        "trabajadores": 15,
        "formularios_completados": 42,
        "formularios_pendientes": 8,
        "co2_estimado_toneladas": 12.5,
        "clc_asociadas": 3,
        "fecha_actualizacion": "2025-06-26 12:00:00"
    },
    "timestamp": 1719398400
}

Formularios

POST /formularios/responder

Enviar respuestas de un formulario.

Campo	Tipo	Requerido	Descripción
`iIdFormulario`	int	required	ID del formulario
`respuestas`	array	required	Array de objetos con iIdPregunta y sRespuesta

Ejemplo Request

curl -X POST "https://pmst.si/api/v1/formularios/responder" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "iIdForm": 5,
    "respuestas": [
        {"iIdPregunta": 1, "sRespuesta": "Coche compartido"},
        {"iIdPregunta": 2, "sRespuesta": "Transporte público"},
        {"iIdPregunta": 3, "sRespuesta": "3-5 días a la semana"}
    ]
}'

Ejemplo Response (200)

{
    "success": true,
    "data": {
        "iIdAnswer": 128,
        "sStatus": "completado",
        "dtDate": "2025-06-26 12:00:00"
    },
    "timestamp": 1719398400
}

Notificaciones

GET /notificaciones

Listar notificaciones del usuario autenticado.

Parámetro	Tipo	Requerido	Descripción
`page`	int	optional	Página (default: 1)
`limit`	int	optional	Resultados por página (default: 25, max: 100)

Ejemplo Request

curl -X GET "https://pmst.si/api/v1/notificaciones?limit=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Ejemplo Response (200)

{
    "success": true,
    "data": {
        "notificaciones": [
            {
                "iId": 15,
                "sTitle": "Nuevo formulario asignado",
                "sMessage": "Se ha asignado el formulario de diagnóstico de movilidad.",
                "sType": "info",
                "bRead": 0,
                "dtSent": "2025-06-26 10:30:00"
            }
        ],
        "no_leidas": 3,
        "pagination": {
            "total": 12,
            "page": 1,
            "limit": 10,
            "pages": 2
        }
    },
    "timestamp": 1719398400
}

POST /notificaciones/mark-read

Marcar notificación(es) como leída(s).

Campo	Tipo	Requerido	Descripción
`id`	int	one of	ID de la notificación a marcar
`all`	bool	one of	Si es true, marca todas como leídas

Ejemplo Request

curl -X POST "https://pmst.si/api/v1/notificaciones/mark-read" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"all": true}'

Ejemplo Response (200)

{
    "success": true,
    "data": {
        "marked": 3,
        "message": "3 notifications marked as read"
    },
    "timestamp": 1719398400
}

API Keys

Gestionar claves de API para acceso externo persistente sin JWT.

GET /api-keys

Listar API keys del usuario autenticado.

POST /api-keys

Generar nueva API key.

Campo	Tipo	Requerido	Descripción
`nombre`	string	required	Nombre descriptivo de la key
`permisos`	string	optional	Comma-separated: read, write, admin (default: read)
`dias_expira`	int	optional	Días hasta expiración (default: 365, 0 = sin expiración)

DELETE /api-keys/{id}

Revocar (desactivar) una API key.

Ejemplo: Generar API Key

curl -X POST "https://pmst.si/api/v1/api-keys" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"nombre": "Mi Integración", "permisos": "read,write", "dias_expira": 90}'

Ejemplo Response (200)

{
    "success": true,
    "data": {
        "message": "API key generated successfully. Save it now — it won't be shown again.",
        "api_key": {
            "iId": 1,
            "sApiKey": "A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4",
            "sName": "Mi Integración",
            "sPermissions": "read,write",
            "dtCreada": "2025-06-26 12:00:00",
            "dtExpires": "2025-09-24 12:00:00"
        }
    },
    "timestamp": 1719398400
}

Importante: La API key completa solo se muestra una vez al generarse. Guárdala de forma segura. Las keys se envían via header X-API-Key.

Uso de API Key

curl -X GET "https://pmst.si/api/v1/empresas" \
  -H "X-API-Key: A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4"

Respuestas de Error

Código	Significado	Descripción
`400`	Bad Request	Parámetros requeridos faltantes o inválidos
`401`	Unauthorized	Token JWT inválido/expirado o API key inválida
`403`	Forbidden	Usuario sin permisos para el recurso solicitado
`404`	Not Found	Recurso no encontrado
`405`	Method Not Allowed	Método HTTP no soportado para el endpoint
`429`	Too Many Requests	Límite de rate limiting superado
`500`	Internal Error	Error interno del servidor

Estructura de respuesta de error

{
    "success": false,
    "error": "Error message describing what went wrong",
    "timestamp": 1719398400
}

Inicio Rápido

# 1. Autenticarse
curl -X POST https://pmst.si/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@pmst.si", "password": "tu_password"}'

# 2. Usar el token para acceder a endpoints
TOKEN="eyJhbGciOiJIUzI1NiIs..."

curl -X GET https://pmst.si/api/v1/empresas \
  -H "Authorization: Bearer $TOKEN"

# 3. Consultar estadísticas
curl -X GET "https://pmst.si/api/v1/estadisticas/dashboard?empresa=8" \
  -H "Authorization: Bearer $TOKEN"

# 4. Refrescar token cuando expire
curl -X POST https://pmst.si/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "eyJhbGciOiJIUzI1NiIs..."}'

Soporte

Para problemas o dudas con la API, contacta: contacto@pmst.si

API Pública v1

Índice

URL Base

Autenticación

POST /auth/login

Cuerpo de la petición

Ejemplo Request

Ejemplo Response (200)

POST /auth/refresh

Ejemplo Request

Ejemplo Response (200)

Empresas

GET /empresas

Parámetros de query

Ejemplo Request

Ejemplo Response (200)

GET /empresas/{id}

Parámetros de ruta

Ejemplo Request

Ejemplo Response (200)

Trabajadores

GET /trabajadores?empresa={id}

Parámetros de query

Ejemplo Request

Ejemplo Response (200)

Estadísticas

GET /estadisticas/dashboard?empresa={id}

Ejemplo Request

Ejemplo Response (200)

Formularios

POST /formularios/responder

Ejemplo Request

Ejemplo Response (200)

Notificaciones

GET /notificaciones

Ejemplo Request

Ejemplo Response (200)

POST /notificaciones/mark-read

Ejemplo Request

Ejemplo Response (200)

API Keys

Ejemplo: Generar API Key

Ejemplo Response (200)

Uso de API Key

Respuestas de Error

Estructura de respuesta de error

Inicio Rápido

Soporte