Document status | PROPOSAL |
Version | 1.0 |
Date |
|
Over deze documentatie
In deze documentatie leest u welke vormvoorschriften verwacht worden van uw 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 leest u hier: https://vlaamseoverheid.atlassian.net/l/cp/0M5wkCN2
Met vragen of feedback kunt u terecht bij de servicedesk: https://www.vlaanderen.be/servicedesk/ik
Gebruikerscontext
Deze wireframes bieden u de nodige gebruikerscontext bij de documentatie van de API’s hieronder.
Algemene REST API-specificaties voor databronnen
Zie: 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": "uw-eloket-cname.formulieren.burgerprofiel.be/93a4b91a-93f4-4cb2-bdc5-14bc53762cef?token={TEMP_SSO_TOKEN}" "templated": true },
"fallback": { "href": "uw-eloket-cname.formulieren.burgerprofiel.be/93a4b91a-93f4-4cb2-bdc5-14bc53762cef" },
"ssoTokenRegistrationApi": { "href": "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": "formulieren.loket.vlaanderen.be/8350d7ed-ae18-4525-ac2c-abaa49656e3c?token={TEMP_SSO_TOKEN}" "templated": true },
"fallback": { "href": "formulieren.loket.vlaanderen.be/8350d7ed-ae18-4525-ac2c-abaa49656e3c" },
"thirdPartyCookieApi": { "href": "formulieren.loket.vlaanderen.be/api/v1/third_party_cookies" },
"ssoTokenRegistrationApi": { "href": "formulieren.loket.vlaanderen.be/api/v1/temp-sso-token" }
},
"sso": {
"audience": "d9da076d-3069-481c-9fa7-783ccb84ad61"
},
"id": "8350d7ed-ae18-4525-ac2c-abaa49656e3c",
"productId": "1390",
"nisCodes": [ "23096", "23038", "23081" ],
"title": "Inname openbaar domein",
"description": "Als u bouwt of verbouwt neemt u soms een deel van de openbare weg in om een container, een steiger, een bouwkraan, ... te plaatsen. Hiervoor moet u een toelating aanvragen."
},
...
]
}
}
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:
nisCodesom aan te geven voor welke lokale besturen het formulier van toepassing isURLs die niet onder http://burgerprofiel.be vallen, hiervoor is een
thirdPartyCookieApiverplicht (zie Aanvraagmodule - Third Party Cookies)IPDC-
titleen -descriptionvelden die toelaten de standaard tekst uit IDPC te overschrijven
Once-Only-principle: minimale input voor een maximaal hergebruik
Door het gebruik van IPDC en once-only principes streven we maximaal naar eenvoudige en eenduidige configuraties die de gebruiker een consistente ervaring geven doorheen het platform.
De minimaal verpichte velden zijn hieronder aangegeven met *
Key | Beschrijving |
|---|---|
| De link naar het fomulier dat geëmbed wordt in Mijn Burgerprofiel. Conform JSON-HAL kan dit een templated link zijn. Indien het formulier SSO verwacht (zie hieronder), dan kan in de URI template query expansion gedaan worden van Gebruik deze key indien er geen |
| De link naar een formulier dat een gebruiker kan openklikken wanneer het formulier niet kan worden geëmbed, bijv. door browser-incompatibiliteit. Om een fallback-link te gebruiken moeten er een global header en footer geconfigureerd zijn. Gebruik deze key indien er geen |
| Alleen nodig als de formulieren worden aangeboden via een third-party domein, niet indien onder een CNAME van Voor meer details, zie https://vlaamseoverheid.atlassian.net/wiki/spaces/IKPubliek/pages/6180832603/Aanvraagmodule+-+Third+Party+Cookies#Alternatieve-oplossing:-Third-party-cookie-API-endpoint |
| Verplicht voor formulieren die een aangemelde context vereisen (samen met Geeft aan op welk endpoint de aangemelde context van MBP overgedragen kan worden. Voor meer details, zie Aanvraagmodule - Authenticatie via Single Sign-on (SSO) |
| Verplicht wanneer Geeft aan voor welke doelgroep of “audience” (ACM Client-ID) de token exchange moet gebeuren wanneer de burger het formulier opent. Voorwaarde: een trust-relatie bij ACM (white-listed) van Mijn Burgerprofiel → klant |
| Het IPDC- |
| Voor formulieren die voor één ofmeerdere lokale besturen beschikbaar zijn. Bijv. "nisCodes": [ "23096", "23038", "23081" ] |
_links.embed en _links.fallback kunnen in deze combinaties worden gebruikt:
_links.embeden_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-linkwel
_links.embeden geen_links.fallbacker 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ërengeen
_links.embeden wel_links.fallback: er is geen iframe-integratie, alleen de knop die direct het extern loket opent
Query parameters
Parameter | Beschrijving |
|---|---|
| |
| 1 of meerdere IPDC-productcodes Bij meerdere productcodes wordt de parameter meerdere keren herhaald: |
| 1 of meerdere niscodes Bij meerdere niscodes wordt de parameter meerdere keren herhaald:
|
| Optioneel, voor use cases waarbij de titel, beschrijving of afleverende dienst overschreven moeten worden. Is dit het geval, dan kunt u dit opgeven wanneer u de aansluitingsaanvraag invult. Bij goedkeuring kan er toegelaten worden dat u deze velden overschrijft door deze alsnog mee te geven in de respons. |
Headers
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
Voor API’s, zie https://vlaamseoverheid.atlassian.net/wiki/spaces/IKPubliek/pages/2076934790/Algemene+REST+API-specificaties#ACM-OAuth-met-burgeridentificatie
Voor Front-end SSO, zie Aanvraagmodule - Authenticatie via Single Sign-on (SSO)
Afhandeling foutberichten
Integratie van formulieren in 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.
Diagram van openen van aanvraag
Lifecycle events
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.
Diagram
WINDOW_RESIZED event
Van zodra de pagina geladen is, moet dit aan Mijn Burgerprofiel gemeld worden (zodat de iframe getoond kan worden in plaats van de loading state).
De formulier-pagina moet rapporteren welke reële hoogte/breedte ze momenteel heeft (in pixels):
window.parent.postMessage({
"action": "WINDOW_RESIZED",
"height": 768,
"width": 1024
})
Hetzelfde event wordt ook verwacht als er veranderingen zijn in de afmetingen van de pagina, bijvoorbeeld wanneer er content verschuift of nieuwe velden zichtbaar worden.
Mijn Burgerprofiel gebruikt de informatie om rekening te houden met eventuele overflows, en indien nodig layoutaanpassingen te doen.
FORM_INITIALIZED event
Van zodra de gebruiker het formulier begint in te vullen, kan er dataverlies zijn indien de aanvraag gesloten wordt. Dit event wordt in eerste plaats gebruikt om aan te geven dat de gebruiker interactie heeft gehad met het formulier.
Het is aangeraden om eerst een informatieve pagina te tonen waarbij de gebruiker expliciet op een knop kan klikken om de aanvraag te ‘starten’ (wat dan een FORM_INITIALIZED event triggert).
Van zodra dit event getriggerd is in 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 worden.
window.parent.postMessage({
"action": "FORM_INITIALIZED"
})
Het is niet de bedoeling dat dit event direct bij het laden van de pagina verstuurd wordt
FORM_FINISHED event
Wanneer de gebruiker de aanvraag wil onderbreken zonder dat ze volledig ingediend kan worden, of wanneer alle stappen in het formulier doorlopen zijn zonder dat er een dossier opgestart wordt, kan het formulier een knop tonen die ervoor zorgt dat de aanvraag gesloten wordt.
Er wordt geen extra waarschuwing getoond aan de gebruiker, en het zijpaneel wordt toegeklapt. De gebruiker blijft op de pagina van waar de aanvraag gestart is.
window.parent.postMessage({
"action": "FORM_FINISHED"
})
FORM_SUBMITTED event
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 (zodat de gebruiker later de status van hun aanvraag kan opvolgen). Van zodra de aanvraag succesvol ingediend is bij het loket, dient 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 aanvragen gestuurd, en krijgt daar een alert te zien die aangeeft dat de aanvraag ingediend is. Idealiter is het dosis dossier daar dan ook direct zichtbaar als ingediende aanvraag (afhankelijk van de flow die bij het loket gevolgd wordt voor dosis-integratie).
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 kunnen (optioneel) 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)