Documentation API – Régulation de Puissance sur Centrale

Introduction

Cette fonctionnalité est basée sur l'API commande ALEMCA (doc de l’API commande ALEMCA).
Elle permet de déclencher une régulation de puissance sur une centrale via la tâche préconfigurée regulation_centrale (identifiant de la commande : 6cdc1f68-5f44-4ec7-91ad-952d58df6023).

Informations de base

L'ensemble des appels pour utiliser cette fonctionnalité sont à faire sur l’endpoint suivant :
URL complète : https://api.alemca.io/v3/commands/tasks/6cdc1f68-5f44-4ec7-91ad-952d58df6023

Vue d'ensemble du processus

Authentification
Variables
Créer une commande de régulation unitaire
Créer une commande de régulation groupée
Lire le statut d’une commande de régulation
Voir l’historique des commandes
Annuler une régulation
Commande de test

1. Authentification

On s’authentifie par API-key. Un utilisateur dédié doit être créé.
Il appartient à l’utilisateur de définir une durée de validité de l’API-key cohérente avec son utilisation.
doc api-keys

En-têtes à ajouter dans toutes les requêtes http

{
  "api-key": "<API_KEY>"
}

2. Variables

Champ	Description	Type	Détails
`entity_ident`	ID unique de l'équipement	`<UUID\\|String>`	identifiants d'équipements
`end_timestamp`	Timestamp Unix de fin de régulation	`Integer`	Unix timestamp (secondes).
`regulation_mode`	Mode de régulation	`String`	default: `cycle` `on`: force ON `off`: force OFF `cycle`: OFF, repasse en ON après le `end_timestamp`.
`regulation_type`	Type de régulation	`String`	default: `none` `percent`: % `power`: en kW `none`: utilise les valeurs de la configuration
`regulation_value`	Valeur de régulation	`Integer`	à ajouter uniquement si `regulation_type` est différent de "none" default: `0` Si `percent`: 0–100 (%) Si `power`: puissance en W (≥ 0).
`target`	Cible de la régulation	`String`	default: `all` `all`: tous les connectors Modbus `<connector>`: Connecteur Modbus spécifique
`comment`	Commentaire visible pour le job	`String`	—
`group_name`	Nom du groupe pour les jobs groupés	`String`	—
`ident_list`	Liste d'équipements ciblés	`Array<UUID\\|String>`	Liste d'identifiants d'équipements.
`tag`	Tag d'équipements pour exécution groupée	`String`	—
`scheduled_time`	Timestamp Unix de début de régulation	`Integer`	Unix timestamp (secondes).
---------------------------------------------------------------------------

3. Créer une commande de régulation unitaire

entity_ident : identifiant de l’entité ALEMCA que l’on souhaite réguler
scheduled_time : début de la régulation, Timestamp Unix (en son absence, la régulation commence immédiatement)
end_timestamp : fin de la régulation, Timestamp Unix (en son absence la durée est infinie)
regulation_mode : Mode de régulation (on, off, cycle) default: cycle
regulation_type : Type de régulation (percent, power, none) default: none
regulation_value : Valeur de régulation (pour percent, c'est un pourcentage; pour power, c'est une puissance) default: 0
target : Cible de la régulation (all, or a specific target) default: all
comment : champ libre pour assurer la traçabilité d’une commande (facultatif)

Endpoint

POST https://api.alemca.io/v3/commands/tasks/6cdc1f68-5f44-4ec7-91ad-952d58df6023/jobs

Corps de requête

{
  "entity_ident": "<ENTITY_IDENT>",
  "variables": {
    "end_timestamp": 1742200955,
    "regulation_mode": "cycle",
    "regulation_type": "none",
    "regulation_value": 0,
    "target": "all"
  },
  "comment": "Régulation temporaire de la centrale",
  "scheduled_time": 1742200455
}

Réponse attendue

{
  "ident": "<JOB_IDENT>",
  "status": "pending",
  "response": "command sent"
}

Le <JOB_IDENT> sert à suivre le statut de la commande sur l'entité associée.

4. Créer une commande groupée

Si vous utilisez jobs/list ou jobs/tags avec un champ group_name, un groupe logique est automatiquement créé.

4.1 En fournissant une liste d’entity_ident

group_name : nom logique pour l’envoi groupé (ex : "regulation_batch_1")
ident_list : liste des identifiants des entités ALEMCA à réguler
scheduled_time : début de la régulation, Timestamp Unix (en son absence, la régulation commence immédiatement)
end_timestamp : fin de la régulation, Timestamp Unix (en son absence la durée est infinie)
regulation_mode : mode de régulation (on, off, cycle) default: cycle
regulation_type : Type de régulation (percent, power, none) default: none
regulation_value : Valeur de régulation (pour percent, c'est un pourcentage; pour power, c'est une puissance) default: 0
target : Cible de la régulation (all, or a specific target) default: all
comment : champ libre (facultatif)

Endpoint

POST https://api.alemca.io/v3/commands/tasks/6cdc1f68-5f44-4ec7-91ad-952d58df6023/jobs/list

Corps de requête

{
  "variables": {
    "end_timestamp": 1742200955,
    "regulation_mode": "cycle",
    "regulation_type": "none",
    "regulation_value": 0,
    "target": "all"
  },
  "comment": "Régulation pour plusieurs centrales",
  "group_name": "regulation_batch_1",
  "ident_list": [
    "<ENTITY_IDENT>",
    "<ENTITY_IDENT>"
  ],
  "scheduled_time": 1742200455
}

Réponse attendue

