Introduction

Bienvenue sur la documentation officielle de l'API Capfile. Cette interface REST permet d'interroger les données de consommation et de production issues des compteurs Linky de type C5 (consommation) et P4 (injection) .

L'API est conçue pour être intégrée facilement dans des systèmes domotiques (Home Assistant, Jeedom) ou des applications de suivi énergétique.

Version bêta. Cette intégration est fournie en l'état, à titre expérimental. Capfile décline toute responsabilité en cas de dysfonctionnement, de perte de données ou de tout préjudice lié à son utilisation.
Usage personnel uniquement. Cette API est réservée à un usage privé par des particuliers. Elle ne peut pas être utilisée à des fins commerciales ou pour le compte de tiers.

Base URL : https://api.capfile.com/free/v1/

Authentification

Deux modes d'authentification sont disponibles selon l'action effectuée :

  • Basic Auth : Obligatoire pour la gestion de la clé. Format Authorization: Basic Base64(login:password).
  • API Key Auth : Recommandé pour l'accès aux données. En-tête : x-api-key: VOTRE_CLE_API.

Gestion de la Clé API

Endpoints accessibles uniquement via Basic Auth.

GET /api_key

Récupère la clé API active associée à votre compte.

{
  "success": true,
  "code": 200,
  "message": "Clé API",
  "data": {
    "api_key": "TamxBsK9hTjszezcSy4sdfsdfsdfqRmYUFo"
  }
}
GET /api_key/renew

Révoque la clé actuelle et en génère une nouvelle immédiatement.

{
  "success": true,
  "code": 200,
  "message": "Clé API renouvelée",
  "data": {
    "api_key": "anQBz1brst89eymswVCqhk29mpKqnb7n"
  }
}

Compteurs

Récupère la liste de tous les compteurs accessibles avec la clé API fournie, y compris les compteurs partagés par d'autres utilisateurs Capfile.

Cet endpoint requiert l'authentification par API Key (x-api-key).

GET /meters
Exemple d'URL complète :
https://api.capfile.com/free/v1/meters

Réponse JSON

{
  "success": true,
  "code": 200,
  "message": "OK",
  "data": [
    {
      "prm": "12345678901234",
      "name": "Maison principale"
    },
    {
      "prm": "98765432109876",
      "name": "Appartement voisin",
      "shared": true
    }
  ]
}
Champs de réponse
  • prm : Identifiant du point de livraison (14 chiffres).
  • name : Nom du site associé au compteur.
  • shared : Présent et à true uniquement si le compteur appartient à un autre utilisateur Capfile et vous a été partagé. Ce champ est absent pour vos propres compteurs.
Compteurs partagés

Un même compte peut avoir accès à des compteurs appartenant à d'autres utilisateurs Capfile. Pour ces compteurs (shared: true), l'accès aux endpoints /info, /index et /loadcurve dépend des options de partage définies par le propriétaire du compteur.

Infos Compteur

Récupère les informations sur un PRM : cadrans tarifaires, labels, couleurs, tarifs en vigueur, abonnement, puissance souscrite et données d'injection (pour les compteurs avec production solaire ou autre).

Cet endpoint requiert l'authentification par API Key (x-api-key).

GET /data/{PRM}/info
Exemple d'URL complète :
https://api.capfile.com/free/v1/data/12345678901234/info

Réponse JSON

