Aller au contenu

Documentation API – Régulation de Puissance sur Centrale

Introduction

Cette API permet de déclencher une régulation de puissance sur une centrale via la tâche préconfigurée regulation_centrale.

Elle repose sur le système standard d’exécution de tâche (task) et de commande (job) d’ALEMCA.

Informations de base

BASE_URL="https://api.alemca.io/v3/commands"
TASK_IDENT="6cdc1f68-5f44-4ec7-91ad-952d58df6023"  # Ne PAS modifier

Vue d'ensemble du processus

  1. Lire les détails de la tâche
  2. Créer une commande (job)
  3. Créer une commande groupée (par liste ou tag)
  4. Lire le statut d’une commande
  5. Voir l’historique d’une commande

1. Lire la tâche regulation_centrale

Endpoint

GET ${BASE_URL}/tasks/${TASK_IDENT}

Exemple de réponse

{
  "ident": "6cdc1f68-5f44-4ec7-91ad-952d58df6023",
  "name": "regulation_centrale",
  "variables_info": {
    "end_timestamp": {
      "type": "timestamp",
      "alias": "Fin",
      "description": "Fin de la période de régulation"
    }
  },
  "constants": {
    "power": "off",
    "value_on": 1,
    "address_on": 40202,
    ...
  },
  "script": "regulation_centrale.lua",
  "active": true
}

2. Créer une commande (job)

Endpoint

POST ${BASE_URL}/tasks/${TASK_IDENT}/jobs
Content-Type: application/json

Corps de requête

{
  "entity_ident": "<ID_DEVICE>",
  "variables": {
    "end_timestamp": 1742200955
  },
  "comment": "Régulation temporaire de la centrale"
}

Réponse attendue

{
  "ident": "job-ident-xyz",
  "status": "transmited",
  "response": "command transmited to mqtt"
}

3. Créer une commande groupée

3.1 Par liste d'équipements

POST ${BASE_URL}/tasks/${TASK_IDENT}/jobs/list

{
  "variables": {
    "end_timestamp": 1742200955
  },
  "comment": "Régulation pour plusieurs centrales",
  "group_name": "regulation_batch_1",
  "ident_list": [
    "device-uuid-1",
    "device-uuid-2"
  ]
}

3.2 Par tag

POST ${BASE_URL}/tasks/${TASK_IDENT}/jobs/tags

{
  "variables": {
    "end_timestamp": 1742200955
  },
  "comment": "Régulation des centrales extérieures",
  "group_name": "tag_group_regulation",
  "tag": "centrales_ext"
}

4. Lire le statut d’un job

Endpoint

GET ${BASE_URL}/jobs/<JOB_IDENT>

Exemple de réponse

{
  "ident": "job-ident-xyz",
  "status": "transmited",
  "created_at": 1742200955,
  "response": "command transmited to mqtt"
}

5. Voir l’historique d’un job

Endpoint

GET ${BASE_URL}/jobs/<JOB_IDENT>/history

Exemple de réponse

{
  "items": [
    {
      "status": "initial",
      "created_at": 1742200955
    },
    {
      "status": "transmited",
      "created_at": 1742200955,
      "response": "command transmited to mqtt"
    }
  ]
}

Groupes de commandes

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

Lister les groupes

GET ${BASE_URL}/groups

Voir les jobs d’un groupe

GET ${BASE_URL}/jobs?group_ident=<GROUP_IDENT>

Récapitulatif des champs

Champ Description
entity_ident ID unique de l’équipement
end_timestamp Timestamp Unix de fin de régulation
comment Commentaire visible pour le job
group_name Nom du groupe pour les jobs groupés
ident_list Liste d’équipements ciblés
tag Tag d’équipements pour une exécution groupée

Planifier une régulation (Schedule)

Vous pouvez planifier l’exécution d’une régulation à une date ultérieure en ajoutant le champ scheduled_time (timestamp Unix) lors de la création du job.

Exemple de requête

POST ${BASE_URL}/tasks/${TASK_IDENT}/jobs
Content-Type: application/json

{
  "entity_ident": "device-uuid-xyz",
  "variables": {
    "end_timestamp": 1742200955
  },
  "scheduled_time": 1750683600,
  "comment": "Régulation programmée demain matin"
}

Le job restera dans l’état scheduled jusqu’à ce que l’heure planifiée soit atteinte.

Annuler une régulation (Cancel)

Si un job est encore en attente ou planifié, vous pouvez l’annuler à tout moment via :

Requête d’annulation

PATCH ${BASE_URL}/jobs/<JOB_IDENT>/cancel

Réponse typique

{
  "status": "cancelled",
  "ident": "job-ident-xyz"
}

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

Pour aller plus loin

Consultez la documentation Swagger pour explorer l’API command dans son ensemble.