API
API REST
Collegare i tuoi software a cDESP con la chiave X-API-KEY: siti, esportazione ZIP, modelli e documenti normativi.
4 min di lettura
L'API REST di cDESP permette ai tuoi software (ERP, CMMS, script) di leggere e creare i tuoi siti, di esportare la cartella di un sito in ZIP e, in base al tuo abbonamento, di leggere i modelli e i documenti normativi. Risponde in JSON.
Ottenere la chiave
- Nel menu a sinistra, clicca su Impostazioni.
- Scorri fino alla scheda Token API.
- Clicca su Nuovo token.
- Clicca sull'icona Copia il token per copiarlo. L'icona a forma di occhio lo mostra in chiaro.
Vedi anche Impostazioni.
Chiamare l'API
- Indirizzo di base:
https://api.dcrr.fr/v1 - Invia la chiave nell'intestazione
X-API-KEYdi ogni richiesta. - Per un invio di dati (
POST), invia JSON con l'intestazioneContent-Type: application/json. - Vedi i siti che condividono almeno un gruppo con il tuo account. Vedi Team e gruppi.
- Limite: 500 richieste al minuto per indirizzo IP.
- Riferimento interattivo (Swagger): https://api.dcrr.fr/swagger/index.html
Prima prova:
curl https://api.dcrr.fr/v1/sites \
-H "X-API-KEY: LA_TUA_CHIAVE_API"
Elenco delle rotte
| Metodo | Percorso | Funzione | Accesso |
|---|---|---|---|
GET | /v1/sites | Elencare i tuoi siti | qualsiasi chiave valida |
GET | /v1/sites/{id} | Leggere un sito | qualsiasi chiave valida |
GET | /v1/sites/{id}/export/zip | Scaricare la cartella del sito in ZIP | qualsiasi chiave valida |
POST | /v1/sites | Creare un sito | secondo l'abbonamento |
DELETE | /v1/sites/{id} | Eliminare un sito | secondo l'abbonamento |
GET | /v1/models | Elencare i modelli | secondo l'abbonamento |
GET | /v1/models/{id} | Leggere un modello | secondo l'abbonamento |
GET | /v1/reglementary-documents | Elencare i documenti normativi | secondo l'abbonamento |
GET | /v1/reglementary-documents/{id} | Leggere un documento normativo | secondo l'abbonamento |
{id} è l'identificativo dell'oggetto, restituito nel campo id.
Siti
Elencare e leggere
GET /v1/sites restituisce tutti i tuoi siti. GET /v1/sites/{id} restituisce un solo sito.
curl https://api.dcrr.fr/v1/sites/507f1f77bcf86cd799439011 \
-H "X-API-KEY: LA_TUA_CHIAVE_API"
{
"id": "507f1f77bcf86cd799439011",
"name": "Entrepôt Nord",
"code": "000042",
"address": "12 avenue des Lilas, 75000 Paris",
"group": ["Mon entreprise"],
"files": [],
"order_index": 42,
"completed": false
}
Campi principali: name (nome), code (codice del sito, assegnato da cDESP), address, group (gruppi che vedono il sito), files (link dei file collegati al sito) e completed (true quando il sito è segnato come conforme in cDESP).
Creare un sito
POST /v1/sites crea un sito. Corpo JSON:
name(obbligatorio): nome del sito.address(obbligatorio): indirizzo.group(facoltativo): elenco di gruppi. Senza questo campo, il sito è collegato a tutti i tuoi gruppi. Puoi scegliere solo gruppi di cui fai parte.
curl -X POST https://api.dcrr.fr/v1/sites \
-H "X-API-KEY: LA_TUA_CHIAVE_API" \
-H "Content-Type: application/json" \
-d '{"name": "Entrepôt Nord", "address": "12 avenue des Lilas, 75000 Paris"}'
Risposta 201:
{ "message": "Site created successfully", "id": "507f1f77bcf86cd799439011" }
Il codice del sito viene assegnato automaticamente. Alcuni abbonamenti limitano il numero di siti: oltre il limite, la risposta è 403. La Licence Suivi non permette di creare siti.
Eliminare un sito
DELETE /v1/sites/{id} elimina il sito con i suoi impianti e i relativi componenti. L'operazione è definitiva.
curl -X DELETE https://api.dcrr.fr/v1/sites/507f1f77bcf86cd799439011 \
-H "X-API-KEY: LA_TUA_CHIAVE_API"
Esportare la cartella in ZIP
GET /v1/sites/{id}/export/zip restituisce un file ZIP: documenti del sito, verbali dei controlli (piano di ispezione, VI, IP, audit) con la loro versione firmata e foto degli impianti.
curl https://api.dcrr.fr/v1/sites/507f1f77bcf86cd799439011/export/zip \
-H "X-API-KEY: LA_TUA_CHIAVE_API" \
-o site.zip
L'elenco delle ESP soggette (elenco 6-III) non viene prodotto dall'API: al suo posto lo ZIP contiene un file vuoto che lo segnala. Genera questo elenco da cDESP. Vedi Cartella del sito.
Modelli
GET /v1/models restituisce il catalogo dei modelli di apparecchiature. GET /v1/models/{id} restituisce un modello.
curl https://api.dcrr.fr/v1/models \
-H "X-API-KEY: LA_TUA_CHIAVE_API"
Ogni modello contiene id, designation (designazione), files (file associati) e doc_files (documentazione).
Documenti normativi
GET /v1/reglementary-documents restituisce l'elenco dei documenti normativi. GET /v1/reglementary-documents/{id} restituisce un documento.
curl https://api.dcrr.fr/v1/reglementary-documents \
-H "X-API-KEY: LA_TUA_CHIAVE_API"
Ogni documento contiene id, name (nome), file (link del file), created_at e updated_at.
Errori
| Codice | Caso | Esempio di risposta |
|---|---|---|
400 | Corpo della richiesta non valido, nome o indirizzo mancante | {"error": "Le nom et l'adresse sont obligatoires"} |
401 | Chiave assente o sconosciuta | {"message": "Invalid or missing API Key"} |
401 | Il tuo abbonamento non consente questa rotta | {"message": "You are not allowed to do this request"} |
403 | Sito non condiviso con i tuoi gruppi, o limite dell'abbonamento raggiunto | {"error": "You don't have access to this site"} |
429 | Più di 500 richieste in un minuto | {"message": "Too many requests, please slow down"} |
500 | Errore del server, o sito non trovato durante una lettura | {"error": "Failed to retrieve site: ..."} |
I messaggi di errore sono in inglese o in francese. Controlla il codice HTTP invece del testo.