NAV Navbar

Home

API overzicht

Shifft P4 API is een product van Shifft BV en biedt partijen de mogelijkheid om zelfstandig P4 data te verwerken.

De API is een RESTFul service. Deze verloopt via het HTTPS-protocol. De status van een verzoek wordt gecommuniceerd door middel van http status codes. Bij een succesvol verzoek wordt de data in JSON formaat geretourneerd.

Beveiliging

Voorbeeld 1A

-----BEGIN CERTIFICATE-----
MIIDsTCCApmgAwIBAgIBADANBgkqhkiG9w0BAQUFADBzMQswCQYDVQQGEwJOTDEV
MBMGA1UECAwMWnVpZC1Ib2xsYW5kMQ4wDAYDVQQHDAVEZWxmdDEPMA0GA1UECgwG
c2hpZmZ0MQwwCgYDVQQLDANpY3QxHjAcBgkqhkiG9w0BCQEWD21haWxAc2hpZmZ0
LmNvbTAeFw0xNDA5MjIwNzQxMTBaFw0xNTA5MjIwNzQxMTBaMHMxCzAJBgNVBAYT
Ak5MMRUwEwYDVQQIDAxadWlkLUhvbGxhbmQxDjAMBgNVBAcMBURlbGZ0MQ8wDQYD
VQQKDAZzaGlmZnQxDDAKBgNVBAsMA2ljdDEeMBwGCSqGSIb3DQEJARYPbWFpbEBz
aGlmZnQuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA8RMzFFSL
5r5PFpL1NCYz+g6GvshhOEKbKCvs8drJjQnLDG7qK87jKcLh7pf1dwubO1ZTjwNc
Kv+XXuyGxjbSDzpCUhLg/g++8ki/yqNUvukO7A+L20LqscSAsAPV2Eo7cGLur0MG
cKvYEZ1dMFVFys6hPsMSsIJAlUruk45rJaAHx4BqSThG1XyzZsWRNQ74pOAibMJB
+wn5bpB6VxxmgWfITXU2CA2KD9zG++12ZFBpWFqIm2Y0bDno2aE0h4RAq09KWwyz
3amNks6p0vb+e6+An7Bv0xPt6v/Pki4RTjfy9CsLenDb3IcN2A/U9vIwFRwy2efd
HF96ugs4YL1KzwIDAQABo1AwTjAdBgNVHQ4EFgQURlTABUBjv4SAAQi6CZxToF6e
+7IwHwYDVR0jBBgwFoAURlTABUBjv4SAAQi6CZxToF6e+7IwDAYDVR0TBAUwAwEB
/zANBgkqhkiG9w0BAQUFAAOCAQEAmkrvWPqUM8qYDB3Yry0o6Fc5ASv3OWwOJSvq
7AymI8in3A8A+GZ46jw51C/vQc1CAFkZsi/XzQS7Q8QclZ5c+8Xmfb/mUQF6YDoR
rBf3MKMEpP5wHXa2kh5Z3xp/t3UkUll2OoAvbI7mrhIukqten4ztkDHM7aKOBkZe
cWkzeIUhxNZMzduYLPLeteNoeQ9p/guwFzeBi/VOaMXGZWC+XuiSGz8T5yd5Jv48
ikG0c1YVF0UnSnesFa8ro1CK2cdHHZPOWnTUM33vyJgFJnkQ30Fpt01ijgvCioJH
erKkWvjzs/ZNrC7OZDOb93p1LruL4nkKMS0foHcTW32UkEwtpg==
-----END CERTIFICATE-----

Inleiding

Bij het inloggen wordt gebruik gemaakt van een door Shifft geleverde private en public key. Ben je nog niet in het bezit van deze keys, vraag ze dan aan bij Shifft. De private en public keys worden gebruikt bij het inloggen en beveiligen van berichten.

Het inlogproces verloopt in twee stappen; allereerst wordt er een challenge aangevraagd. Hierbij doe je een verzoek aan de API, waarbij je gebruik maakt van de public key. Vervolgens wordt de challenge gesigneerd met de private key en verstuurd naar de API. Dit levert een Auth token op, welke een levensduur van 5 minuten heeft. Een volledige beschrijving van dit proces vind je op de pagina Login.

Public key

In de documentatie wordt regelmatig gesproken over een public key. Een voorbeeld van een public key, welke gebruikt wordt om de challenge te signeren vind je in Voorbeeld 1A.

Encryptie

Voorbeeld 1B

{
  number: 2,
  parts:
  {
    part1: "GERg34tt2ntj/....",
    part2: "btr4g4tg22tt+...."
  }
}

De encryptie verloopt via het, door Shifft geleverde, sleutelpaar. Alle antwoorden vanuit de API, met uitzondering van foutmeldingen, zullen versleuteld worden met behulp van de public key. Deze kunnen worden gedecodeerd met behulp van de private key. De versleutelde antwoorden zijn base64 gecodeerd.

