API
API REST
Ligar os seus programas ao cDESP com a chave X-API-KEY: locais, exportação ZIP, modelos e documentos regulamentares.
4 min de leitura
A API REST do cDESP permite que os seus programas (ERP, GMAO, scripts) leiam e criem os seus locais, exportem a pasta de um local em ZIP e, conforme a sua assinatura, leiam os modelos e os documentos regulamentares. Responde em JSON.
Obter a sua chave
- No menu à esquerda, clique em Configurações.
- Desça até ao cartão Token API.
- Clique em Novo token.
- Clique no ícone Copiar token para o copiar. O ícone em forma de olho mostra-o em claro.
Ver também Definições.
Chamar a API
- Endereço de base:
https://api.dcrr.fr/v1 - Envie a chave no cabeçalho
X-API-KEYde cada pedido. - Para um envio de dados (
POST), envie JSON com o cabeçalhoContent-Type: application/json. - Vê os locais que partilham pelo menos um grupo com a sua conta. Ver Equipa e grupos.
- Limite: 500 pedidos por minuto e por endereço IP.
- Referência interativa (Swagger): https://api.dcrr.fr/swagger/index.html
Primeiro teste:
curl https://api.dcrr.fr/v1/sites \
-H "X-API-KEY: A_SUA_CHAVE_API"
Lista das rotas
| Método | Caminho | Função | Acesso |
|---|---|---|---|
GET | /v1/sites | Listar os seus locais | qualquer chave válida |
GET | /v1/sites/{id} | Ler um local | qualquer chave válida |
GET | /v1/sites/{id}/export/zip | Descarregar a pasta do local em ZIP | qualquer chave válida |
POST | /v1/sites | Criar um local | conforme a assinatura |
DELETE | /v1/sites/{id} | Eliminar um local | conforme a assinatura |
GET | /v1/models | Listar os modelos | conforme a assinatura |
GET | /v1/models/{id} | Ler um modelo | conforme a assinatura |
GET | /v1/reglementary-documents | Listar os documentos regulamentares | conforme a assinatura |
GET | /v1/reglementary-documents/{id} | Ler um documento regulamentar | conforme a assinatura |
{id} é o identificador do objeto, devolvido no campo id.
Locais
Listar e ler
GET /v1/sites devolve todos os seus locais. GET /v1/sites/{id} devolve um único local.
curl https://api.dcrr.fr/v1/sites/507f1f77bcf86cd799439011 \
-H "X-API-KEY: A_SUA_CHAVE_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
}
Campos principais: name (nome), code (código do local, atribuído pelo cDESP), address, group (grupos que veem o local), files (ligações dos ficheiros associados ao local) e completed (true quando o local está marcado como conforme no cDESP).
Criar um local
POST /v1/sites cria um local. Corpo JSON:
name(obrigatório): nome do local.address(obrigatório): morada.group(opcional): lista de grupos. Sem este campo, o local fica associado a todos os seus grupos. Só pode escolher grupos dos quais faz parte.
curl -X POST https://api.dcrr.fr/v1/sites \
-H "X-API-KEY: A_SUA_CHAVE_API" \
-H "Content-Type: application/json" \
-d '{"name": "Entrepôt Nord", "address": "12 avenue des Lilas, 75000 Paris"}'
Resposta 201:
{ "message": "Site created successfully", "id": "507f1f77bcf86cd799439011" }
O código do local é atribuído automaticamente. Algumas assinaturas limitam o número de locais: acima do limite, a resposta é 403. A Licence Suivi não permite criar locais.
Eliminar um local
DELETE /v1/sites/{id} elimina o local com os seus sistemas e respetivos componentes. Esta ação é definitiva.
curl -X DELETE https://api.dcrr.fr/v1/sites/507f1f77bcf86cd799439011 \
-H "X-API-KEY: A_SUA_CHAVE_API"
Exportar a pasta em ZIP
GET /v1/sites/{id}/export/zip devolve um ficheiro ZIP: documentos do local, relatórios de controlos (plano de inspeção, VI, IP, auditoria) com a respetiva versão assinada e fotografias dos sistemas.
curl https://api.dcrr.fr/v1/sites/507f1f77bcf86cd799439011/export/zip \
-H "X-API-KEY: A_SUA_CHAVE_API" \
-o site.zip
A lista dos ESP abrangidos (lista 6-III) não é produzida pela API: no seu lugar, o ZIP contém um ficheiro vazio que o assinala. Gere esta lista a partir do cDESP. Ver Pasta do local.
Modelos
GET /v1/models devolve o catálogo de modelos de equipamentos. GET /v1/models/{id} devolve um modelo.
curl https://api.dcrr.fr/v1/models \
-H "X-API-KEY: A_SUA_CHAVE_API"
Cada modelo contém id, designation (designação), files (ficheiros associados) e doc_files (documentação).
Documentos regulamentares
GET /v1/reglementary-documents devolve a lista dos documentos regulamentares. GET /v1/reglementary-documents/{id} devolve um documento.
curl https://api.dcrr.fr/v1/reglementary-documents \
-H "X-API-KEY: A_SUA_CHAVE_API"
Cada documento contém id, name (nome), file (ligação do ficheiro), created_at e updated_at.
Erros
| Código | Caso | Exemplo de resposta |
|---|---|---|
400 | Corpo do pedido inválido, nome ou morada em falta | {"error": "Le nom et l'adresse sont obligatoires"} |
401 | Chave ausente ou desconhecida | {"message": "Invalid or missing API Key"} |
401 | A sua assinatura não permite esta rota | {"message": "You are not allowed to do this request"} |
403 | Local não partilhado com os seus grupos, ou limite da assinatura atingido | {"error": "You don't have access to this site"} |
429 | Mais de 500 pedidos num minuto | {"message": "Too many requests, please slow down"} |
500 | Erro do servidor, ou local não encontrado durante uma leitura | {"error": "Failed to retrieve site: ..."} |
As mensagens de erro estão em inglês ou em francês. Verifique o código HTTP em vez do texto.