Introduction

Bienvenue sur la documentation de l'API Pro Capfile. Cette interface REST permet d'interroger les données brutes de soutirage (consommation) et d'injection (production) d'un point de livraison.

Aucune information tarifaire n'est renvoyée par cette API (pas de prix, d'abonnement ni de puissance souscrite) : elle expose les données techniques et énergétiques brutes du compteur, à charge pour l'intégrateur d'appliquer sa propre logique métier.

Démo interactive. Pour tester l'API directement depuis votre navigateur (connexion, quotas, compteurs, graphique de courbe de charge), consultez la page de démonstration.

Base URL : https://api.capfile.com/pro/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/pro/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 techniques brutes d'un PRM : segments contractuels en service, informations techniques (ITC), et grandeurs physiques disponibles en soutirage et en injection. Aucune donnée tarifaire n'est renvoyée par cet endpoint.

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

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

Réponse JSON (extrait, "itc" tronqué)

{
  "success": true,
  "code": 200,
  "message": "OK",
  "data": {
    "prm": "12345678901234",
    "name": "Maison principale",
    "segments": {
      "C5": {
        "segment": "C5",
        "etatContractuel": "En service",
        "etatContractuelCode": "SERVC"
      }
    },
    "itc": {
      "point": {
        "donneesGenerales": { "...": "..." },
        "situationContractuelle": { "...": "..." }
      }
    },
    "soutirage": {
      "grandeurs_physiques": {
        "EA": "Energie Active (Wh)"
      },
      "itc": { "...": "informations techniques spécifiques au flux de soutirage" }
    },
    "injection": {
      "grandeurs_physiques": {
        "EA": "Energie Active (Wh)"
      },
      "itc": { "...": "informations techniques spécifiques au flux d'injection" },
      "puissance_raccordement": 12.0
    }
  }
}
Champs racine
  • segments : Dictionnaire des segments contractuels connus pour ce PRM, avec leur état contractuel.
  • itc : Informations Techniques et Contractuelles du point de livraison. Structure riche et variable selon le compteur.
Structure soutirage / injection
  • grandeurs_physiques : Dictionnaire code → libellé des grandeurs physiques mesurées et disponibles pour ce flux (ex. EA = Energie Active). La liste dépend du compteur — voir la table des grandeurs physiques.
  • itc : Informations techniques spécifiques au flux (injection ou soutirage).
  • puissance_raccordement (injection uniquement) : Puissance de raccordement en kVA, 0 si non disponible.

Le bloc soutirage est absent si le PRM ne soutire pas ; le bloc injection est absent si le PRM n'injecte pas.

Données d'Index

Récupère l'historique des index relevés chaque jour à minuit, pour une grandeur physique donnée. Cet endpoint requiert l'authentification par API Key (x-api-key).

GET /data/{PRM}/index/{SENS}/{GP}
Exemple d'URL complète :
https://api.capfile.com/pro/v1/data/12345678901234/index/sou/EA?start_date=2024-01-01&end_date=2024-01-02
Paramètre SENS (obligatoire)

Définit le flux :

  • sou : Soutirage (consommation)
  • inj : Injection (production)
Paramètre GP — grandeur physique (obligatoire)

Code de la grandeur physique à récupérer (ex. EA, ER…). Les valeurs possibles dépendent du compteur : consultez le champ grandeurs_physiques renvoyé par /data/{PRM}/info pour ce PRM, dans le bloc soutirage ou injection correspondant. Une valeur non disponible pour ce compteur renvoie une erreur 400.

Différence vs Réel

Les champs sont doublés dans chaque ligne de data :

  • NOM_CADRAN : Différence par rapport à la veille (valeur "journalière"), dans l'unité de la grandeur physique (ex. Wh pour EA).
  • cadran_NOM_CADRAN : Index cumulé lu sur le compteur à minuit.

Réponse JSON

{
  "success": true,
  "code": 200,
  "message": "OK",
  "data": {
    "head": {
      "prm": "12345678901234",
      "type": "index",
      "sens": "SOU",
      "grandeur_physique": "EA",
      "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"
      },
      {
        "date": "2026-03-05",
        "BASE": "11021",
        "Total": "11021",
        "cadran_BASE": "17550918",
        "cadran_Total": "17550918"
      }
    ]
  }
}

Le nombre et le nom des champs (autres que date et Total) dépendent des cadrans réellement utilisés par le compteur pour la grandeur physique demandée.

Courbe de Charge

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

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

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 :

  • 5 minutes
  • 10 minutes
  • 15 minutes
  • 30 minutes
  • 60 minutes

Réponse JSON

{
  "success": true,
  "code": 200,
  "message": "OK",
  "data": {
    "head": {
      "prm": "04389580265458",
      "type": "loadcurve",
      "sens": "CONS",
      "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 l'API 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).

GET /quotas

Consulte vos quotas autorisés, votre consommation actuelle et le nombre d'appels restants sur chaque période. Cet endpoint requiert l'authentification par API Key (x-api-key) et n'est pas soumis lui-même au décompte des quotas.

Exemple d'URL complète :
https://api.capfile.com/pro/v1/quotas

Réponse JSON

{
  "success": true,
  "code": 200,
  "message": "Usage et quotas",
  "data": {
    "quotas": {
      "day": 5000,
      "week": 50000,
      "month": 300000
    },
    "usage": {
      "day": 120,
      "week": 890,
      "month": 3400
    },
    "remaining": {
      "day": 4880,
      "week": 49110,
      "month": 296600
    }
  }
}
Champs de réponse
  • quotas : Limites autorisées pour votre compte, par période.
  • usage : Nombre d'appels déjà effectués sur la période en cours (jour, semaine calendaire, mois calendaire).
  • remaining : Nombre d'appels restants avant d'atteindre chaque quota (jamais négatif).

Table des grandeurs physiques

Codes utilisables pour le paramètre {GP} de l'endpoint /index. La disponibilité réelle par PRM est donnée par grandeurs_physiques dans /info.

Codes connus
  • EA : Energie Active (Wh)
  • ER : Energie Réactive (VARh)
  • ERI : Energie Réactive Inductive (VARh)
  • ERC : Energie Réactive Capacitive (VARh)
  • PMA : Puissance Maximale (VA)
  • TF : Temps de Fonctionnement (s)
  • DD : Durée de Dépassement (s)
  • DE : Dépassement Energétique (s)
  • DQ : Dépassement Quadratique (W)

Codes d'erreur détaillés

400 Bad Request

La requête contient des erreurs de syntaxe ou des paramètres manquants/invalides. Causes possibles :

  • PRM mal formé (doit faire exactement 14 chiffres).
  • {SENS} manquant ou différent de sou/inj.
  • {GP} manquant ou non disponible pour ce compteur (voir grandeurs_physiques dans /info).
  • Format de date invalide (le format attendu est YYYY-MM-DD).

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 (3 ans pour /index, 1 an pour /loadcurve).

429 Too Many Requests

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