Indien een antwoord te groot is, zal deze in meerdere stukken geknipt worden en zal ieder stuk afzonderlijk versleuteld worden. Alle stukken bij elkaar zullen de uiteindelijke JSON string vormen. De afzonderlijke stukken zullen base64 gecodeerd worden en als JSON geretourneerd worden, waarbij aangegeven wordt uit hoeveel stukken de data bestaat. Voorbeeld 1B laat dit zien (hierin zijn de gecodeerde delen verkort weergeven).

Login

Voorbeeld 1C

POST https://p4.energyshifft.com/login/start
AuthorizationKey: key="<base64_public_key>"

Challenge aanvragen

Om het inlogproces te starten, stuur je een POST verzoek naar https://p4.energyshifft.com/login/start. Stel hierbij de Authorization header in op: key="{base64_public_key}", waarbij {base64_public_key} de base64 gecodeerde public key is. Dit betekent dat over de string, zoals beschreven onder public key, nog een base64 encoding gehaald moet worden voordat deze wordt meegestuurd.

Bij een succesvol verzoek zal je als antwoord de auth challenge ontvangen. De auth challenge bestaat uit een random gegeneerde string welke is versleuteld. Het antwoord zal de status code 200 mee krijgen en de challenge zal in de response body zitten. Voorbeeld 1C laat zien hoe de body er uit ziet.:

Voorbeeld 1D

{
  Challenge: "<versleutelde_string>"
}

Challenge errors

Naast de algemene foutmelding, is het mogelijk dat je een van de volgende foutmeldingen ontvangt bij het starten van de inlogprocedure (challenge).

HTTP status code Shifft error code Omschrijving
400 1 De AuthorizationKey header ontbreekt, hierdoor kan de identiteit van de aanvrager niet gecontroleerd worden.
400 2 De public key ontbreekt, hierdoor kan de identiteit van de aanvrager niet gecontroleerd worden.
401 1 De public key is onbekend.

Auth token aanvragen

Voorbeeld 1E

POST https://p4.energyshifft.com/login/response
AuthorizationKey: key="<base64_publickey>", response="<base64_private_signed_challenge_string>"

Nadat je het antwoord van de challenge hebt ontvangen, zal deze gesigneerd moeten worden met de private key. Vervolgens dient deze base64 gecodeerd te worden en, samen met de public key, in de Authorization header naar het end point https://p4.energyshifft.com/login/response verstuurd moeten worden. Voorbeeld 1E laat dit zien.

Voorbeeld 1F

{
  token: "<string>"
}

Auth token aanvraag fouten

Naast de algemene foutmeldingen, is het mogelijk dat je een van de volgende foutmeldingen ontvangt bij het aanvragen van het auth token.

HTTP status code Shifft error code Omschrijving
400 1 De AuthorizationKey header ontbreekt, hierdoor kan de identiteit van de aanvrager niet gecontroleerd worden.
400 2 De public key mist in het bericht, hierdoor kan de identiteit van de aanvrager niet gecontroleerd worden.
401 1 De public key is onbekend.
401 2 Er is geen response meegestuurd.
401 3 De response komt niet overeen met de auth challenge.

Auth token meesturen

Voorbeeld 1G

AuthorizationToken: token="<string>"

Bij alle API verzoeken (met uitzondering van het inlogproces) dient het auth token meegestuurd te worden. Dit gebeurt in de Authorization header, voorbeeld 1G laat dit zien.

Auth token meesturen errors

Naast de algemene foutmeldingen, is het mogelijk dat je een van de volgende foutmeldingen ontvangt bij het meesturen van het Auth token.

HTTP status code Shifft error code Omschrijving
400 3 Het Auth token is niet meegestuurd, hierdoor kan de identiteit van de aanvrager niet gecontroleerd worden.
401 d Het Auth token is onjuist of verlopen. Er dient een nieuwe Auth token te worden aangevraagd om verder te gaan.

Gebruikers

Inleiding

Gebruikers vormen de kern van de API. Zodra er een gebruiker toegevoegd is, begint het proces om de energie data op te halen. Het ophalen van data kan in eerste instantie enkele dagen in beslag nemen. Data van bestaande gebruikers heeft altijd een vertraging van één á twee dagen (is dus niet real-time).

Gebruiker toevoegen

Om een gebruiker toe te voegen stuur je een POST verzoek naar https://p4.energyshifft.com/persons. Voorzie dit verzoek van een JSON object met de gebruikersdata in de request body. De JSON moet de volgende parameters bevatten:

name <String>

Name is een string die de naam van de gebruiker bevat.

postal <String>

Postal is een string die de postcode van een gebruiker bevat. De postcode mag met of zonder spatie tussen de cijfers en letters geschreven worden. Dus onderstaande schrijfwijzen zijn dus beide correct:

number <Int>

Number is een integer met het huisnummer van de gebruiker.

additional <String>

Additional is een optionele string. Diverse huizen in Nederland hebben naast een huisnummer ook een huisnummertoevoeging. Indien dit het geval is moet deze meegeleverd worden als waarde van deze parameter.

accept <DateTime>

Shifft dient als ODA aan te geven vanaf wanneer wij data mogen ophalen. Dit mag vanaf het moment dat de gebruiker daarvoor akkoord heeft gegeven. Dit is vaak de datum van registratie en zal dus meestal het huidige tijdstip zijn. Dit tijdstip stuurt u mee als waarde van deze parameter. De waarde dient als volgt opgemaakt te zijn: yyyy-mm-dd hh:ii.

