SWITCHGRID
DOCS

Extraction de factures

GuideSpec OpenAPI — v0.1
Versions précédentes
Spec OpenAPI — v0
Release Notes

Introduction

L'API d'extraction lit une facture d'électricité française (un PDF, ou une photo de chaque page) et en restitue, sous forme structurée :

  • les prix HT imprimés par le fournisseur ;
  • les prix TTC tout compris (part fixe en €/mois, part variable en €/kWh) ;
  • la puissance souscrite ;
  • le PRM ;
  • le fournisseur ;
  • le régime de facturation du contrat.

Lancer une extraction

Un seul appel : envoyez la facture en multipart/form-data, dans le champ file — un PDF, ou une image PNG, JPEG, WebP ou HEIC. La réponse arrive quand les tarifs ont été lus (comptez 20 s à 1 min).

curl -X POST https://api.switchgrid.tech/extraction-tarifs-facture \
  -H "Authorization: Bearer $SWITCHGRID_API_KEY" \
  -H 'x-api-version: v0.1' \
  -F file=@facture.pdf
ℹ️

Envoyez toujours x-api-version: v0.1. Sans l'en-tête, l'appel reçoit la v0 — champs en anglais, prix sans décomposition — et rien de ce que décrit ce guide.

Sans écrire de code, vous pouvez aussi lancer une extraction depuis l'application, sur la page Extraction de factures de votre projet (/w/{workspace}/p/{projet}/invoice-extraction) : déposez-y le PDF ou la photo, le résultat s'affiche dans la page. Ouvrir l'extraction de factures de mon projet.

Envoyer des photos de chacune des pages

Pour envoyer une série d'images représentant les pages d'une facture dans l'ordre, vous pouvez faire cette requête :