{
  "success": true,
  "code": 200,
  "message": "OK",
  "data": {
    "prm": "12345678901234",
    "name": "Maison principale",
    "soutirage": {
      "cadrans": {
        "BUHC": {
          "label": "Bleu Heures Creuses",
          "color": "#61acf0",
          "cadran": 1
        },
        "BUHP": {
          "label": "Bleu Heures Pleines",
          "color": "#3b82f6",
          "cadran": 2
        },
        "RHC": {
          "label": "Rouge Heures Creuses",
          "color": "#f87171",
          "cadran": 3
        },
        "RHP": {
          "label": "Rouge Heures Pleines",
          "color": "#dc2626",
          "cadran": 4
        }
      },
      "prices": {
        "conso": {
          "BUHC": 1740,
          "BUHP": 2516,
          "RHC": 1740,
          "RHP": 5842
        },
        "abonnement": 15.5,
        "puissance_souscrite": 9.0,
        "offer_name": "Tempo"
      }
    },
    "injection": {
      "cadrans": {
        "BASEINJ": {
          "label": "Injection",
          "color": "#10b981",
          "cadran": 1
        }
      },
      "puissance_raccordement": 12.0
    }
  }
}
Structure soutirage
  • cadrans : Dictionnaire des cadrans de consommation. Chaque clé est le nom du cadran (ex: BASE, HP, BUHC…). cadran est l'index d'ordre (1-based).
  • prices.conso : Prix par cadran en centimes/kWh.
  • prices.abonnement : Coût de l'abonnement mensuel en €/mois.
  • prices.puissance_souscrite : Puissance souscrite en kVA.
  • prices.offer_name : Nom de l'offre tarifaire (ex : "Base", "HP/HC", "Tempo").

Le bloc soutirage est absent pour les compteurs qui ne mesurent que de l'injection (compteurs P4 sans consommation).

Structure injection

Le bloc injection n'est présent que pour les compteurs avec production d'énergie raccordée au réseau. Il suit la même structure de cadrans que le soutirage.

  • cadrans : Cadrans d'injection avec label, couleur et ordre.
  • puissance_raccordement : Puissance de raccordement en kVA.

Si le compteur n'a pas d'énergie injectée, le bloc injection est absent.

Données d'Index

Récupère les index relevés chaque jour à minuit. Le contenu de la réponse dépend de l'abonnement du PRM (Base, HP/HC, Tempo). Cet endpoint requiert l'authentification par API Key (x-api-key).

Note Importante : Les noms des champs (cadrans) varient selon l'abonnement de l'utilisateur. Par exemple, un utilisateur Tempo disposera de 6 cadrans de consommation (BCHC, BCHP, BUHC, BUHP, RHC, RHP).

Décalage de transmission : Enedis transmet les relevés à Capfile avec un délai d'environ 48 heures. La donnée du jour J n'est donc disponible qu'aux alentours du jour J+2.


Recommandation : Effectuez vos appels après 11h30 (heure de Paris) pour maximiser la fraîcheur des données disponibles. Évitez les appels répétés tout au long de la journée : les données n'évoluent pas en continu et une synchronisation quotidienne unique suffit à préserver vos quotas.

GET /data/{PRM}/index/{TYPE}
Exemple d'URL complète :
https://api.capfile.com/free/v1/data/12345678901234/index/sou?start_date=2024-01-01&end_date=2024-01-02
Différence vs Réel

Les champs sont doublés :

  • NOM_CADRAN : Représente la consommation journalière (différence par rapport à la veille), en Wh.
  • cadran_NOM_CADRAN : Représente l'index cumulé lu sur le compteur à minuit, en Wh.
Paramètre TYPE

Définit le flux :

  • sou : Soutirage (consommation)
  • inj : Injection (production)

Exemple abonnement TEMPO (6 cadrans)

{
  "success": true,
  "code": 200,
  "message": "OK",
  "data": {
    "head": {
      "prm": "12345678901234",
      "type": "index",
      "sens": "SOU",
      "start_date": "2026-03-04",
      "end_date": "2026-03-11"
    },
    "data": [
      {
        "date": "2026-03-04",
        "BCHC": "1008",
        "BCHP": "0",
        "BUHC": "324",
        "BUHP": "2685",
        "RHC": "0",
        "RHP": "0",
        "Total": "4017",
        "cadran_BCHC": "631619",
        "cadran_BCHP": "620574",
        "cadran_BUHC": "11621742",
        "cadran_BUHP": "13411709",
        "cadran_RHC": "432698",
        "cadran_RHP": "195102",
        "cadran_Total": "26913444"
      },
      {
        "date": "2026-03-05",
        "BCHC": "0",
        "BCHP": "0",
        "BUHC": "1365",
        "BUHP": "2656",
        "RHC": "0",
        "RHP": "0",
        "Total": "4021",
        "cadran_BCHC": "631619",
        "cadran_BCHP": "620574",
        "cadran_BUHC": "11623107",
        "cadran_BUHP": "13414365",
        "cadran_RHC": "432698",
        "cadran_RHP": "195102",
        "cadran_Total": "26917465"
      }
    ]
  }
}