eanElek

EanElek is een optionele waarde met hierin de ean code voor elektriciteit die uitgelezen dient te worden. Er zit hier nog wel een controle op om te controleren of de ean echt bij de aansluiting hoort

eanGas

eanGas is een optionele waarde met hierin de ean code voor gas die uitgelezen dient te worden. Er zit hier nog wel een controle op om te controleren of de ean echt bij de aansluiting hoort

code <String>

Dit is de code van de slimme meter. Deze code vindt je bij de streepjes code op de slimme meter.

Voorbeeld 2A

POST https://p4.energyshifft.com/persons
AuthorizationToken: token="<string>"

{
  name: "Jan Jansen",
  postal: "1234ab",
  number: 1,
  additional: "abs",
  accept: "2014-08-14 15:19",
  eanElek: 871000000000000000,
  eanGas: 871000000000000000,
  code: "ZBEV1241523434t12312"
}

Voorbeeld 2A toont een voorbeeld van het verzoek (inclusief de optionele additional parameter).

Voorbeeld 2B

{
  personId: 1 
}

Bij een succesvol verzoek zal de statuscode 201 in het antwoord zijn en zal de body het user id personId bevatten. Voorbeeld 2B laat dit zien.

Zodra een gebruiker aangemaakt is, is deze klaargezet om meegenomen te worden in het klantmandaatoverzicht dat door Shifft zo spoedig mogelijk naar de regionale netbeheerder wordt verstuurd.

Foutmeldingen

Naast de algemene foutmeldingen en de auth token foutmeldingen, is het mogelijk dat je een van de volgende foutmeldingen ontvangt bij het aanmaken van gebruikers.

HTTP status code Shifft error code Omschrijving
400 4 Het adres is niet gevonden.
400 5 Er is iets fout gegaan bij het ophalen van de eans.
400 7 Niet alle data is juist ingevuld.
400 8 Er zijn meerdere EAN codes voor elektriciteit en/of gas.
400 9 De gevonden EANS voor elektriciteit en/of gas is incorrect.

Adresgegevens van gebruikers opvragen

Voorbeeld 2C

[
  {
    Id: 1,
    name: "Piet Puk",
    postal: "1234ab",
    number: 1,
    additional: "abs",
    accept: "2014-08-14 15:19",
    eanElektricity: "871689290500689394",
    eanGas: "871689290501503675",
    code: "ZBEV1241523434t12312"
  },
  {
    Id: 2,
    name: "Karel Jansen",
    postal: "1234 ab",
    number: 5,
    accept: "2014-08-14 15:15",
    eanElektricity: "871689290500689394",
    eanGas: "871689290501503675",
    code: "ZBEV1241523434t12312"
  }
]

De adresgegevens en naam van alle gebruikers kunnen via een GET verzoek aan het endpoint https://p4.energyshifft.com/persons opgevraagd worden. Als antwoord ontvang je een JSON array met objecten met daarin de gegevens van de gebruiker. Voorbeeld 2C laat dit zien.

Foutmeldingen

Naast de algemene foutmeldingen en de auth token foutmeldingen komen in dit onderdeel geen andere foutmeldingen voor.

Adresgegevens van een gebruiker opvragen

Voorbeeld 2E

{
  Id: 1,
  name: "Piet Puk",
  postal: "1234ab",
  number: 1,
  additional: "abs",
  accept: "2014-08-14 15:19",
  eanElektricity: "871689290500689394",
  eanGas: "871689290501503675",
  code: "ZBEV1241523434t12312"
}

De adresgegevens en naam van een gebruiker kunnen via een GET verzoek naar het endpoint https://p4.energyshifft.com/persons/{id} opgevraagd worden. {id} staat voor het gebruikers id, zoals ontvangen bij het toevoegen van de gebruiker. Als antwoord ontvang je een JSON object met de daarin de gegevens van de gebruiker. Voorbeeld 2E laat dit zien.

Foutmeldingen

Naast de algemene foutmeldingen en de auth token foutmeldingen, is het mogelijk dat je een van de volgende foutmeldingen ontvangt bij het opvragen van gebruikersgegevens.

HTTP status code Shifft error code Omschrijving
404 2 pId is geen nummer.

Gebruiker aanpassen

Het aanpassen van de gegevens van een gebruiker verloopt via een PUT verzoek naar het endpoint https://p4.energyshifft.com/persons/{id}. Hierbij is {id} het gebruikers id, zoals ontvangen bij het toevoegen van een gebruiker.

Voor het aanpassen van de gegevens van een gebruiker stuur je de gebruikersdata nogmaals. Stuur hierbij alleen de velden die gewijzigd dienen te worden mee. De JSON is gelijk aan die bij het toevoegen van een gebruiker, met als verschil dat niet alle data meegestuurd hoeft te worden.

Bij succesvolle uitvoering ontvang je de nieuwe gegevens van de gebruiker retour. Het antwoord ziet er hetzelfde uit als bij een GET verzoek.

