API
API REST
Connecter vos logiciels à cDESP avec la clé X-API-KEY : sites, export ZIP, modèles et documents réglementaires.
4 min de lecture
L'API REST de cDESP permet à vos logiciels (ERP, GMAO, scripts) de lire et de créer vos sites, d'exporter le dossier d'un site en ZIP et, selon votre abonnement, de lire les modèles et les documents réglementaires. Elle répond en JSON.
Obtenir votre clé
- Dans le menu de gauche, cliquez sur Paramètres.
- Descendez jusqu'à la carte Token API.
- Cliquez sur Nouveau token.
- Cliquez sur l'icône Copier le token pour le copier. L'icône en forme d'œil l'affiche en clair.
Voir aussi Paramètres.
Appeler l'API
- Adresse de base :
https://api.dcrr.fr/v1 - Envoyez la clé dans l'en-tête
X-API-KEYde chaque requête. - Pour un envoi de données (
POST), envoyez du JSON avec l'en-têteContent-Type: application/json. - Vous voyez les sites qui partagent au moins un groupe avec votre compte. Voir Équipe et groupes.
- Limite : 500 requêtes par minute et par adresse IP.
- Référence interactive (Swagger) : https://api.dcrr.fr/swagger/index.html
Premier essai :
curl https://api.dcrr.fr/v1/sites \
-H "X-API-KEY: VOTRE_CLE_API"
Liste des routes
| Méthode | Chemin | Rôle | Accès |
|---|---|---|---|
GET | /v1/sites | Lister vos sites | toute clé valide |
GET | /v1/sites/{id} | Lire un site | toute clé valide |
GET | /v1/sites/{id}/export/zip | Télécharger le dossier du site en ZIP | toute clé valide |
POST | /v1/sites | Créer un site | selon l'abonnement |
DELETE | /v1/sites/{id} | Supprimer un site | selon l'abonnement |
GET | /v1/models | Lister les modèles | selon l'abonnement |
GET | /v1/models/{id} | Lire un modèle | selon l'abonnement |
GET | /v1/reglementary-documents | Lister les documents réglementaires | selon l'abonnement |
GET | /v1/reglementary-documents/{id} | Lire un document réglementaire | selon l'abonnement |
{id} est l'identifiant de l'objet, renvoyé dans le champ id.
Sites
Lister et lire
GET /v1/sites renvoie tous vos sites. GET /v1/sites/{id} renvoie un seul site.
curl https://api.dcrr.fr/v1/sites/507f1f77bcf86cd799439011 \
-H "X-API-KEY: VOTRE_CLE_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
}
Champs principaux : name (nom), code (code du site, donné par cDESP), address, group (groupes qui voient le site), files (liens des fichiers rattachés au site) et completed (true quand le site est marqué conforme dans cDESP).
Créer un site
POST /v1/sites crée un site. Corps JSON :
name(obligatoire) : nom du site.address(obligatoire) : adresse.group(facultatif) : liste de groupes. Sans ce champ, le site est rattaché à tous vos groupes. Vous ne pouvez choisir que des groupes dont vous faites partie.
curl -X POST https://api.dcrr.fr/v1/sites \
-H "X-API-KEY: VOTRE_CLE_API" \
-H "Content-Type: application/json" \
-d '{"name": "Entrepôt Nord", "address": "12 avenue des Lilas, 75000 Paris"}'
Réponse 201 :
{ "message": "Site created successfully", "id": "507f1f77bcf86cd799439011" }
Le code du site est attribué automatiquement. Certains abonnements limitent le nombre de sites : au-delà, la réponse est 403. La Licence Suivi ne permet pas de créer de site.
Supprimer un site
DELETE /v1/sites/{id} supprime le site avec ses systèmes et leurs composants. Cette action est définitive.
curl -X DELETE https://api.dcrr.fr/v1/sites/507f1f77bcf86cd799439011 \
-H "X-API-KEY: VOTRE_CLE_API"
Exporter le dossier en ZIP
GET /v1/sites/{id}/export/zip renvoie un fichier ZIP : documents du site, comptes rendus de contrôles (plan d'inspection, VI, IP, audit) avec leur version signée, et photos des systèmes.
curl https://api.dcrr.fr/v1/sites/507f1f77bcf86cd799439011/export/zip \
-H "X-API-KEY: VOTRE_CLE_API" \
-o site.zip
La liste des ESP soumis (liste 6-III) n'est pas produite par l'API : le ZIP contient à sa place un fichier vide qui le signale. Générez cette liste depuis cDESP. Voir Dossier du site.
Modèles
GET /v1/models renvoie le catalogue des modèles d'équipements. GET /v1/models/{id} renvoie un modèle.
curl https://api.dcrr.fr/v1/models \
-H "X-API-KEY: VOTRE_CLE_API"
Chaque modèle contient id, designation (désignation), files (fichiers associés) et doc_files (documentation).
Documents réglementaires
GET /v1/reglementary-documents renvoie la liste des documents réglementaires. GET /v1/reglementary-documents/{id} renvoie un document.
curl https://api.dcrr.fr/v1/reglementary-documents \
-H "X-API-KEY: VOTRE_CLE_API"
Chaque document contient id, name (nom), file (lien du fichier), created_at et updated_at.
Erreurs
| Code | Cas | Exemple de réponse |
|---|---|---|
400 | Corps de requête invalide, nom ou adresse manquant | {"error": "Le nom et l'adresse sont obligatoires"} |
401 | Clé absente ou inconnue | {"message": "Invalid or missing API Key"} |
401 | Votre abonnement ne permet pas cette route | {"message": "You are not allowed to do this request"} |
403 | Site non partagé avec vos groupes, ou limite de l'abonnement atteinte | {"error": "You don't have access to this site"} |
429 | Plus de 500 requêtes en une minute | {"message": "Too many requests, please slow down"} |
500 | Erreur du serveur, ou site introuvable lors d'une lecture | {"error": "Failed to retrieve site: ..."} |
Les messages d'erreur sont en anglais ou en français. Testez le code HTTP plutôt que le texte.