Réponse standard SOU (Base)

{
  "success": true,
  "code": 200,
  "message": "OK",
  "data": {
    "head": {
      "prm": "12345678901234",
      "type": "index",
      "sens": "SOU",
      "start_date": "2026-03-04",
      "end_date": "2026-03-11"
    },
    "data": [
      {
        "date": "2026-03-04",
        "BASE": "11593",
        "Total": "11593",
        "cadran_BASE": "17539897",
        "cadran_Total": "17539897"
      }
    ]
  }
}

Réponse standard INJ

{
  "success": true,
  "code": 200,
  "message": "OK",
  "data": {
    "head": {
      "prm": "12345678901234",
      "type": "index",
      "sens": "INJ",
      "start_date": "2026-03-04",
      "end_date": "2026-03-11"
    },
    "data": [
      {
        "date": "2026-03-04",
        "BASEINJ": "1611",
        "Total": "1611",
        "cadran_BASEINJ": "7106890",
        "cadran_Total": "7106890"
      }
    ]
  }
}

Courbe de Charge

Données précises au pas défini par le compteur. Unité : Wh (numérique).

GET /data/{PRM}/loadcurve/{TYPE}
Exemple d'URL complète :
https://api.capfile.com/free/v1/data/12345678901234/loadcurve/sou?start_date=2024-03-10&end_date=2024-03-11
Paramètre TYPE

Définit le flux :

  • sou : Soutirage (consommation)
  • inj : Injection (production)
Paramètre "p" (Le Pas)

Le champ p indique la durée de l'intervalle de mesure en minutes. Selon la configuration du compteur, ce pas peut être de :

  • 15 minutes
  • 30 minutes (standard)
  • 60 minutes

Réponse JSON

{
  "success": true,
  "code": 200,
  "message": "OK",
  "data": {
    "head": {
      "prm": "04389580265458",
      "type": "loadcurve",
      "sens": "SOU",
      "start_date": "2026-03-01",
      "end_date": "2026-03-11"
    },
    "data": [
      {
        "date_time": "2026-03-01T00:00:00Z",
        "p": 30,
        "Wh": 81
      },
      {
        "date_time": "2026-03-01T00:30:00Z",
        "p": 30,
        "Wh": 92
      },
      {
        "date_time": "2026-03-01T01:00:00Z",
        "p": 30,
        "Wh": 81
      }
    ]
  }
}

Gestion des Quotas

L'utilisation de la version Free est encadrée par des quotas fixes basés sur le calendrier (et non glissants) :

  • Quotas quotidiens : Se réinitialisent chaque jour à 00:00.
  • Quotas hebdomadaires : Basés sur la semaine calendaire, du Lundi au Dimanche.
  • Quotas mensuels : Basés sur le mois calendaire en cours.

Le dépassement de l'une de ces limites entraîne une erreur 429. Les compteurs sont remis à zéro au début de chaque nouvelle période (jour, lundi ou 1er du mois).

Codes d'erreur détaillés

400 Bad Request

La requête contient des erreurs de syntaxe. Causes possibles :

  • PRM mal formé (doit faire exactement 14 chiffres).
  • Format de date invalide (le format attendu est YYYY-MM-DD).
  • Paramètres de query string manquants ou incohérents.

401 Unauthorized

Identifiants Basic Auth incorrects ou clé API x-api-key non reconnue.

403 Forbidden

Accès refusé au PRM demandé ou demande hors plage historique autorisée (max 3 ans).

429 Too Many Requests

Un des quotas (Journalier, Hebdomadaire ou Mensuel) a été atteint.