Foutmeldingen

Naast de algemene foutmeldingen en de auth token foutmeldingen, is het mogelijk dat je een van de volgende foutmeldingen ontvangt bij het aanpassen van adresgegevens.

HTTP status code Shifft error code Omschrijving
400 4 Het adres is niet gevonden.
400 5 Er is iets fout gegaan bij het ophalen van de eans.
400 7 Niet alle data is juist ingevuld.
400 8 Er zijn meerdere EAN codes voor elektriciteit en/of gas.
400 2 pId is geen nummer.

Gebruiker verwijderen

Een gebruiker kan uit het systeem verwijderd worden door een DELETE verzoek te sturen naar het endpoint https://p4.energyshifft.com/persons/{id}. Hierbij is {id} het gebruikers id, zoals ontvangen bij het toevoegen van de gebruiker.

Als antwoord stuurt deze functie alleen een http status code terug. Indien deze code gelijk is aan 204 betekent dit dat de gebruiker is verwijderd.

Foutmeldingen

Naast de algemene foutmeldingen en de auth token foutmeldingen, is het mogelijk dat je een van de volgende foutmeldingen ontvangt bij het aanpassen van adresgegevens.

HTTP status code Shifft error code Omschrijving
404 2 pId is geen nummer.

Energiedata

Inleiding

Energiedata wordt opgevraagd door een verzoek te sturen naar het end point https://p4.energyshifft.com/persons/{pId}/energyData/{params}. Als antwoord ontvang je een JSON array met per interval de timestamp, meterstand elektriciteit, meterstand teruglevering en de meterstand gas. Een dag bij energiedata loopt van 00:00 tot en met 23:45 uur. {pId} is het gebruikers id, zoals ontvangen bij het toevoegen van de gebruiker. {params} zijn de parameters waarmee gekozen kan worden welke data er opgevraagd wordt.

Timestamp

Dit is het tijdstip dat door de meter aan de meterstanden gekoppeld is in het formaat yyyy/mm/dd hh:ii.

Meterstand elektriciteit

Bevat de meterstand van de elektriciteit in Wh. De meterstand staat voor het verbruik van alle elektriciteit die vanaf het net door de meter naar binnen komt. Indien er sprake is van opwek (van bijvoorbeeld zonnepanelen), dan staat het op de meter aangegeven verbruik niet gelijk aan het totaalverbruik van de gebruiker. (Deze verbruikt immers ook opgewekte energie). Het verbruik van de elektriciteit wordt per kwartier getoond.

Meterstand teruglevering

Indien een gebruiker elektriciteit opwekt en niet alle elektriciteit direct verbruikt, wordt dit aan het elektriciteitsnet gegeven. Dit wordt teruglevering genoemd. De meterstand van de teruglevering is de stand in Wh van de meter die dit meet. Teruglevering wordt per kwartier getoond.

Meterstand gas

Toont de meterstand van de gasmeter in m3. Gas wordt per uur getoond.

Parameters verzoek

Parameters

Voor het opvragen van energiedata zijn vier parameters beschikbaar. De parameters dienen achter de url geplaatst te worden. Iedere parameter is optioneel en kan in willekeurige volgorde worden meegegeven. De parameters moeten op de volgende wijze toegevoegd worden: naam|waarde, waarbij de parameters gescheiden dienen te worden door een slash "/".

interval <quarter, hour, day, months>

Dit is een enum die aangeeft hoeveel tijd er tussen iedere meterstand zit. De meterstanden zullen oplopend vanaf begin van het tijdsinterval tot en met het tijdstip van aanvraag getoond worden. Dit betekent dat bij een interval van een dag de eerste meterstand die van 00:00 uur zal zijn. Wil je data van een andere periode opvragen, gebruik dan de parameters start en end.

start <yyyymmddhhii>

Start is een optionele parameter. Indien deze parameter is ingesteld, wordt de data vanaf dit tijdstip getoond. De parameters Interval en/of End bepalen hoeveel data er wordt getoond. Afhankelijk van het interval kunnen datum en tijd automatisch worden afgerond om zo aan te sluiten op het gekozen interval.

end <yyyymmddhhii>

End is een optionele parameter. Indien deze parameter is ingesteld, wordt de data tot aan dit tijdstip getoond. De parameters Interval en/of End bepalen hoeveel data er wordt getoond. Afhankelijk van het interval kunnen datum en tijd automatisch worden afgerond om zo aan te sluiten op het gekozen interval.

order <asc, desc>

Order geeft aan in welke volgorde de resultaten getoond moeten worden. Deze parameter kan een van deze twee waardes bevatten:

Gebruik parameters

Zoals eerder aangegeven, bepaalt het gebruik van de parameters welke resultaten worden teruggegeven. Hieronder vind je een overzicht van de invloed van parameters interval, start en end op de resultaten.

Indien er (nog) geen data beschikbaar is, krijg je ook geen resultaten terug. Is er slechts een gedeelte beschikbaar, dan wordt dit getoond. Zie het onderdeel Tips & tricks voor meer handige weetjes.

Energiedata dag

Inleiding