curl -X POST https://api.switchgrid.tech/extraction-tarifs-facture \
  -H "Authorization: Bearer $SWITCHGRID_API_KEY" \
  -H 'x-api-version: v0.1' \
  -F file=@page-1.jpg \
  -F file=@page-2.jpg \
  -F file=@page-3.jpg
  • Formats : PNG, JPEG, WebP ou HEIC (les photos d'iPhone).
  • 20 pages au plus par appel.
  • Envoyez les pages d'une seule facture : un appel lit une facture, et plusieurs factures reconnues à la suite sont refusées (TARIFS_NON_EXTRAITS).

Format de réponse

Autour des identifiants (id, statut, point_de_livraison, fournisseur, cree_le…), la réponse porte quatre sections. Chacune vaut null quand rien n'a pu être établi.

statut

Une extraction qui aboutit répond toujours HTTP 200, même si rien n'a été extrait :

  • EXTRAITE — les prix ont été lus, prix_HT est rempli ;
  • TARIFS_NON_EXTRAITS — le document est bien une facture, mais ses prix n'ont pas pu être lus de façon fiable (lectures discordantes, fournisseur non identifié) : prix_HT vaut null ;
  • PAS_UNE_FACTURE — le document n'est pas une facture d'électricité (courrier, avenant, autre fichier) : prix_HT vaut null.

Ces deux derniers statuts sont des réponses valides, pas des erreurs : relancer le même fichier à l'aveugle n'y change en général rien. EN_COURS existe dans la spec mais n'est jamais renvoyé par cet appel, qui ne répond qu'une fois l'extraction terminée.

puissance_souscrite

Constante ({ "_tag": "constant", "puissance_souscrite_kVA": 18 }) ou périodisée quand la facture en change.

prix_HT

Les prix que le fournisseur imprime — ce que les factures appellent HT ou HTT :

  • abonnement[] — { periode, prix_EUR_par_mois, parts } ;
  • consommation[] — { periode, prix_EUR_par_kWh, parts }, le prix étant une structure taguée par option (base, 2_cadrans HP/HC, cadrans saisonniers, tempo, ejp).

Un prix est accompagné de ses parts. Une part, c'est un montant et les composantes que ce montant couvre :

"parts": [
  { "composantes": ["fourniture"], "prix_EUR_par_kWh": { "_tag": "2_cadrans", "HP": "0.1", "HC": "0.06" } },
  { "composantes": ["acheminement.soutirage_variable"], "prix_EUR_par_kWh": { "_tag": "2_cadrans", "HP": "0.04", "HC": "0.03" } },
  { "composantes": ["capacite"], "prix_EUR_par_kWh": { "_tag": "2_cadrans", "HP": "0.005", "HC": "0.005" } },
  { "composantes": ["cee"], "prix_EUR_par_kWh": { "_tag": "2_cadrans", "HP": "0.005", "HC": "0.005" } }
]

Une facture qui imprime un seul prix tout compris — la présentation des particuliers — a une seule part, qui porte toutes les composantes qu'elle facture :

"parts": [
  { "composantes": ["fourniture", "acheminement.soutirage_variable", "capacite", "cee"],
    "prix_EUR_par_kWh": { "_tag": "base", "base": "0.2516" } }
]

C'est la différence avec un champ par composante : ce prix-là facture bien les CEE, fondus dans son prix unique, et il le dit. Deux règles sur lesquelles vous pouvez compter :

  • une composante appartient à au plus une part — jamais comptée deux fois ;
  • le prix est la somme de ses parts, à une exception documentée : aide (amortisseur électricité, bouclier tarifaire) est un crédit, porté par sa propre part et jamais compris dans le total. Soustrayez-la, ou non, selon ce que vous voulez lire.

Les composantes d'acheminement sont nommées en entier — acheminement.gestion, acheminement.comptage, acheminement.soutirage_fixe, acheminement.soutirage_variable — parce que le TURPE a un côté fixe et un côté variable qui atterrissent dans deux sections différentes.

Une composante qui n'apparaît sur aucune part n'est pas facturée ici.

L'acheminement : trois cas

L'acheminement (TURPE) se présente de trois façons sur une facture, et les parts disent dans laquelle on se trouve.

  1. Acheminement intégré. Le fournisseur ne répercute pas l'acheminement sur des lignes à part : il est inclus dans le prix HT annoncé. C'est le cas classique des factures en Base, alors que le distributeur, lui, facture sur quatre cadrans : le fournisseur fait tampon et ajuste éventuellement ses tarifs sur les périodes suivantes. Chaque prix a une seule part, qui porte fourniture avec les composantes d'acheminement.
  2. Acheminement séparé (ou répercuté, détaillé). L'acheminement fait l'objet de lignes spécifiques, et le prix HT annoncé est sans acheminement. La fourniture et l'acheminement ont chacun leurs parts, une par ligne imprimée (gestion, comptage, soutirage fixe), et le prix en est la somme : c'est le prix complet.
  3. Contrat CARD. L'acheminement n'est pas sur la facture du fournisseur : le distributeur le facture directement au client, en général pour les grandes puissances. Aucune part ne porte de composante acheminement.*.

Dans les trois cas, les composantes fixes (acheminement.gestion, .comptage, .soutirage_fixe) sont dans l'abonnement, la part variable (acheminement.soutirage_variable) dans la consommation. Une facture sans abonnement fournisseur (courant sur un site C4) a quand même une entrée d'abonnement, faite de la seule part du réseau.

Les lignes d'acheminement sont imprimées en montants de période ; elles sont ramenées en €/mois au prorata des jours, ou telles quelles quand la facture dit qu'elles couvrent « 1 mois ». Quand le distributeur facture un mois d'avance puis corrige (lignes « reprise », « échu », « à échoir »), seul l'échu est retenu : c'est la charge réelle du mois, et les deux autres s'annulent d'une facture à l'autre.

Une part qui porte fourniture, capacite ou aide peut être négative (certains contrats de marché 2023-2024, mécanisme de capacité crédité en heures creuses, aides d'État) ; une part faite uniquement de tarifs de réseau et de contributions ne l'est jamais.

garanties_origine est l'option « électricité verte » quand le fournisseur la facture au kWh — « Option Energie renouvelable » chez EDF, « Electricité d'origine renouvelable » chez ENGIE. Le fournisseur achète et annule pour vous des garanties d'origine, un certificat par MWh. Elle est comprise dans total, contrairement à aide : le client la paie, et la facture la compte dans son propre total de consommation. Soustrayez-la pour obtenir le prix de la fourniture sans l'option.

Vendue au forfait — « Option Energie Verte » en montant de période chez ENGIE pro, « Option Elec Vert+ » à 2,50 €/mois chez ENGIE particuliers —, elle est une part garanties_origine de l'abonnement, ramenée en €/mois et comprise dans abonnement[].prix_EUR_par_mois : le client la paie chaque mois. Et quand l'offre inclut l'option dans son prix (la mention « Elec Verte » d'ENGIE), garanties_origine est portée par la part fourniture elle-même, au kWh comme dans l'abonnement — ["fourniture", "garanties_origine"] —, sauf là où la facture l'isole sur sa propre ligne.

"prix_EUR_par_kWh": { "_tag": "2_cadrans", "HP": "0.15", "HC": "0.1" }

Les périodes sont "AAAA-MM-JJ/AAAA-MM-JJ", fin exclusive. La sentinelle "Indisponible" marque une valeur que la facture ne donne pas.

prix_TTC

ℹ️

En développement. Cette partie va évoluer au fil des prochaines versions ; sa forme peut encore changer.

Le prix tout compris que paie le client final : part_fixe[] ({ periode, prix_EUR_par_mois }) et part_variable[] ({ periode, prix_EUR_par_kWh }). Une période qu'on ne sait pas calculer est absente. Un contrat CARD n'a pas de prix_TTC.

regimes

Ce sur quoi le contrat indexe son prix — l'information qui permet de simuler l'évolution future. Même convention que puissance_souscrite : { "_tag": "constant", … } quand un seul régime couvre toute la facture (le cas courant), { "_tag": "periodes", "periodes": [{ "periode": "AAAA-MM-JJ/AAAA-MM-JJ", … }] } quand la facture chevauche un renouvellement de contrat. Les champs :

  • indexation :
    • TRV — la facture est au TRV (Tarif Réglementé de Vente) ;
    • INDEXE_TRV — offre de marché qui suit le TRV, généralement avec une remise (remise_trv_centi_pourcent, en centièmes de % : 500 = −5 %) ;
    • PRIX_FIXE — fourniture contractuellement gelée, jusqu'à echeance_prix_fixe quand la facture imprime la date ; taxes et tarif réseau restent répercutés ;
    • INDEXE_MARCHE — indexé sur les prix de gros ;
    • null — la facture ne permet pas de trancher. null signifie « non déterminé ».
  • confiance — haute, moyenne ou basse.

regimes est null sur son ensemble quand rien n'a pu être établi ou pour les extractions antérieures à cette fonctionnalité.

SWITCHGRID
© 2024 - 2026 Switchgrid