API Pública v1

PMST.si — Documentación da REST API para integracións 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 e obter token JWT + refresh token.

Corpo da petición

Campo	Tipo	Requirido	Descrición
`email`	string	obrigatorio	Email do usuario
`password`	string	requirido	Contrasinal do usuario

Exemplo Request

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

Exemplo 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

Renovar token JWT usando o refresh token.

Campo	Tipo	Requirido	Descrición
`refresh_token`	string	obrigatorio	Token de actualización obtido no inicio de sesión

Exemplo de solicitude

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

Exemplo de resposta (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 as empresas asociadas ao usuario autenticado.

Parámetros de consulta

Parámetro	Tipo	Requirido	Descrición
`page`	int	opcional	Páxina (por defecto: 1)
`limit`	int	opcional	Resultados por páxina (por defecto: 25, máximo: 100)

Exemplo Request

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

Exemplo Response (200)

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

GET /empresas/{id}

Obter detalle completo dunha empresa.

Parámetros de ruta

Parámetro	Tipo	Requirido	Descrición
`id`	int	obrigatorio	ID da empresa

Exemplo Request

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

Exemplo 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 traballadores dunha empresa concreta.

Parámetros de consulta

Parámetro	Tipo	Requirido	Descrición
`empresa`	int	obrigatorio	ID da empresa
`page`	int	opcional	Páxina (default: 1)
`limit`	int	opcional	Resultados por páxina (default: 25, max: 100)

Exemplo Request

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

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

Estatísticas

GET /estadisticas/dashboard?empresa={id}

Obter estatísticas do dashboard para unha empresa.

Parámetro	Tipo	Requirido	Descrición
`empresa`	int	requirido	ID da empresa

Exemplo Request

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

Exemplo de resposta (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 respostas dun formulario.

Campo	Tipo	Requirido	Descrición
`iIdFormulario`	int	obrigatorio	ID do formulario
`respostas`	array	requirido	Array de obxectos con iIdPregunta e sRespuesta

Exemplo 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"}
    ]
}'

Exemplo Response (200)

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

Notificacións

GET /notificaciones

Listar notificacións do usuario autenticado.

Parámetro	Tipo	Requirido	Descrición
`page`	int	opcional	Páxina (default: 1)
`limit`	int	opcional	Resultados por páxina (default: 25, max: 100)

Exemplo Request

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

Exemplo 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(s) como lida(s).

Campo	Tipo	Requirido	Descrición
`id`	int	un de	ID da notificación a marcar
`all`	bool	un de	Se é true, marca todas como lidas

Exemplo Request

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

Exemplo Response (200)

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

Chaves de API

Xestionar claves de API para acceso externo persistente sen JWT.

GET /api-keys

Listar API keys do usuario autenticado.

POST /api-keys

Xerar nova API key.

Campo	Tipo	Requirido	Descrición
`nome`	string	requirido	Nome descritivo da key
`permisos`	string	opcional	Separado por comas: read, write, admin (por defecto: read)
`dias_expira`	int	opcional	Días ata expiración (por defecto: 365, 0 = sen expiración)

DELETE /api-keys/{id}

Revogar (desactivar) unha API key.

Exemplo: Xerar 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}'

Exemplo Resposta (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 da API Key

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

Respostas de erro

Código	Significado	Descrición
`400`	Petición incorrecta	Parámetros requiridos faltantes ou inválidos
`401`	Non autorizado	Token JWT inválido/expirado ou clave API inválida
`403`	Prohibido	Usuario sen permisos para o recurso solicitado
`404`	Non atopado	Recurso non atopado
`405`	Método non permitido	Método HTTP non soportado para o endpoint
`429`	Demasiadas solicitudes	Límite de rate limiting superado
`500`	Erro interno	Erro interno do servidor

Estrutura de resposta de erro

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

Corpo da petición

Exemplo Request

Exemplo Response (200)

POST /auth/refresh

Exemplo de solicitude

Exemplo de resposta (200)

Empresas

GET /empresas

Parámetros de consulta

Exemplo Request

Exemplo Response (200)

GET /empresas/{id}

Parámetros de ruta

Exemplo Request

Exemplo Response (200)

Trabajadores

GET /trabajadores?empresa={id}

Parámetros de consulta

Exemplo Request

Exemplo Response (200)

Estatísticas

GET /estadisticas/dashboard?empresa={id}

Exemplo Request

Exemplo de resposta (200)

Formularios

POST /formularios/responder

Exemplo Request

Exemplo Response (200)

Notificacións

GET /notificaciones

Exemplo Request

Exemplo Response (200)

POST /notificaciones/mark-read

Exemplo Request

Exemplo Response (200)

Chaves de API

Exemplo: Xerar API Key

Exemplo Resposta (200)

Uso da API Key

Respostas de erro

Estrutura de resposta de erro

Inicio Rápido

Soporte