Notificaties | skryvdocs

Inleiding

Via deze service is het mogelijk om notificaties te sturen vanuit het domein van de Vlaamse Overheid naar burgers, ondernemingen en organisaties.

Er zijn twee kanalen mogelijk:

passieve notificaties (een melding die verschijnt in de globale header van een digitaal loket en in de Brievenbus van Mijn Burgerprofiel);
e-mailnotificaties (rechtstreeks naar het e-mailadres van de bestemmeling).

Beide kanalen kunnen ook gecombineerd worden in één notificatie. Een notificatie versturen gebeurt in de vorm van een notificatiebundel: één boodschap, naar één of meerdere bestemmelingen, via één of meerdere kanalen. De externe dienst aanvaardt de notificatiebundel voor verwerking. Dat is geen garantie dat de notificatie ook meteen (of succesvol) afgeleverd is.

Deze service is Vlaams (beheerd door Digitaal Vlaanderen) en stuurt enkel korte statusmeldingen, geen officiële documenten. Verwar dit niet met eBox, de federale elektronische brievenbus waarin overheden op alle niveaus (federaal, Vlaams, lokaal) daadwerkelijke documenten afleveren, soms met juridische gevolgen (bv. een beroepstermijn).

Use cases

De notificaties-connector wordt gebruikt om burgers of organisaties automatisch op de hoogte te brengen van een statuswijziging, actie, of aankomende vervaldatum in hun dossier, zonder dat ze zelf actief moeten controleren of er iets veranderd is.

Typisch verloop binnen een Skryv-toepassing:

Er gebeurt een relevante wijziging in een dossier (bv. een beslissing, een goedkeuring, of een naderende vervaldatum van een toelating).
De workflow roept sendNotification aan met de betrokken bestemmeling(en), de gewenste categorie (bv. VrijeNotificatie of VervaldagBericht), en de bijhorende inhoud via sleutelWaardeParen.
Je kiest via kanalen of de bestemmeling dit als passieve melding (in Mijn Burgerprofiel), als e-mail, of via beide krijgt.
De bestemmeling ziet de notificatie in zijn Brievenbus (Mijn Burgerprofiel) en/of ontvangt een e-mail.

Setup

Onboardingsprocedure

Neem contact op met Digitaal Vlaanderen om de onboardingsprocedure op te starten, via het aanvraagformulier ‘Starten met Notificaties’. Hierbij krijg je toegang tot de OAuth 2.0/ACM-omgeving (scope dv_notificaties_import) en moet je een JWK-sleutelpaar registreren voor de client credentials-flow.

Opgelet: als je zelf e-mailadressen doorgeeft (dus niet uitsluitend via rijksregisternummer), een uitschrijflink (opt-out) voorzien in je e-mails. Dit is een wettelijke verplichting, te configureren per afzender.

Dependency toevoegen in pom.xml bestand

Voeg onderstaande maven dependency toe in je pom.xml. Dit zorgt ervoor dat de connector code binnengehaald en meegenomen wordt in de build van je applicatie.

<dependency>
   <groupId>com.skryv.connectors</groupId>
   <artifactId>notification</artifactId>
   <version>${skryv.version}</version>
</dependency>

Applicatie eigenschappen

Voeg onderstaande applicatie eigenschappen toe.

Eigenschap	Default	Beschrijving
NotificationBusinessConnector
`skryv.connectors.notification.service-url`	`http://localhost:1080`	Notification service URL
NotificationCamundaConnector
`skryv.connectors.notification.afzender-organisatie-code`	`null`	Sender organisation code
NotificationTokenFetcher
`skryv.connectors.geosecure.notification.scope`	`dv_notificaties_import`	GeoSecure OAuth scope.
`skryv.connectors.geosecure.notification.request-path`	`https://authenticatie-ti.vlaanderen.be/op/v1/token`	GeoSecure token request path
`skryv.connectors.geosecure.notification.app-number`	-	GeoSecure app number
`skryv.connectors.geosecure.notification.keypath`	-	GeoSecure keypath
`skryv.connectors.geosecure.notification.aws.seed.enabled`	`false`	Enable AWS seed for GeoSecure
`skryv.connectors.geosecure.notification.aws.keypath`	-	AWS keypath for GeoSecure

