Inbound : Programme de soutirage

Version courante du contrat : v0.2

Direction Opérateur de marché → SmartWatt. Vous transmettez chaque jour un programme de soutirage J+1 par site, à la maille 15 minutes en kWh.

Endpoint

POST /api/v0.5/energy-programs/programme-soutirage
Host: api.smartwatt.fr
Authorization: Bearer <INBOUND_TOKEN>
Content-Type: application/json

Le payload est l’enveloppe Programme_Soutirage (1 ou plusieurs sites, créneaux 15 min en kWh). Une instruction est persistée par site listé dans sites[].

Idempotence : envoyer deux fois le même couple (target_date, emitted_at, site_id) produit le même instruction_id côté SmartWatt et écrase l’instruction précédente.

Cadence d’envoi

Quotidien à J 12:30 Europe/Paris pour la journée J+1.

Authentification

Cert client mTLS + token Bearer scopé inbound:programme-soutirage, les deux obligatoires. Le token se génère depuis votre espace dashboard. Voir Authentification pour le détail (cert client, génération du token, rotation).

Un token sans le scope inbound:programme-soutirage reçoit 403 SCOPE_DENIED.

Format du payload

Une enveloppe contenant 1 ou plusieurs sites, chacun avec sa série de créneaux 15 minutes en kWh :

{
  "schema_version": "v0.2",
  "type": "programme_soutirage",
  "emitted_by": "OperateurDeMarche",
  "emitted_at": "2026-05-04T10:10:08Z",
  "target_date": "2026-05-05",
  "slot_duration_secs": 900,
  "sites": [
    {
      "site_id": "PRM12345678901234",
      "site_name": "SiteDemo",
      "energie_programmee": [
        {
          "debut_utc": "2026-05-04T22:00:00Z",
          "fin_utc": "2026-05-04T22:15:00Z",
          "energie_kwh": 0
        },
        {
          "debut_utc": "2026-05-04T22:45:00Z",
          "fin_utc": "2026-05-04T23:00:00Z",
          "energie_kwh": 20
        },
        {
          "debut_utc": "2026-05-04T23:00:00Z",
          "fin_utc": "2026-05-04T23:15:00Z",
          "energie_kwh": 45
        }
      ]
    }
  ]
}

Champs

Champ	Type	Description
schema_version	string	Version du schéma payload (cf. badge en haut de page).
type	string	Toujours "programme_soutirage".
emitted_at	ISO 8601 UTC	Horodatage d’émission du fichier. Sert à dériver l’instruction_id.
target_date	YYYY-MM-DD	Jour cible (J+1 par convention).
slot_duration_secs	int	Durée d’un créneau. Standard : 900 (15 min).
sites[].site_id	string	PRM Enedis sans underscore : PRM + 14 chiffres (ex PRM12345678901234).
sites[].energie_programmee[]	array	Liste contiguë de créneaux. energie_kwh = 0 = effacement.

Sémantique

• energie_kwh > 0 = consommation cible (surconsommation).
• energie_kwh = 0 = effacement (pas de charge sur ce créneau).
• Créneau absent = pas de contrainte.
• Créneaux 15 min alignés sur HH:00, HH:15, HH:30, HH:45.
• Référentiel temporel : ISO 8601 UTC, suffixe Z.

Conversion énergie → puissance

SmartWatt convertit côté SmartWatt :

power_kw = energie_kwh / (slot_duration_secs / 3600)

Pour des créneaux 15 min : power_kw = energie_kwh × 4. SmartWatt applique cette puissance comme plancher sur le créneau : la consigne doit être atteinte au minimum, l’overshoot n’est pas crédité.

Réponse

Succès : 202 Accepted

{
  "status": "received",
  "count": 1,
  "instructions": [
    {
      "instruction_id": "ProgrammeSoutirage-2026-05-05-rev-20260504T101008Z",
      "site_id": "PRM12345678901234",
      "periods_count": 96
    }
  ],
  "message": "instructions persisted, will be applied at next solver cycle"
}

L’instruction_id est dérivé côté SmartWatt, l’expéditeur ne le fournit pas.

Erreurs

Code	error.code	Cas typiques
400	INVALID_PROGRAMME_SOUTIRAGE_REQUEST	schema_version manquant, type ≠ programme_soutirage, target_date mal formé, créneaux non contigus, énergie négative, alignement slot incorrect
401		header Authorization: Bearer absent ou token invalide / expiré / révoqué
403	SCOPE_DENIED ou MTLS_REQUIRED	scope inbound:programme-soutirage absent, cert client mTLS absent, ou subject ne matche pas
503	NO_STORE	base de données indisponible (transitoire, retry après quelques secondes)

Le détail des champs en faute est renvoyé dans error.details (chemin JSON pointer → message) :

{
  "error": {
    "code": "INVALID_PROGRAMME_SOUTIRAGE_REQUEST",
    "message": "ProgrammeSoutirage request validation failed",
    "details": {
      "sites[0].energie_programmee[3].debut_utc": "must be aligned to 900s boundary"
    }
  }
}

Exemple curl

curl -X POST https://api.smartwatt.fr/api/v0.5/energy-programs/programme-soutirage \
  --cert /path/to/bsp-client.crt \
  --key  /path/to/bsp-client.key \
  -H "Authorization: Bearer $INBOUND_TOKEN" \
  -H "Content-Type: application/json" \
  -d @Programme_Soutirage_2026-05-05.json