Abonnementen en API-toegang

De App heeft vier niveaus. De actuele prijzen staan op de prijzenpagina; onderstaande functiegrenzen bepalen welke documentatie voor een account geldt.

Abonnementsoverzicht

Cloud Voice werkt op UltimateSensor V2 met cloudfirmware. Instellingen en verbruik staan onder Instellingen > Cloud Voice; zie de handleiding voor de spraakassistent.

De waarschuwingslimieten staan in Locaties en waarschuwingen.

Persoonlijke API-tokens

Maak tokens onder Instellingen > API Tokens. Geef ieder token een herkenbare naam. Rechten kies je niet zelf: een token krijgt de rechten van je abonnement op het moment dat je het aanmaakt. Ieder abonnement krijgt toegang tot prijzen. Pro en Business krijgen ook toegang tot apparaten, metingen, statistieken, zonnevoorspelling en export. Maak na een upgrade een nieuw token om de extra rechten te gebruiken.

Behandel een token als een wachtwoord:

• kopieer het eenmaal naar de bestemming en bewaar het in een wachtwoordmanager;
• plaats het nooit in screenshots, openbare YAML of een Git-repository;
• gebruik een apart token voor Home Assistant en iedere externe toepassing;
• trek het direct in en vervang het wanneer het mogelijk is uitgelekt.

Gedrag van de API

De API is geversioneerd onder /api/v1 op https://api.smarthomeshop.io, met een limiet van 60 verzoeken per minuut per gebruiker. Clients moeten authenticatiefouten, validatieresponsen, limieten en tijdelijke onbeschikbaarheid afhandelen. Vraag met een redelijk interval op en cache resultaten, in plaats van dezelfde historie steeds opnieuw op te halen.

Dynamische prijseindpunten zijn toegankelijk met een geauthenticeerd token met het juiste prijsrecht. De bredere Cloud API voor apparaten en metingen is beperkt tot Pro en Business. Een token krijgt nooit meer toegang dan het abonnement en de toegekende rechten toestaan.

Respons van de Energy Price API

GET /api/v1/energy/prices gebruikt de bestaande bearer-tokenauthenticatie en het recht prices:read. Naast de bestaande velden voor elektriciteit, gas, samenvatting en tarieven bevat de respons veilige bron- en contractmetadata:

{
  "pricing": {
    "source": "SmartHomeShop.io",
    "market": "EPEX NL",
    "price_type": "all_in",
    "currency": "EUR",
    "unit": "kWh",
    "timezone": "Europe/Amsterdam"
  },
  "contract": {
    "name": "Mijn thuiscontract",
    "supplier": "Voorbeeld Energie",
    "provider": "Voorbeeld Energie",
    "product": "Dynamisch Energiecontract",
    "type": "dynamic",
    "location_id": 12,
    "location_name": "Thuis",
    "location": {
      "id": 12,
      "name": "Thuis"
    },
    "starts_at": "2026-01-01",
    "ends_at": null,
    "standing_charge_monthly": 7.5,
    "import_markup_per_kwh": 0.021,
    "feed_in_markup_per_kwh": 0.018,
    "currency": "EUR"
  }
}

Gebruik GET /api/v1/energy/prices?location=12 om het actieve contract te kiezen dat aan een locatie is gekoppeld, of ?contract=34 om direct een eigen contract vast te zetten. Een locatie zonder eigen contract gebruikt het contract op Alle locaties. name is de zelf ingestelde contractnaam, provider is de leesbare leveranciersnaam en location.name is de zelf ingestelde locatienaam.

GET /api/v1/energy/contracts geeft zowel de backwards-compatible vlakke lijst contracts als een lijst locations. Iedere locatie bevat het bijbehorende active_contract, of null als die locatie geen huidig contract heeft. Per locatie kan slechts één actief contract dezelfde periode omvatten.

Als geen toepasbaar contract kan worden bepaald, antwoordt het prijseindpunt met HTTP 422 en code energy_contract_required; stroom-, gas- en samenvattingsprijzen ontbreken dan volledig. Geldbedragen zijn JSON-nummers en optionele waarden kunnen null zijn. Klantnummers en privéreferenties worden nooit teruggestuurd.