Services en functies

Overzicht

Functie	Retourtype	Info
sendNotification	`NotificationResponse`	Een notificatiebundel aanbieden voor verzending naar één of meerdere bestemmelingen, via passieve en/of e-mailnotificatie.

Naast de workflow expressie is deze functie ook rechtstreeks aanroepbaar vanuit Java-code door NotificationCamundaConnector (bean notificationService) te injecteren in je klasse.

Java

@RequiredArgsConstructor
public class MyOwnService {
    private final NotificationCamundaConnector notificationService;
}

sendNotification

Uitsturen van een notificatie.

Workflow expressie

${notificationService.sendNotification(Map<String,String> bestemmelingen, String categorieCode, boolean gelezen, String dossierId, ZonedDateTime expirationDate, List<String> kanalen, String productId, String merkCode, Map<String, String> sleutelWaardeParen)}

Java-code

NotificationResponse response = notificationService.sendNotification(
        bestemmelingen, categorieCode, gelezen, dossierId,
        expirationDate, kanalen, productId, merkCode, sleutelWaardeParen);

Input

Parameter	Data type	Verplicht	Voorbeeld	Uitleg
`bestemmelingen`	Map<String,String>	Ja	{'80102529724': ‘RijksRegisterNummer’}	Sleutel = identificatie of e-mailadres, waarde = het type bestemmeling. Enkel deze drie types zijn geldig: `RijksRegisterNummer` (identificatie = rijksregisternummer), `PersoonMetContactInfo` of `OrganisatieMetContactInfo` (in beide gevallen is de sleutel een e-mailadres). Een ander type-woord wordt niet door de connector gevalideerd en pas door de externe dienst afgekeurd.
`categorieCode`	String	Ja	‘VrijeNotificatie’	De template die bepaalt welke `sleutelWaardeParen` verwacht worden (zie voorbeelden onder Output). Twee bevestigde categorieën: `VrijeNotificatie` en `VervaldagBericht`. Andere categorieën zijn mogelijk configuratie-afhankelijk. Te bevragen bij Digitaal Vlaanderen.
`gelezen`	boolean	Ja (primitief type, dus altijd meegegeven)	‘false’	Geeft aan of het bericht al gelezen is in een ander systeem. Enkel relevant voor het kanaal `Passief`, zonder effect bij `Email`.
`dossierId`	String	Nee	‘interne-referentie-362b1160’	Wordt als `transactieId` doorgestuurd. Mag herhaald worden over meerdere notificaties heen — die worden dan gegroepeerd getoond (bv. in Mijn Burgerprofiel).
`expirationDate`	ZonedDateTime	Nee	2026-09-01T10:00:00+02:00	Wordt als `vervalDatum` doorgestuurd. Enkel relevant voor het kanaal `Passief`. De notificatie verdwijnt na deze datum uit Mijn Burgerprofiel. Kan niet meer gewijzigd worden nadat de notificatie verstuurd is.
`kanalen`	List<String>	Ja (min. 1 item)	['Passief']	Enkel twee geldige waarden: `Passief` en `Email`. Beide kunnen samen in de lijst staan.
`productId`	String	Ja	'201'	De IPDC-productcode van de dienst waarvoor genotifieerd wordt.
`merkCode`	String	Ja (verplicht Java-parameter)	-	Volgens de officiële Digitaal Vlaanderen-documentatie wordt dit veld niet meer gebruikt. Alle productomschrijvingen komen sinds IPDC v3 uit `productId`. De parameter staat nog in de connector-signatuur. Je kan hier vermoedelijk gerust `null` of een lege string doorgeven.
`sleutelWaardeParen`	Map<String,String>	Afhankelijk van `categorieCode`	Zie voorbeelden onder Output	Vrije inhoud van de notificatie, per categorie anders. Hou rekening met onderstaande beperkingen: Enkel platte tekstwaarden. Geneste of lijst-vormige sleutel/waarde-paren die de externe API toelaat, worden niet ondersteund. Geen meertaligheid (`WaardeFR`/`WaardeEN`/`WaardeDE`). enkel Nederlandse tekst kan via deze connector verstuurd worden.

