...

...

...

...

...

Document status

...

...

Version

...

1.0

...

Date

...

09 Nov 2022

Over deze documentatie

In deze documentatie leest u welke vormvoorschriften verwacht worden van uw API’s API('s) om te kunnen integreren met Mijn Burgerprofiel. Het is een verdere uitwerking van dehttps://vlaamseoverheid.atlassian.net/l/c/LP1ZL8i6.

• Meer informatie over de types aansluitingen op de bouwsteen aanvraagformulieren Aanvraagformulieren leest u hier: https://vlaamseoverheid.atlassian.net/l/cp/0M5wkCN2

• Met vragen of feedback bij een bestaande koppeling kunt u terecht bij de servicedesk: https://www.vlaanderen.be/servicedesk/ik

Gebruikerscontext

...

- Look en feel formulieren

Hier vindt u binnenkort wireframes die u de nodige gebruikerscontext bieden bij de documentatie van de API’s hieronder.

Algemene REST API-specificaties voor databronnen

Zie: https://vlaamseoverheid.atlassian.

Zie ook: https://vlaamseoverheid.atlassian.net/l/c/LP1ZL8i6.

REST API

GET /api/v1/forms

{
    "_links": {
      "self": { "href": "https://dienstenleverancier.be/api/v1/forms?limit=10&offset=0" },
      "first": { "href": "https://dienstenleverancier.be/api/v1/forms?limit=10&offset=0" },
      "next": { "href": "https://dienstenleverancier.be/api/v1/forms?limit=10&offset=10" },
      "last": { "href": "https://dienstenleverancier.be/api/v1/forms?limit=10&offset=30" }
    },
    "_pageMetadata": {
      "offset": 0,
      "size": 10,
      "totalItems": 35
    },
   "_embedded": {
      "items": [
        {
          "_links": {
              "embed": { "href": "https://uw-eloket-cname.formulieren.burgerprofiel.be/93a4b91a-93f4-4cb2-bdc5-14bc53762cef?token={TEMP_SSO_TOKEN}", "templated": true },
              "fallback": { "href": "https://uw-eloket-cname.formulieren.burgerprofiel.be/93a4b91a-93f4-4cb2-bdc5-14bc53762cef" },
              "ssoTokenRegistrationApi": { "href": "https://uw-eloket-cname.formulieren.burgerprofiel.be/api/v1/temp-sso-token" }
          },
          "sso": {
            "audience": "93a4b91a-93f4-4cb2-bdc5-14bc53762cef"
          },
          "id": "d898fa60-e76f-44bb-89bd-9a468dab2319",
          "productId": "697"
        },
        {
          "_links": {
              "embed": { "href": "https://formulieren.loket.vlaanderen.be/8350d7ed-ae18-4525-ac2c-abaa49656e3c?token={TEMP_SSO_TOKEN}" "templated": true },
              "fallback": { "href": "https://formulieren.loket.vlaanderen.be/8350d7ed-ae18-4525-ac2c-abaa49656e3c" },
              "thirdPartyCookieApi": { "href": "https://formulieren.loket.vlaanderen.be/api/v1/third_party_cookies" },
              "ssoTokenRegistrationApi": { "href": "https://formulieren.loket.vlaanderen.be/api/v1/temp-sso-token" }
          },
          "sso": {
            "audience": "d9da076d-3069-481c-9fa7-783ccb84ad61"
          },
          "id": "8350d7ed-ae18-4525-ac2c-abaa49656e3c",
          "productId": "1390",
          "

...

nisCode":

...

 "23096"

...

...

...

...

...

},
        

...

Het bovenstaande codevoorbeeld geeft de volgende 2 items terug:

• Een standaard item op basis van het Once-Only-principe waarbij u de minimale parameters van het formulier opgeeft. De voorwaarde is een CNAME onder http://burgerprofiel.be, en de respectievelijke testdomeinen.

• Een tweede item met extensies:

  • nisCodes om aan te geven voor welke lokale besturen het formulier van toepassing is

  • URLs die niet onder http://burgerprofiel.be vallen, hiervoor is een thirdPartyCookieApi verplicht (zie Aanvraagmodule - Third Party Cookies)

  • IPDC-title en -description velden die toelaten de standaard tekst uit IDPC te overschrijven

...

Key

...

Beschrijving

...

_links.embed

De link naar het fomulier dat geëmbed wordt in Mijn Burgerprofiel.

Conform JSON-HAL kan dit een templated link zijn.

...

...
      ]
    }
  }

Het bovenstaande codevoorbeeld geeft de volgende 2 items terug:

• Een standaard item op basis van het Once-Only-principe waarbij u de minimale parameters van het formulier opgeeft. De voorwaarde is een CNAME onder http://*.burgerprofiel.be, en de respectievelijke testdomeinen.

• Een tweede item met extensies:

  • nisCode om aan te geven voor welk lokaal bestuur het formulier van toepassing is

  • productId voor het IPDC-nummer

  • URLs die niet onder http://burgerprofiel.be vallen, hiervoor is een thirdPartyCookieApi verplicht (zie Aanvraagmodule - Third-party cookies)

...

_links.embed en _links.fallback: er is een iframe-integratie dankzij de embed-link, en er wordt in het zijpaneel ook een link naar het extern loket getoond dankzij de fallback-link

...

wel _links.embed en geen _links.fallback er is een iframe-integratie dankzij de embed-link maar de link naar het extern loket is identiek aan de link voor de iframe (zonder SSO) - let op: het is altijd beter om de fallback-link expliciet te definiëren

...

"nisCodes": [ "23096", "23038", "23081" ]

...

_links.embed en _links.fallback kunnen in deze combinaties worden gebruikt:

"nisCode": "23096"

Query parameters

GET /api/v1/forms-submissions (optioneel)

{
    "_links": {
      "self": { "href": "https://dienstenleverancier.be/api/v1/form-submissions?limit=10&offset=0" },
      "first": { "href": "https://dienstenleverancier.be/api/v1/form-submissions?limit=10&offset=0" },
      "next": { "href": "https://dienstenleverancier.be/api/v1/form-submissions?limit=10&offset=10" },
      "last": { "href": "https://dienstenleverancier.be/api/v1/form-submissions?limit=10&offset=20" },
    },
    "_pageMetadata": {
      "offset": 0,
      "size": 10,
      "totalItems": 26
    },
   "_embedded": {
      "items": [
        {
          "_links": {
              "embed": { "href": "https://uw-eloket-cname.formulieren.burgerprofiel.be/submission/cff3bebb-dd1c-4937-b335-f6c8c9543cb6?token={TEMP_SSO_TOKEN}", "templated": true },
              "fallback": { "href": "https://uw-eloket-cname.formulieren.burgerprofiel.be/submission/cff3bebb-dd1c-4937-b335-f6c8c9543cb6 },
              "ssoTokenRegistrationApi": { "href": "https://uw-eloket-cname.formulieren.burgerprofiel.be/api/v1/temp-sso-token" }
          },
          "sso": {
            "audience": "93a4b91a-93f4-4cb2-bdc5-14bc53762cef"
          },
          "id": "cff3bebb-dd1c-4937-b335-f6c8c9543cb6",
          "productId": "697"
          "status": "in-progress",
          "created": "2020-08-11T08:34:55.451Z",
          "updated": "2020-08-19T10:58:12.379Z"
        },
        {
          "_links": {
              "embed": { "href": "https://formulieren.loket.vlaanderen.be/submission/80a5af1f-8786-4124-9d60-652e53428a8d?token={TEMP_SSO_TOKEN}", "templated": true },
              "fallback": { "href": "https://formulieren.loket.vlaanderen.be/submission/80a5af1f-8786-4124-9d60-652e53428a8d" },
              "thirdPartyCookieApi": { "href": "https://formulieren.loket.vlaanderen.be/api/v1/third_party_cookies" },
              "ssoTokenRegistrationApi": { "href": "https://formulieren.loket.vlaanderen.be/api/v1/temp-sso-token" }
          },
          "sso": {
            "audience": "d9da076d-3069-481c-9fa7-783ccb84ad61"
          },
          "id": "80a5af1f-8786-4124-9d60-652e53428a8d",
          "productId": "1390"
          "nisCode": "23096",
          "status": "in-progress",
          "created": "2020-08-11T08:34:55.451Z",
          "updated": "2020-08-19T10:58:12.379Z"
        },
        ...
      ]
    }
  }

Het bovenstaande codevoorbeeld geeft items terug met deze extra extensies:

• status: in-progress zodat het formulier tussentijds kan bewaard worden

• created: Datum wanneer de instantie van het formulier aangemaakt is

• updated: Datum wanneer de laatste wijziging is gebeurd aan de instantie van het formulier

Query parameters

Headers

Zie https://vlaamseoverheid.atlassian.net/wiki/spaces/IKPubliek/pages/2076934790/Algemene+REST+API-specificaties#CorrelationId-en-RequestId

De X-Correlation-ID en X-Request-ID headers zullen aanwezig zijn op de aanvragen en we verwachten dat de API-implementatie er rekening mee houdt in de responses.

Authenticatie

...

Headers

Zie https://vlaamseoverheid.atlassian.net/wiki/spaces/IKPubliek/pages/2076934790/Algemene+REST+API-specificaties#CorrelationId-en-RequestId

De X-Correlation-ID en X-Request-ID headers zullen aanwezig zijn op de aanvragen en we verwachten dat de API-implementatie er rekening mee houdt in de responses.

Authenticatie

We maken onderscheid tussen de forms API en de form submissions API.

De forms API is verondersteld onafhankelijk te zijn van de ingelogde burger. Deze API moet ook aangeroepen worden in een niet-aangemaalde MBP sessie. Voor dit endpoint worden daar volgende authenticatie middelen ondersteund:

• anonymous (publiek)

• OAuth2 met client-credentials-grant (meer informatie op https://authenticatie.vlaanderen.be/docs/beveiligen-van-api/oauth-rest/rest-server2server/)

• mTLS

De form submissions API moet aangeroepen worden in de context van een aangemelde burger, hiervoor zie https://vlaamseoverheid.atlassian.net/wiki/spaces/IKPubliek/pages/2076934790/Algemene+REST+API-specificaties#ACM-OAuth-met-burgeridentificatie

...

Zie https://vlaamseoverheid.atlassian.net/wiki/spaces/IKPubliek/pages/2076934790/Algemene+REST+API-specificaties#Standaard-foutberichten

...

Formulieren koppelen met Mijn Burgerprofiel

Mijn Burgerprofiel gebruikt de REST-API (zie hierboven) om de dienstverlening van verschillende leveranciers aan te bieden via de lijst met Aanvragen.
Als de gebruiker kiest om een aanvraag te starten, wordt de embed-link (die hierboven beschreven staat) geopend in een zijpaneel.

...

Een aanvraag starten

...

Om de integratie met Mijn Burgerprofiel correct te laten verlopen, moet de embed-pagina bepaalde gebeurtenissen melden aan Mijn Burgerprofiel. Momenteel gebeurt dit aan de hand van het window.postMessage op het parent-window (= Mijn Burgerprofiel). Die gebeurtenissen worden opgevangen om de gebeurtenissen - zoals een formulier indienen - correct te verwerken.

...

WINDOW_RESIZED event

Van zodra Zodra de pagina geladen is, moet dit aan Mijn Burgerprofiel worden gemeld worden (, zodat de iframe kan worden getoond kan worden (in plaats van de loading state).

De Dit event zorgt ervoor dat de formulier-pagina moet rapporteren rapporteert over welke reële hoogte/breedte ze die momenteel heeft (in pixels):

...

Hetzelfde event wordt ook verwacht als er veranderingen zijn in de afmetingen van de pagina, bijvoorbeeld wanneer er content verschuift of wanneer nieuwe velden zichtbaar worden.

Mijn Burgerprofiel gebruikt de informatie om rekening te houden met eventuele overflows, en om indien nodig layoutaanpassingen lay-outaanpassingen te doen.

FORM_INITIALIZED event

Van zodra Zodra de gebruiker het formulier begint in te vullen, kan er dataverlies zijn indien als de aanvraag gesloten wordt vooraleer ze bevestigd en ingediend is. Dit event wordt in eerste plaats gebruikt om aan te geven dat de gebruiker interactie heeft gehad met het formulier.

...

...

...

Van zodra Zodra dit event getriggerd is in de context van een formulier, kan de gebruiker het zijpaneel in Mijn Burgerprofiel niet zonder meer sluiten. Vanaf dan wordt een waarschuwing getoond waarbij de gebruiker moet bevestigen dat ze zeker zijn dat het formulier gesloten mag wordensluiten zonder een waarschuwing te krijgen.

window.parent.postMessage({
  "action": "FORM_INITIALIZED"
})

FORM_FINISHED event

Wanneer de gebruiker de aanvraag wil onderbreken zonder dat ze volledig ingediend kan wordenze in te dienen, of wanneer alle stappen in het formulier doorlopen zijn zonder dat er een dossier opgestart wordtte starten, kan het formulier een knop tonen die ervoor zorgt dat om de aanvraag gesloten wordtte sluiten. Er wordt

...

...

window.parent.postMessage({
  "action": "FORM_FINISHED"
})

...

Wanneer de gebruiker de aanvraag volledig heeft ingevuld, kan ze ingediend worden. Dit houdt ook in dat achter de schermen een dosis dossier opgestart is (Na indiening wordt er een dossier opgestart zodat de gebruiker later de status van hun de aanvraag kan opvolgen). Van zodra

Zodra de aanvraag succesvol met succes is ingediend is bij het loket, dient moet de pagina dit te melden aan Mijn Burgerprofiel. Op basis van dit event wordt het zijpaneel gesloten (zonder extra waarschuwing). De gebruiker wordt naar de overzichtspagina van met aanvragen gestuurd, en krijgt daar een alert te zien die aangeeft ziet daar de bevestiging dat de aanvraag ingediend is.

...

...

...

...

window.parent.postMessage({
  "action": "FORM_SUBMITTED",
  "submissionTitle": "Uw aanvraag is ingediend",
  "submissionMessage": "Loket X verwerkt nu uw aanvraag. U ontvangt een melding wanneer ze in behandeling is.",
  "dosis": "urn://loket.burgerprofiel.be/aanvraag/86-XIOSJP-91352"
})

• submissionTitle en submissionMessage

...

• (optioneel) kunnen meegegeven worden om de boodschap in de alert aan te passen.

• dosis kan (optioneel) meegegeven worden om aan te geven wat de dossierbron & dossiernummer zijn van het nieuwe dossier (op die manier kan het relevante dossier opgehaald worden in het aanvragen-overzicht)

...

Changelog

...