Guides d'installation → API push

API push

Pas d'adaptateur pour votre onduleur ? Envoyez les relevés vous-même depuis un script shell, un flux Node-RED ou une tâche cron.

À quelle fréquenceToutes les 30 s — pas plus vite

CompatibleTout ce qui sait faire une requête HTTP

Le point d'entrée

POST https://api.sunplug.app/ingest/site
Authorization: Bearer <votre clé d'API>
Content-Type: application/json

{
  "tsms": 1785759034000,
  "production_kw": 4.2,
  "net_import_kw": -3.1,
  "consumption_kw": 1.1,
  "battery_discharge_kw": 0.0,
  "battery_soc": 0.62
}

Votre clé se trouve dans l'application, sous Réglages → Équipement → Envoyez vos propres relevés.

Les champs

tsmsMoment du relevé, en millisecondes depuis 1970

production_kwProduction solaire. Toujours positive

net_import_kwRéseau. Positif en soutirage, négatif en injection

consumption_kwToute la maison, recharge des voitures comprise

battery_discharge_kwPositif en décharge, négatif en charge. Optionnel

battery_socUne fraction — 0,62 pour 62 %. Optionnel

La seule chose à ne pas rater

L'injection doit être négative. Tout s'équilibre : consommation = production + réseau + décharge batterie. Avec le signe du réseau inversé, Sunplug voit un soutirage de 3 kW par un après-midi ensoleillé et ne charge pas, sans aucune erreur.

Si vous mesurez deux des trois, omettez le troisième ; il sera déduit. Un troisième chiffre faux est pire que rien. La production seule est refusée.

Un exemple

curl -sS -X POST https://api.sunplug.app/ingest/site \
  -H "Authorization: Bearer $SUNPLUG_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"tsms\": $(date +%s000), \"production_kw\": 4.2,
       \"net_import_kw\": -3.1, \"consumption_kw\": 1.1}"

À quelle fréquence

Toutes les trente secondes ; plus vite n'apporte rien. Plus lent est accepté et affiché comme moins frais. Les doublons et les relevés légèrement dans le désordre ne posent aucun problème.

L'âge des données, à côté des valeurs en direct du tableau de bord, doit se stabiliser à votre intervalle d'envoi. S'il grimpe, vos envois échouent : le corps de la réponse nomme le champ refusé.

Vous venez de ChargeHQ

Les noms de champs, les unités et les conventions de signe sont ceux de ChargeHQ. Trois choses changent :

L'adresse. api.chargehq.net/api/public/push-solar-data devient api.sunplug.app/ingest/site.
La clé sort du corps. ChargeHQ attend apiKey comme champ JSON ; Sunplug attend un en-tête Authorization: Bearer.
Les relevés sortent de leur boîte. Pas d'objet siteMeters ; les relevés vont au premier niveau.

Ce que vous envoyez à ChargeHQ :

POST https://api.chargehq.net/api/public/push-solar-data

{
  "apiKey": "VOTRE-CLE",
  "siteMeters": {
    "production_kw": 4.2,
    "net_import_kw": -3.1,
    "consumption_kw": 1.1
  }
}

Le même relevé, envoyé ici :

POST https://api.sunplug.app/ingest/site
Authorization: Bearer VOTRE-CLE

{
  "production_kw": 4.2,
  "net_import_kw": -3.1,
  "consumption_kw": 1.1
}

Aucun point d'entrée n'accepte le format de ChargeHQ tel quel.

Bloqué, ou vous préféreriez un adaptateur ? Écrivez-moi.