Energiedata dag wordt opgevraagd door een verzoek te sturen naar het end point persons/{pId}/energyDataDag/{params}. Als antwoord ontvang je een JSON array met de dagstand voor de opgevraagde dag(en). Een dagstand bevat de standen van ieder telraam om 00:00 uur van de opgevraagde dag. (Voor elektriciteit zijn er vier telramen: T1 voor het verbruik tijdens piekuren, T2 voor het verbruik tijdens de daluren, T3 voor de teruglevering tijdens piekuren en T4 voor de teruglevering tijdens daluren. Voor gas is dit alleen het verbruik (geen dal/piek en geen teruglevering)). De waarde {pId} in het end point staat voor de gebruikers id, zoals ontvangen bij het toevoegen van de gebruiker. {params} zijn de parameters waarmee bepaald kan worden welke data er opgevraagd wordt.

In het JSON array dat je terug krijgt vind je de volgende waardes:

timestamp

De dag waarvan je de data wilt ontvangen in het yyyymmdd formaat.

elektricity_low

De meterstand voor de elektriciteitslevering tijdens het laag tarief in kWh.

elektricity_high

De meterstand voor de elektriciteit levering tijdens het hoog tarief in kWh.

gas

De meterstand voor gas levering in m3.

production_low

De meterstand voor de elektriciteit teruglevering tijdens het laag tarief in kWh.

production_high

De meterstand voor de elektriciteit teruglevering tijdens het hoog tarief in kWh.

Parameters verzoek

Parameters

Voor het opvragen van energiedata dag zijn vier parameters beschikbaar. De parameters dienen achter de url geplaatst te worden. Iedere parameter is optioneel en kan in iedere volgorde worden meegegeven. De parameters moeten op de volgende wijze toegevoegd worden: naam|waarde, waarbij de parameters gescheiden dienen te worden door een slash "/".

interval <day, months>

Dit is een enum die aangeeft hoeveel tijd er tussen iedere meterstand zit. De meterstanden zullen oplopend vanaf het begin van het tijdsinterval tot en met het tijdstip van aanvraag getoond worden. Dit betekent dat bij een interval van een dag de eerste meterstand die van 00:00 uur zal zijn. Wil je data van een andere periode opvragen, gebruik dan de parameters 'start' en 'end'.

start <yyyymmddhhii>

Start is een optionele parameter. Indien deze parameter is ingesteld, wordt de data vanaf dit tijdstip getoond. De parameters Interval en/of End bepalen hoeveel data er wordt getoond. Afhankelijk van het interval kunnen datum en tijd automatisch worden afgerond om zo aan te sluiten op het gekozen interval.

end <yyyymmddhhii>

End is een optionele parameter. Indien deze parameter is ingesteld, wordt de data tot aan dit tijdstip getoond. De parameters Interval en/of End bepalen hoeveel data er wordt getoond. Afhankelijk van het interval kunnen datum en tijd automatisch worden afgerond om zo aan te sluiten op het gekozen interval.

order <asc, desc>

Order geeft aan in welke volgorde de resultaten getoond moeten worden. Deze parameter kan een van deze twee waardes bevatten:

Gebruik parameters

Zoals eerder aangegeven, bepaalt het gebruik van de parameters welke resultaten worden teruggegeven. Hieronder vind je een overzicht van de invloed van parameters interval, start en end op de resultaten.

Indien er (nog) geen data beschikbaar is, krijg je ook geen resultaten terug. Is er slechts een gedeelte beschikbaar, dan wordt dit getoond. Zie het onderdeel Tips & tricks voor meer handige weetjes.

Storingen

Voorbeeld 3

[
    {
        id:1,
        errors: 
        [
            {
                'ean':"871689290500689394",
                'type':"gas",
                'start':"2019-11-01",
                'end':"2019-11-12",
                'current':"opgelost",
                'history':
                [
                    {
                        'date':"2019-11-12",
                        'state':"opgelost"
                    },
                    {
                        'date':"2019-11-05",
                        'state':"Afspraak met klant gemaakt"
                    },
                    {
                        'date':"2019-11-01",
                        'state':"storing gemeld"
                    }
                ]
            },
            {
                'ean':"871689290500689394",
                'type':"gas",
                'start':"2019-11-01",
                'current':"Afspraak met klant gemaakt",
                'history':
                [
                    {
                        'date':"2019-11-05",
                        'state':"Afspraak met klant gemaakt"
                    },
                    {
                        'date':"2019-11-01",
                        'state':"storing gemeld"
                    }
                ]
            }
        ]
    }
]

Storingen opvragen

De huidige storingen kunnen met een get verzoek naar het endpoint https://p4.energyshifft.com/errors/current opgevraagd worden. Als antwoord ontvang je een JSON array met objecten met daarin per gebruiker de huidige actieve storingen. Voorbeeld 3 laat dit zien.

Foutmeldingen

Naast de algemene foutmeldingen en de auth token foutmeldingen komen in dit onderdeel geen andere foutmeldingen voor.

Foutmeldingen

Inleiding

Naast de algemene foutmeldingen vind je hier ook foutcodes voor specifieke endpoints.