Twee velden die de externe API verplicht, maar die je hier niet zelf meegeeft:

id (de connector genereert zelf een verse UUID per aanroep);
afzenderOrganisatieCode (ingesteld via de applicatie-eigenschap skryv.connectors.notification.afzender-organisatie-code). Indien niet ingesteld vult Digitaal Vlaanderen dit automatisch in op basis van je OAuth-claims.

Niet ondersteund door deze connector: uitgestelde/geplande verzending (VerzendDatum). De externe API laat toe om een notificatiebundel nu aan te maken, maar pas later te versturen. De connector heeft hiervoor geen parameter.

Output

Je krijgt een object NotificationResponse terug (met een Status-veld, bv. 'Success').

Belangrijk: dit is een bevestiging dat de notificatiebundel aanvaard is voor verwerking (HTTP 202 Accepted). Het is geen garantie dat de notificatie al effectief afgeleverd is bij de bestemmeling.

Voorbeeld sleutelWaardeParen bij categorie VrijeNotificatie

Sleutel	Verplicht	Uitleg
`Titel`	Ja	Titel van de notificatie.
`Body`	Ja	Vrije tekst, beperkte HTML toegelaten (`<p>`, `<ul>`, `<ol>`, `<li>`).
`DocumentLinkUri`	Nee	Deep-link naar meer info, bv. de detailpagina in het loket.
`ExterneLinkNaam`	Nee (max. 25 tekens)	Label voor de deep-link.

JSON

{
  "Titel": "Inschrijving dienstencheques",
  "Body": "Uw inschrijving tot de dienstenchequesportaal is bevestigd",
  "DocumentLinkUri": "http://www.dienstencheques.vlaanderen.be/xxx",
  "ExterneLinkNaam": "Meer informatie"
}

Voorbeeld sleutelWaardeParen bij categorie VervaldagBericht

Sleutel	Verplicht	Uitleg
`ArtikelNaam`	Ja	Naam van het product dat vervalt, bv. "Elektronische identiteitskaart".
`Vervaldatum`	Ja	De effectieve vervaldatum.
`BegeleidendeInfo`	Nee	Bijkomende tekst (niet de body), zelfde beperkte HTML.
`DocumentLinkUri`	Nee	Deep-link naar meer info.
`ExterneLinkNaam`	Nee	Label voor de deep-link.

JSON

{
  "ArtikelNaam": "Elektronische identiteitskaart",
  "Vervaldatum": "2021-06-03",
  "BegeleidendeInfo": "<p>Breng mee: <ul><li>oude identiteitskaart</li><li>uitnodiging om een nieuwe identiteitskaart op te halen</li></ul></p>",
  "DocumentLinkUri": "https://www.vlaanderen.be/elektronische-identiteitskaart-eid",
  "ExterneLinkNaam": "Elektronische identiteitskaart (eID)"
}

Error-handling

Statuscode	Betekenis
`400`	Ongeldige/onverwerkbare aanvraag. Specifiek geval: foutcode `1071` ("Bundel reeds eerder ingevoerd") als het `id` van de bundel al eerder gebruikt is — in de praktijk onwaarschijnlijk, want de connector genereert telkens een verse UUID.
`401`	Authenticatie ontbreekt of is mislukt (bv. verlopen of ongeldig OAuth-token).
`403`	Onvoldoende rechten om deze actie uit te voeren.
`405`	Ongeldige HTTP-methode voor dit endpoint.
`406`	Het gevraagde antwoordformaat wordt niet ondersteund.
`500`	Interne fout bij de externe dienst.

Geen typering van fouten in de connector. NotificationBusinessConnector.sendNotification vangt élke fout op (ook een mislukte tokenaanvraag) en gooit die telkens door als een kale, ongetypeerde RuntimeException. Er bestaat een eigen NotificationException-klasse in de codebase, maar die wordt nergens gebruikt.

De productie-omgeving van de service hanteert een harde limiet van 1800 calls per minuut.