API-calls Notificaties

1 API-documentatie
2 POST-call
3 Template voor de NotificatieCategorie “Vrije Notificaties”
4 Template voor de NotificatieCategorie “Vervaldagbericht”
5 Uitgestelde notificaties

API-documentatie

We maken 2 types API-documentatie beschikbaar:

Voor de POST-call, die alleen kan gedaan worden door de afzender, vindt u hieronder een codevoorbeeld.

POST-call

Deze call plaatst een nieuw ophaalverzoek voor de notificatiebundel: POST/api/v2/notificaties

Een voorbeeld van een payload bij een notificatiebundel voor een vrije notificaties:

{ 
  "Id": "85144567-7043-4469-9e79-279f4eb31e27", 
  "Bestemmelingen": [ 
    { 
      "Identificatie": "80102529724", 
      "Type": "RijksRegisterNummer" 
    }, 
  ], 
  "Categorie": { 
    "Code": "VrijeNotificatie", 
  }, 
  "TransactieId": "interne-referentie-111", 
  "VerzendDatum": "2021-07-27T14:25:05.514Z", 
  "VervalDatum": "2022-03-01T10:00:10.514Z",
  "Kanalen": [ 
    { 
      "Type": "Passief", 
    }, 
  ], 
  "ProductId": "130", 
  "SleutelWaardeParen": [ 
    { 
      "Sleutel": "Body", 
      "Waarde": " Uw inschrijving tot de dienstenchequesportaal is bevestigd" 
    }, 
    { 
      "Sleutel": "Titel", 
      "Waarde": "Inschrijving dienstencheques" 
    }, 
    { 
      "Sleutel": "DocumentLinkUri", 
      "Waarde": "http://www.dienstencheques.vlaanderen.be/xxx" 
    }, 
    { 
      "Sleutel": "ExterneLinkNaam", 
      "Waarde": "Meer informatie" 
    }, 
  ] 
}

Template voor de NotificatieCategorie “Vrije Notificaties”

De inkomende en uitgaande sleutelwaardeparen zijn identiek. Bovendien zijn de sleutelwaardeparen identiek voor beide kanalen: passief en e-mail.

Verplichte Sleutels	Waarde	Omschrijving

Verplichte Sleutels	Waarde	Omschrijving
Titel	string	De titel van de notificatie
Body	string	Vrij te kiezen tekst met beperkte opmaakmogelijkheden. De toegelaten html-tags zijn: <p> <ul> <ol> <li>
Optionele Sleutels	Waarde	Omschrijving
DocumentLinkUri	string	Een deep-link naar meer informatie voor de bestemmeling, vb. naar de detailpagina in het loket van het agentschap van de broninformatie.
ExterneLinkNaam	string - maximum 25 karakters	Het label dat moet gebruikt worden voor de deep-link

Template voor de NotificatieCategorie “Vervaldagbericht”

De inkomende en uitgaande sleutelwaardeparen zijn identiek. Bovendien zijn de sleutelwaardeparen identiek voor beide kanalen: passief en e-mail.

Verplichte Sleutels	Waarde	Omschrijving

Verplichte Sleutels	Waarde	Omschrijving
ArtikelNaam	string	De naam van het product dat vervalt, bijvoorbeeld: “Elektronische identiteitskaart”
Vervaldatum	string (datum/tijd)	De effectieve datum waarop het artikel vervalt
Optionele Sleutels	Waarde	Omschrijving
BegeleidendeInfo	string	Vrij te kiezen aanvullende tekst met beperkte opmaakmogelijkheden. Dit is niet de body van de notificatie. Toegelaten HTML-tags zijn <p> <ul> <ol> <li>
DocumentLinkUri	string	Een deeplink naar meer informatie voor de bestemmeling, bijv. naar de detailpagina van het product in het loket van het agentschap dat de broninformatie beheert
ExterneLinkNaam	string	Het label dat moet gebruikt worden voor de deep-link

Een voorbeeld van een payload met informatie over een vervaldagbericht:

{
  "Id": "e682c962-fe95-47d8-9cd2-65edc059d706",
  "TransactieId": "interne-referentie-e42231b6-b98c-48fd-bcfc-2a535d10346b",
  "ProductId": "148",
  "VerzendDatum": "2021-05-03T07:24:00Z",
  "VervalDatum": "2021-05-05T00:00:00Z",
  "Bestemmelingen": [
    {
      "Identificatie": "99999999999",
      "Type": "RijksRegisterNummer"
    }
  ],
  "Categorie": {
    "Code": "VervaldagBericht"
  },
  "Kanalen": [
    {
      "Type": "Email"
    },
    {
      "Type": "Passief"
    }
  ],
  "SleutelWaardeParen": [
    {
      "Waarde": "Elektronische identiteitskaart",
      "Sleutel": "ArtikelNaam"
    },
    {
      "Waarde": "2021-06-03",
      "Sleutel": "Vervaldatum"
    },
    {
      "Waarde": "<p>Breng mee: <ul><li>oude identiteitskaart</li><li>uitnodiging om een nieuwe identiteitskaart op te halen</li></ul></p>",
      "Sleutel": "BegeleidendeInfo"
    },
    {
      "Waarde": "https://www.vlaanderen.be/elektronische-identiteitskaart-eid",
      "Sleutel": "DocumentLinkUri"
    },
    {
      "Waarde": "Elektronische identiteitskaart (eID)",
      "Sleutel": "ExterneLinkNaam"
    }
  ]
}

Uitgestelde notificaties

Dit zijn notificatiebundels die worden aangemaakt om op een later tijdstip te versturen naar de bestemmeling.

In het NotificatieBundelVerzoek wordt hiervoor een veld VerzendDatum toegevoegd. Zodra daar een datum wordt ingevuld, dan gelden de volgende voorwaarden:

De tijdzone moet ook ingevuld zijn (timezone = ISO 8601). Dit is noodzakelijk om te vermijden dat het tijdstip hetzelfde is, maar in een andere tijdzone.
De datum moet in de toekomst liggen
Er is geen minimum toekomstige datum. Gebruik dit veld zinvol: maak bijvoorbeeld geen notificatie die een half uur later kan worden uitgestuurd.
Er is echter wel een maximale datum in de toekomst, nl. vandaag + 1 maand. Hiermee vermijdt u dat de informatie in de notificatie niet meer accuraat/gevalideerd is.

De volgende velden hoeft u niet in te vullen:

Afzenderorganisatiecode: Digitaal Vlaanderen vult hier de OVO-code in van de organisatie die de notificaties verstuurt. U hoeft dit niet zelf in te vullen. De OVO-code is gekend uit de ACM Client claims.
Merkcode: wordt niet meer gebruikt. Alle productomschrijvingen komen uit IPDC v3 op basis van Product-Id.

Het Id-veld moet uniek zijn. Indien dezelfde notificatie meerdere malen aangeboden wordt, krijgt u een 400-response met een errorcode 1071 "Bundel reeds eerder ingevoerd".
De Transactie-Id mag dezelfde zijn in meerdere notificaties. Notificaties met dezelfde Transactie-Id worden gegroepeerd weergegeven.
Schrijf OVO-code altijd met hoofdletters.

Documentatie voor partners en klanten van Digitaal Vlaanderen - bouwstenen Mijn Burgerprofiel, Verenigingsloket en e-loketondernemers

Documentatie voor klanten en partners van Digitaal Vlaanderen - bouwstenen Mijn Burgerprofiel, Verenigingsloket en e-loketondernemers