Algemene foutmeldingen

Foutcodes

Bij een fout kan de API verschillende foutmeldingen geven. Hieronder vind je een aantal generieke foutmeldingen:

HTTP status code Shifft error code Omschrijving
301 - De API is via HTTP aangeroepen, in plaats van HTTPS.
404 1 Het opgevraagde 'end point' is niet bekend.
405 - De HTTP methode is niet toegestaan op het 'end point'.
500 - Er heeft zich een onbekende fout voorgedaan.

Een overzicht van alle foutmeldingen is te vinden op de statuscodes pagina.

Gebruiker

Voorbeeld 5

[
  {
    ean: "871689290500689394",
    type: "gas",
    start: "2019-11-01",
    end: "2019-11-12",
    current: "opgelost",
    history:
    [
      {
        date: "2019-11-12",
        state: "opgelost"
      },
      {
        date: "2019-11-05",
        state: "Afspraak met klant gemaakt"
      },
      {
        date: "2019-11-01",
        state: "storing gemeld"
      }
    ]
  },
  {
    ean: "871689290500689394",
    type: "gas",
    start: "2019-11-01",
    current: "Afspraak met klant gemaakt",
    history:
    [
      {
        date: "2019-11-05",
        state: "Afspraak met klant gemaakt"
      },
      {
        date: "2019-11-01",
        state: "storing gemeld"
      }
    ]
  }
]

Foutmeldingen gebruikers opvragen

De foutmeldingen voor een gebruiker kunnen met een get verzoek naar het endpoint https://p4.energyshifft.com/errors/{pId} opgevraagd worden, waarbij pId de person id is. Als antwoord ontvang je een JSON array met objecten met daarin de foutmeldingen. Voorbeeld 5 laat dit zien.

Foutmeldingen

Naast de algemene foutmeldingen en de auth token foutmeldingen komen in dit onderdeel geen andere foutmeldingen voor.

Platform

Inleiding

Voorbeeld 6A

POST https://p4.energyshifft.com/persons/1/platform/test%40shifft.com
AuthorizationToken: token="brbresui4g2rfd"

Met het platform endpoint kan er een aanmeldlink aangevraagd worden voor het energieplatform. Om de link aan te vragen dien je een POST verzoek te sturen naar het end point https://p4.energyshifft.com/persons/{pId}/platform/{email}. Hier staat {pId} voor het id van de gebruiker, zoals ontvangen bij het toevoegen van de gebruiker. {email} staat voor het e-mailadres van de gebruiker. Dit e-mail adres wordt bij de aanmelding op het platform gebruikt (en automatisch ingevuld in het aanmeldformulier dat de gebruiker te zien krijgt). Voorbeeld 6A laat dit zien.

Als het verzoek succesvol afgehandeld kan worden, zal er een aanmeldlink teruggestuurd worden.

Voorbeeld 6B

{
  link: "https://energyshifft.com/aanmelden_123456.html"
}

Hierbij is energyshifft.com de url van het platform. Voorbeeld 6B laat dit zien.

Foutmeldingen

Naast de algemene foutmeldingen en de auth token foutmeldingen, is het mogelijk dat je een van de volgende foutmeldingen ontvangt bij het aanmaken van gebruikers.

HTTP status code Shifft error code Omschrijving
400 7 Niet alle data is juist ingevuld.
400 8 Er is geen platform beschikbaar.

Voorbeelden

Er zijn PHP voorbeelden beschikbaar voor diverse onderdelen. Gebruik het menu aan de linkerzijde (items onder 'Voorbeelden') om de voorbeelden te bekijken.

Login

Voorbeeld 7A

<?php
  //Lees het certificaat in, $keyStore is het pad(inclusief de bestandsnaam) naar het door Shifft geleverde .p12 bestand en $keyPhrase is het bijbehorende wachtwoord.
  $pkcs12 = file_get_contents($keyStore);
  openssl_pkcs12_read($pkcs12, $key, $keyPhrase);

  /*haal de public key uit het certificaat in het volgende format:
  ----- BEGIN PUBLIC KEY ------
  {String die de public key representeert}
  ----- END PUBLIC KEY  ------ */
  $pubKey = $key['cert'];
  $pubEncoded = base64_encode($pubKey);//haal de base64 encoding over de string

  //maak het request naar de server met behulp van curl
  $base = 'https://p4.energyshifft.com/';
  $headers = array('AuthorizationKey: key='.$pubEncoded); 
  $ch = curl_init(); 
  curl_setopt($ch, CURLOPT_URL, $base.'login/start');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
  curl_setopt($ch, CURLOPT_VERBOSE, 1);
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); 
  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
  $output = curl_exec($ch);
  curl_close($ch);

  //decodeer de data met behulp van de private key
  $data = '';
  openssl_private_decrypt(base64_decode($output), $data, $key['pkey']);

  //signeer de challenge
  $data = json_decode($data);
  $sign = '';
  openssl_sign($data->challenge, $sign, $key['pkey']);
  $sign = base64_encode($sign);

  //stuur het antwoord op de challenge naar de server om de auth token te krijgen.
  $headers = array('AuthorizationKey: key='.$pubEncoded.', response="'.$sign.'"');
  $ch = curl_init(); 
  curl_setopt($ch, CURLOPT_URL, $base.'login/response'); 
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
  curl_setopt($ch, CURLOPT_VERBOSE, 1);
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); 
  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
  $output = curl_exec($ch);
  curl_close($ch);

  //decodeer de data met behulp van de private key en sla het auth token op in de $token variabele.
  $data = '';
  openssl_private_decrypt(base64_decode($output), $data, $key['pkey']);
  $data = json_decode($data);
  $token = $data->token;
