Hulp bij Partners in Energie notification en REST API

Notificatie API

Ten eerste is er de notificatie API. EDSN heeft een AMQP 1.0 broker waarmee je je kunt abonneren op gebeurtenissen die plaatsvinden op het Partners in Energie platform. Op deze manier kan de applicatie automatisch op de hoogte worden gebracht wanneer er iets gebeurt op het Partners in Energie platform.

REST API

Ten tweede is er een REST-gebaseerde web API waarmee je synchroon kunt communiceren met het Partners in Energie platform. Voor nu is slechts een beperkte set functionaliteiten beschikbaar; notificaties worden alleen verzonden wanneer een ticket of een opmerking wordt aangemaakt op het Partners in Energie platform, en de REST API staat alleen toe om informatie over deze tickets en opmerkingen op te halen.

Om verbinding te maken met beide API’s moet de organisatie toegang hebben toe Partners in Energie. Is dit nog niet het geval? Neem dan contact op met onze servicedesk via [email protected].

Authenticatie

Authenticatie voor beide API's werkt met het OAuth-protocol. Om een toegangstoken te verkrijgen, moeten de volgende stappen worden uitgevoerd:

1. Maak een OAuth Service account aan.
2. Maak een client assertion.
3. Vraag een toegangstoken aan.

Een OAuth Service Account aanmaken

Een service account kan handmatig worden aangemaakt via de DVT UI.

Acceptance: https://portal.idp.acc.cmf.energysector.nl/gegevens

Production: https://portal.idp.cmf.energysector.nl/gegevens

Onder het gedeelte "Service Accounts" kan een service account worden aangemaakt. Zorg ervoor dat je het service account de juiste rechten geeft en selecteer het type "OAuth". Zorg ervoor dat je de privésleutel van het service account veilig opslaat, omdat deze nodig is om de client assertion te genereren.

Onder “Applicatierollen” zoek je naar “AMQP” en voeg je de applicatierol 'AMQP {env} consumer role to access pie for {organizationName}' toe.

Client Assertion

De client assertion is een JWT die wordt gebruikt om de client te verifiëren bij de Identity Provider. Het is een JWT ondertekend met de privésleutel van het service account. De client assertion moet de volgende claims bevatten:

• iss (issuer): De client ID van het service account, die kan worden opgehaald van de service account pagina.
• sub (subject): De client ID van het service account.
• aud (audience): De toegangstoken endpoint: https://idp.cmf.energysector.nl/am/oauth2/access_token
• exp (expiration): De vervaltijd van de client assertion. Let op dat deze waarde betrekking heeft op de client assertion zelf, niet op het toegangstoken. Vijf minuten is een goede waarde.
• iat (issued at): Het tijdstip waarop de client assertion is uitgegeven.
• jti (JWT ID): Een unieke identificatie voor de client assertion, die kan worden gegenereerd met een UUID-generator.

Deze claims moeten worden ondertekend met de privésleutel van het service account die is verkregen toen het service account werd aangemaakt. Deze ondertekende JWT is de client assertion.

Een toegangstoken aanvragen

Om een toegangstoken aan te vragen, moet een POST-verzoek worden verzonden naar de toegangstoken endpoint. De toegangstoken endpoint is:

Acceptance: https://acc.idp.cmf.energysector.nl/am/oauth2/access_token

Production: https://idp.cmf.energysector.nl/am/oauth2/access_token

De aanvraag moet een URL-gecodeerd formulier bevatten met de volgende parameters:

• grant_type: client_credentials
• client_id: De client ID van het service account, op te halen van de service account pagina.
• client_assertion_type: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
• scope: openid roles
• client_assertion: De client assertion (JWT) gegenereerd in de vorige stap.

Het toegangstoken gebruiken

Het toegangstoken kan worden gebruikt om een API aan te roepen. Het moet worden opgenomen in de 'Authorization' header met behulp van het 'Bearer' schema.

Notification API

Op deze pagina vind je uitleg over hoe je een AMQP consumer service kunt implementeren op een programmeertaal onafhankelijke manier. AMQP (Advanced Message Queuing Protocol) is een open standard application layer protocol voor message-oriented middleware. Het stelt applicaties in staat om berichten tussen systemen te verzenden, ongeacht platform of programmeertaal.

Op dit moment kan de berichtenwachtrij twee soorten berichten bevatten: het ticket created bericht en het comment created bericht. Deze berichten blijven 1 dag in de wachtrij.

Het ticket created bericht heeft het volgende formaat:

Het comment created bericht heeft het volgende formaat:

Client library

Voeg de juiste AMQP 1.0 client library toe voor je programmeertaal, bijvoorbeeld:

• .NET: Amqp.Net.Lite
• Java: Apache Qpid
• Python: qpid-proton
• JavaScript: rhea
  

Configuratie

Sla deze instellingen op en haal ze op:

• Broker URL/endpoint
  • Acceptance: amqps://:{BEARER_TOKEN}@amqp.acc.cmf.energysector.nl
  • Production: amqps://:{BEARER_TOKEN}@amqp.cmf.energysector.nl
• Queue name
  • /queues/energy-market.market-participant.partners-in-energy.notification.v1.{MARKETPARTY_EAN13}
• Authenticatiegegevens (JWK, CLIENT_ID, TOKEN_URL)
  

Authenticatie

Implementeer een tokenservice die:

• Authenticatietokens verkrijgt
• Tokens vernieuwt wanneer nodig, tokens zijn slechts 1 uur geldig
• Inloggegevens veilig opslaat
  

Verbindingsbeheer

• Maak een verbinding met de AMQP broker
• Stel een sessie in
• Maak een receiver link gekoppeld aan je wachtrij
• Implementeer een juiste connection cleanup bij afsluiten

Berichtverwerking

• Start een message consumer met een callback functie
• Verwerk ontvangen berichten
  • Om te bepalen welk bericht je verwerkt uit de wachtrij, kun je kijken naar de routing key.
    • De routing key bevindt zich in de Message Annotations sectie van een geconsumeerd bericht.
    • Het heeft de sleutel "x-routing-key".
    • En een waarde in het volgende patroon: [ean13].[entity-type].[action] (bijv. "7627119388329.comments.created")
    • message.MessageAnnotations.Map["x-routing-key"]

• Bevestig berichten na verwerking
• Implementeer foutafhandeling
  

REST API

Het PIE platform stelt drie REST endpoints bloot.

• GET {root-url}/pie-api/v1/tickets/{ticket-mrid}
• GET {root-url}/pie-api/v1/tickets/{ticket-mrid}/comments
• GET {root-url}/pie-api/v1/tickets/{ticket-mrid}/comments/{comment-mrid}

root-url acceptance: https://api.acc.cmf.energysector.nl

root-url production: https://api.cmf.energysector.nl

Door de berichten van de notificaties API te verwerken, kunnen de ticket- en comments ID's worden opgehaald. Met deze ID's is het mogelijk om deze REST endpoints aan te roepen om gedetailleerde informatie over tickets en opmerkingen op te halen.

Net als bij de notificatie API gebruikt de REST API OAuth voor authenticatie. Een token moet worden opgehaald en toegevoegd in de 'Authorization' header, voorafgegaan door 'Bearer' bij het verzenden van een verzoek.