[
  {
    "ident": "<JOB_IDENT>",
    "status": "pending",
    "response": "command sent",
    "group": {
      "ident": "<GROUP_IDENT>",
      "name": "regulation_batch_1"
    }
  }
]

Le <JOB_IDENT> permet de suivre l’état de la commande pour chaque entité.
Le <GROUP_IDENT> permet de suivre l’état global de l’ensemble des commandes du groupe.

4.2 En ciblant un tag

tag : tag d’équipements ALEMCA à réguler
ident_list : liste des identifiants des entités ALEMCA à réguler
scheduled_time : début de la régulation, Timestamp Unix (en son absence, la régulation commence immédiatement)
end_timestamp : fin de la régulation, Timestamp Unix (en son absence la durée est infinie)
regulation_mode : mode de régulation (on, off, cycle) default: cycle
regulation_type : Type de régulation (percent, power, none) default: none
regulation_value : Valeur de régulation (pour percent, c'est un pourcentage; pour power, c'est une puissance) default: 0
target : Cible de la régulation (all, or a specific target) default: all
comment : champ libre (facultatif)

Endpoint

POST https://api.alemca.io/v3/commands/tasks/6cdc1f68-5f44-4ec7-91ad-952d58df6023/jobs/tags

Corps de requête

{
  "variables": {
    "end_timestamp": 1742200955,
    "regulation_mode": "cycle",
    "regulation_type": "none",
    "regulation_value": 0,
    "target": "all"
  },
  "comment": "Régulation pour plusieurs centrales",
  "group_name": "regulation_batch_1",
  "tag": "centrales_ext",
  "scheduled_time": 1742200455
}

Réponse attendue

[
  {
    "ident": "<JOB_IDENT>",
    "status": "pending",
    "response": "command sent",
    "group": {
      "ident": "<GROUP_IDENT>",
      "name": "regulation_batch_1"
    }
  }
]

Le <JOB_IDENT> permet de suivre l’état de la commande pour chaque entité.
Le <GROUP_IDENT> permet de suivre l’état global de l’ensemble des commandes du groupe.

5. Lire le statut d’une commande de régulation

5.1 Statut d'une commande unitaire

Le est celui récupéré dans les réponses des étapes précédentes

Endpoint

GET https://api.alemca.io/v3/commands/jobs/<JOB_IDENT>

Exemple de réponse

{
  "ident": "<JOB_IDENT>",
  "status": "pending",
  "response": "command sent",
  "group": {
    "ident": "<GROUP_IDENT>",
    "name": "regulation_batch_1"
  }
}

5.2 Statut d’un envoi groupé

Le est celui récupéré dans les réponses des étapes précédentes

Endpoint

GET https://api.alemca.io/v3/commands/jobs?group_ident=<GROUP_IDENT>

Exemple de réponse

{
  "page": 1,
  "per_page": 500,
  "total_pages": 1,
  "total_items": 1,
  "items": [
    {
      "ident": "<JOB_IDENT>",
      "status": "pending",
      "response": "command sent",
      "group": {
        "ident": "<GROUP_IDENT>",
        "name": "regulation_batch_1"
      }
    }
  ]
}

6. Voir l’historique d’une commande de régulation

Le est celui récupéré dans les réponses des étapes précédentes pour récupérer l'historique d'une commande groupée, il est nécessaire d'appeler l'historique de chacun des

Endpoint

GET https://api.alemca.io/v3/commands/jobs/<JOB_IDENT>/history

Exemple de réponse

{
  "page": 1,
  "per_page": 500,
  "total_pages": 1,
  "total_items": 2,
  "items": [
    {
      "status": "initial",
      "created_at": 1742200955,
      "response": ""
    },
    {
      "status": "transmited",
      "created_at": 1742200955,
      "response": ""
    }
  ]
}

7. Annuler une régulation

Si une régulation de centrale est encore en attente ou planifiée, vous pouvez l’annuler à tout moment via :

Requête

PATCH https://api.alemca.io/v3/commands/jobs/<JOB_IDENT>/cancel

Réponse attendue

{
  "status": "cancelled",
  "ident": "<JOB_IDENT>"
}

Une fois le job commencé, l’annulation n’est plus garantie une fois le job commencé.

8. Commande de test

Commande qui permet de tester la trame de communication entre le server ALEMCA et la centrale à réguler

⚠️ Warning :

Cette action n'est disponible que pour les agent ALEMCA en version supérieure à 2.4.12
Si cette commande est exécutée avec une version antérieure à 2.4.12 la commande ne sera pas un test mais une vraie régulation

Endpoint

POST https://api.alemca.io/v3/commands/tasks/6cdc1f68-5f44-4ec7-91ad-952d58df6023/jobs/test

Corps de requête

{
  "entity_ident": "<ENTITY_IDENT>",
  "variables": {},
  "comment": "Commande de test"
}

Réponse attendue

{
  "global": true
  "server": {
    "global": true,
    "info": {},
    "errors": {}
  },
  "edge": {
    "global": true,
    "info": {},
    "errors": {}
  }
}

server infra/config coté ALEMCA

edge agent/config/modbus coté centrale

global permet de savoir si le test c'est bien passé, une valeur à true montre que tout est ok, false montre qu'il y a une erreur et que la commande ne passera pas

info permet d'avoir des infos sur les tests effectués si besoin

errors permet de voir si il y à des problèmes

Pour aller plus loin

Consultez la documentation Swagger pour explorer l’API command dans son ensemble.
Pour toute information supplémentaire, contactez le support à l’adresse suivante : support@alemca.com