?>

Dit is een simpel voorbeeld voor de challenge met de server. Voorbeeld 7A laat dit zien.

Gebruiker toevoegen

Voorbeeld 7B

<?php
  //Creëer een JSON object met de gebruikersdata
  $userData = array('name'=>'Terry van Leeuwen', 'postal'=>'3042EC', 'number'=>27, 'additional'=>'D', 'accept'=>date('Y-m-d H:i'));
  $user = json_encode($userData);

  //Stuur het verzoek naar de server
  $headers = array('AuthorizationToken: token="'.$token.'"',
            'Content-Type: application/json',                                                                                
            'Content-Length: ' . strlen($user));
  $ch = curl_init(); 
  curl_setopt($ch, CURLOPT_URL, $base.'persons'); 
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
  curl_setopt($ch, CURLOPT_VERBOSE, 1);
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");                                                    
  curl_setopt($ch, CURLOPT_POSTFIELDS, $user);
  $output = curl_exec($ch);
  curl_close($ch);

  //Decodeer de data en haal het id uit de json
  $data = '';
  openssl_private_decrypt(base64_decode($output), $data, $key['pkey']);
  $data = json_decode($data);
  $id = $data->personId;
?>

Voorbeeld 7B is een voorbeeld voor het toevoegen van een gebruiker, zoals aangegeven in gebruiker toevoegen. Het voorbeeld gaat ervan uit dat hiervoor het login voorbeeld uitgevoerd is en gebruikt de variabelen die in het login voorbeeld zijn aangemaakt.

Energiedata opvragen

Voorbeeld 7C

<?php 
  //Stuur het verzoek naar de server
  $headers = array('AuthorizationToken: token="'.$token.'"',
            'Content-Type: application/json');
  $ch = curl_init(); 
  curl_setopt($ch, CURLOPT_URL, $base.'persons/1/energyData/start|20140913/end|20140919/Order|desc/interval|day');//Stel in welke data er opgevraagd wordt.
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
  curl_setopt($ch, CURLOPT_VERBOSE, 1);
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
  $output = curl_exec($ch);
  curl_close($ch);
  //Indien de output een JSON string is, zullen de stukken afzonderlijk gedecodeerd worden.
  if(substr($output, 0, 1) == '{')
  {
    $data = json_decode($output);
    //Loop over de verschillende stukken en decodeer ze.
    $jsonString = '';
    for($i = 1; $i <= $data->number; $i++)
    {
      $element = 'part'.$i;
      openssl_private_decrypt(base64_decode($data->parts->$element), $dataPart, $key['pkey']);
      $jsonString .= $dataPart;
    }
  }
  //Anders bestaat het antwoord uit een gecodeerde string
  else
  {
    openssl_private_decrypt(base64_decode($output), $jsonString, $key['pkey']);
  }
?>

Voorbeeld 7C is een voorbeeld voor het opvragen van energiedata, zoals aangegeven in energiedata. Het voorbeeld gaat ervan uit dat hiervoor het login voorbeeld uitgevoerd is en gebruikt de variabelen die in het login voorbeeld zijn aangemaakt.

Statuscodes

HTTP codes

Hieronder volgen alle HTTP status codes waarvan gebruik van gemaakt wordt, met daarachter de sub-code en toelichting.

