Carregant...

🎓 FREEMIUM

API Pública v1

PMST.si — Documentació de la REST API per a integracions externes.

Autenticació
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.

Índex

URL base

https://pmst.si/api/v1

Autenticación

POST /auth/login

Autenticar usuari i obtenir token JWT + token de refresc.

Cos de la petició

CampTipusRequeritDescripció
emailstringrequeritEmail de l'usuari
passwordstringrequeritContrasenya de l'usuari

Exemple Request

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

Exemple 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 fent servir el refresh token.

CampTipusRequeritDescripció
refresh_tokenstringobligatoriToken de refresc obtingut en l'inici de sessió

Exemple Request

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

Exemple 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.

Empreses

GET /empresas

Llistar les empreses associades a l'usuari autenticat.

Paràmetres de query

ParàmetreTipusRequeritDescripció
pageintopcionalPàgina (per defecte: 1)
limitintopcionalResultats per pàgina (per defecte: 25, màx: 100)

Exemple Request

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

Exemple Response (200)

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

GET /empresas/{id}

Obtenir el detall complet d'una empresa.

Paràmetres de ruta

ParàmetreTipusRequeritDescripció
idintrequeritID de l'empresa

Exemple Request

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

Exemple 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 /treballadors?empresa={id}

Llistar treballadors d'una empresa concreta.

Paràmetres de query

ParàmetreTipusRequeritDescripció
empresaintrequeritID de l'empresa
pageintopcionalPàgina (per defecte: 1)
limitintopcionalResultats per pàgina (per defecte: 25, màx: 100)

Exemple Request

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

Exemple 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ístiques

GET /estadístiques/dashboard?empresa={id}

Obtenir estadístiques del dashboard per a una empresa.

ParàmetreTipusRequeritDescripció
empresaintrequeritID de l'empresa

Exemple Request

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

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

Formularis

POST /formularis/respondre

Enviar respostes d'un formulari.

CampTipusRequeritDescripció
iIdFormulariointrequeritID del formulari
respostesarrayrequeritArray d'objectes amb iIdPregunta i sRespuesta

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

Exemple Response (200)

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

Notificacions

GET /notificacions

Llistar notificacions de l'usuari autenticat.

ParàmetreTipusRequeritDescripció
pageintopcionalPàgina (per defecte: 1)
limitintopcionalResultats per pàgina (per defecte: 25, màxim: 100)

Exemple de petició

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

Exemple de resposta (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 /notificacions/mark-read

Marcar notificació(ons) com a llegida(des).

CampTipusRequeritDescripció
idintun deID de la notificació a marcar
allboolun deSi és true, marqui totes com a llegides

Exemple de petició

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

Exemple de resposta (200)

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

Claus API

Gestionar claus d'API per a accés extern persistent sense JWT.

GET /api-keys

Llistar API keys de l'usuari autenticat.

POST /api-keys

Generar nova API key.

CampTipusRequeritDescripció
nomstringrequeritNom descriptiu de la key
permisosstringopcionalSeparat per comes: read, write, admin (per defecte: read)
dies_expiraintopcionalDies fins a l'expiració (per defecte: 365, 0 = sense expiració)
DELETE /api-keys/{id}

Revocar (desactivar) una clau d'API.

Exemple: Generar clau d'API

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

Exemple de 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.

Ús de la clau d'API

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

Respostes d'error

CodiSignificatDescripció
400Petició incorrectaParàmetres requerits absents o invàlids
401No autoritzatToken JWT invàlid/expirat o clau API invàlida
403ProhibitUsuari sense permisos per al recurs sol·licitat
404No trobatRecurs no trobat
405Mètode no permèsMètode HTTP no suportat per a l'endpoint
429Massa sol·licitudsLímit de rate limiting superat
500Error internError intern del servidor

Estructura de resposta d'error

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

Inici Ràpid

# 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..."}'

Suport

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

Assistent PMST.si
Hola, sóc l'assistent virtual de PMST.si. Puc ajudar-lo amb plans de mobilitat, normativa DGT, formularis, informes i ús de la plataforma. En què puc ajudar-lo?