Valida· API REST v1

Documentació de l'API

API REST per a la integració amb sistemes externs (p. ex. torns de control d'accés físic). Permet consultar l'aptitud dels treballadors i reportar esdeveniments d'entrada/sortida (bidireccional).

Base URL

https://www.valida.pro/api/v1

Autenticació

Totes les crides requereixen una clau d'API (es crea a Configuració → API). Envia-la a la capçalera:

Authorization: Bearer vld_xxxxxxxxxxxxxxxxxxxxxxxx
# o bé
x-api-key: vld_xxxxxxxxxxxxxxxxxxxxxxxx

Les claus estan limitades al seu tenant i tenen scopes access:read i access:write.

Endpoints

GET/api/v1/health

Comprova la clau i l'estat del servei.

curl -H "Authorization: Bearer $KEY" https://www.valida.pro/api/v1/health
GET/api/v1/access/check?national_id=12345678A

Consulta l'aptitud d'un treballador per DNI/NIE. Retorna el semàfor, els documents bloquejants i les obres autoritzades.

curl -H "Authorization: Bearer $KEY" \
  "https://www.valida.pro/api/v1/access/check?national_id=12345678A"

{
  "found": true,
  "worker": { "id": "…", "name": "Carles Puig", "national_id": "12345678A",
              "company": "Construccions Vallès SL", "is_active": true },
  "status": "apto",
  "eligible": true,
  "blocking": [],
  "projects": ["Reforma laboratoris Edifici Clúster"],
  "access_note": null
}
POST/api/v1/access/events

El torn reporta una entrada/sortida. Si no s'informa 'decision', la plataforma l'avalua automàticament segons l'aptitud (integració bidireccional).

curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  https://www.valida.pro/api/v1/access/events \
  -d '{ "national_id": "12345678A", "direction": "in", "gate": "Recepció-1" }'

{
  "event_id": "…", "created_at": "2026-07-05T09:12:00Z",
  "direction": "in", "decision": "granted", "reason": null,
  "worker": { "id": "…", "name": "Carles Puig", … }, "status": "apto"
}
GET/api/v1/access/events?limit=50

Llista els darrers esdeveniments d'accés registrats.

GET/api/v1/workers?updated_since=2026-07-01T00:00:00Z

Sincronització de treballadors i el seu estat d'aptitud amb sistemes externs.

Codis de resposta

← Tornar a Valida