HTTP status code Shifft error code Omschrijving End points
200 - Het verzoek is succesvol afgehandeld. login/start, login/response, persons, persons/{pId}, persons/{pId}/energyData/{params}, persons/{pId}/platform/{email}
201 - De gebruiker is aangemaakt. persons
204 - De gebruiker is verwijderd. persons/{pId}
206 - Niet alle energiedata is beschikbaar. persons/{pId}/energyData/{params}
301 - De API werd aangeroepen op een HTTP verbinding, in plaats van een HTTPS verbinding. login/start, login/response, persons, persons/{pId}, persons/{pId}/energyData/{params}, persons/{pId}/platform/{email}
400 1 De autorization header ontbreekt login/start, login/response, persons, persons/{pId}, persons/{pId}/energyData/{params}, persons/{pId}/platform/{email}
400 2 De public key ontbreekt login/start, login/response
400 3 Het auth token ontbreekt. persons, persons/{pId}, persons/{pId}/energyData/{params}, persons/{pId}/platform/{email}
400 4 Het adres is niet gevonden. persons, persons/{pId}
400 5 De startdatum is recenter dan de einddatum. persons/{pId}/energyData/{params}
400 6 Het opgegeven interval is niet bekend. persons/{pId}/energyData/{params}
400 7 Niet alle data is juist ingevuld. persons/, persons/{pId}
400 8 Er zijn meerdere EAN codes voor elektriciteit en/of gas. persons/, persons/{pId}
400 9 Er is een verkeerde ean voor elektriciteit en/of gas doorgeven. persons/, persons/{pId}
401 1 De public key is onbekend. login/start, login/response
401 2 De response op de challenge ontbreekt. login/response
401 3 De response op de challenge is niet correct. login/response
401 4 Het auth token is niet correct of verlopen. persons, persons/{pId}, persons/{pId}/energyData/{params}, persons/{pId}/platform/{email}
401 5 De meter code is niet correct. persons/{pId}/energyData/{params}
404 1 Het endpoint is onbekend. login/start, login/response, persons, persons/{pId}, persons/{pId}/energyData/{params}, persons/{pId}/platform/{email}
404 2 Het pId moet een getal zijn. persons/{pId}, persons/{pId}/energyData/{params}, persons/{pId}/platform/{email}
404 3 De energiedata is (nog) niet beschikbaar. persons/{pId}/energyData/{params}
404 4 Er hangt nog geen slimme meter. persons/{pId}/energyData/{params}
404 5 De slimme meter staat uit. persons/{pId}/energyData/{params}
405 - De HTTP methode is niet toegestaan. login/start, login/response, persons, persons/{pId}, persons/{pId}/energyData/{params}, persons/{pId}/platform/{email}
500 - Er is een onbekende fout opgetreden. login/start, login/response, persons, persons/{pId}, persons/{pId}/energyData/{params}, persons/{pId}/platform/{email}

Codes voor het ontbreken van data

Wanneer er geen data beschikbaar is, of er data ontbreekt, worden een of meerdere van de onderstaande meldingen meegestuurd.

Error code Omschrijving
0 De reden waarom er geen data beschikbaar is, is onbekend.
1 Er gaat iets mis aan de kant van Shifft. Wij zijn hier druk mee bezig.
2 Het klantmandaat is nog niet verwerkt of de beschikbare data is van voor de acceptatiedatum.
3 De netbeheerder geeft aan dat er geen slimme meter aanwezig is op het opgegeven adres.
4 De opgegeven datum ligt te ver in het verleden.
5 De opgegeven datum ligt in de toekomst.
6 De data is momenteel niet beschikbaar, dit komt mogelijk in de toekomst nog.
7 Er is een technische storing bij de meter of netbeheerder.
8 De meter staat administratief uit, hierdoor geeft deze geen data door. De gebruiker zal aan zijn/haar netbeheerder door moeten geven dat de meter aangezet moet worden.
9 Er is (nog) geen data ontvangen.
10 De contractant is gewijzigd, dit kan duiden op een verhuizing.
11 Er is een grootschallige storing binnen het netwerk, de netbeheerders weten hiervan en zijn bezig met het oplossen.

Tips & Tricks

Inleiding

In de communicatie met de API kan het wel eens voorkomen dat er onverwachte waardes worden geretourneerd, of zich andere onverwachte situaties voordoen. Dit is helaas niet altijd te voorkomen, omdat Shifft ook afhankelijk is van de (consistentie van) data uit de slimme meters. In dit hoofdstuk worden een aantal van dit situaties besproken, zodat je inzage krijgt in wat je kunt verwachten.

Wijziging in eenheid <kWh/Wh>

De meterstanden van de elektriciteit worden soms (tijdelijk en zonder verklaarbare reden) in een keer doorgegeven in een andere eenheid. Dit gebeurt met name bij Enexis.

Klantmandaat ongeldig

Bij een 'move in' van een energieleverancier wordt het mandaat om de meter uit te lezen soms onterecht ongeldig verklaard, waardoor Shifft de slimme meter niet meer uit kan lezen. Dit gebeurt met name bij Stedin.

Afronding meterstanden

Shifft rondt de meterstanden af op zeven decimalen. Dit gebeurt omdat niet alle slimme meters evenveel decimalen meesturen.

Nieuwe meterstand lager dan/gelijk aan vorige meterstand

Het kan voorkomen dat een nieuwe meterstand gelijk is aan de vorige, of zelfs lager is dan de vorige meterstand. In dat geval is er meestal sprake van het 'klokje rond gaan' van de teller. Deze heeft dan zijn maximale waarde bereikt en start (meestal) weer op 0.

Energiedata dag en Energiedata

In theorie zouden de meterstanden van Energiedata dag en Energiedata op hetzelfde moment gelijk moeten zijn. Helaas is dat niet het geval (er is een kleine afwijking). Voor het ophalen van de data bij de slimme meter worden twee verschillende verzoeken gestuurd en deze geven ook beide andere waardes terug. Hier heeft Shifft geen invloed op. Het is daarom belangrijk de waardes van beide verzoeken niet door elkaar te gebruiken.

Contact

Aanvragen

Voor meer informatie over de API of de mogelijkheden van een online energieplatform kun je contact opnemen met stefan.versluis@shifft.com

Technische ondersteuning

Indien je problemen ondervindt met de implementatie van deze API, stuur dan je vraag naar: terry.vanleeuwen@shifft.com