1 Over deze documentatie
2 Gebruikerscontext - Look en feel formulieren
3 REST API
- 3.1 GET /api/v1/forms
- 3.2 GET /api/v1/forms-submissions (optioneel)
- 3.3 Headers
- 3.4 Authenticatie
- 3.5 Afhandeling foutberichten
4 Formulieren koppelen met Mijn Burgerprofiel
- 4.1 Een aanvraag starten
- 4.2 Lifecycle events
  - 4.2.1 WINDOW_RESIZED event
  - 4.2.2 FORM_INITIALIZED event
  - 4.2.3 FORM_FINISHED event
  - 4.2.4 FORM_SUBMITTED event

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 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.

Om een consistente gebruikerservaring te bieden, verwachten we dat de formulieren die we embedden in Mijn Burgerprofiel, zoveel mogelijk de look en feel van Mijn Burgerprofiel benaderen.
Maak de formulieren ook mobile friendly als u ze beschikbaar wil maken in de mobiele app van Mijn Burgerprofiel en/of uw gemeente app. Ondersteuning nodig? Stuur uw vraag gerust naar aansluitingen.mijnburgerprofiel@vlaanderen.be.

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:
- 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)

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

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. Indien het formulier SSO verwacht (zie hieronder), dan kan in de URI template query expansion gedaan worden van `TEMP_SSO_TOKEN` of `token` (die overeenkomen met het single use SSO token, zie Aanvraagmodule - Authenticatie via Single Sign-on (SSO) \| Gebruikerscontext doorgeven aan een Aanvraagmodule Gebruik deze key indien er geen `fallback` wordt meegegeven.
`_links.fallback`	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 `embed` wordt meegegeven.
`_links.thirdPartyCookieApi`	Alleen nodig als de formulieren worden aangeboden via een third-party domein, niet indien onder een CNAME van `*.formulieren.burgerprofiel.be` Voor meer details, zie Aanvraagmodule - Third-party cookies \| Alternatieve oplossing: Third party cookie API endpoint
`_links.ssoTokenRegistationApi`	Verplicht voor formulieren die een aangemelde context vereisen (samen met `sso.audience`, hieronder beschreven). Geeft aan op welk endpoint de aangemelde context van MBP overgedragen kan worden. Voor meer details, zie Aanvraagmodule - Authenticatie via Single Sign-on (SSO)
`sso.audience`	Verplicht wanneer `_links.ssoTokenRegistationApi` meegegeven wordt. 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 Zie ook: ACM-integratie \| Aanvragen Provider API
`productId` ^*	Het IPDC- `productId` wordt gebruikt om in IPDC de titel, beschrijving, afleverende dienst, thematiek en meer info-link op te vragen.
`nisCode`	Voor formulieren die voor een lokale bestuur beschikbaar is. Voor dienstverleningen op Vlaams niveau komt deze property niet terug - kan vrijblijvend wel worden ingevuld, afhankelijk van de context. Voor dienstverleningen op lokaal niveau is deze property wel verplicht. Bijv. `"nisCode": "23096"`

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

_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
geen _links.embed en wel _links.fallback: er is geen iframe-integratie, alleen de knop die direct het extern loket opent

Query parameters

Parameter	Beschrijving

Parameter	Beschrijving
`limit`, `offset`	Zie Algemene REST API-specificaties \| Paginering

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

Parameter	Beschrijving

Parameter	Beschrijving
`limit`, `offset`	Zie Algemene REST API-specificaties \| Paginering

Headers

Zie 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 oAuth REST API voor server-naar-server)
mTLS

De form submissions API moet aangeroepen worden in de context van een aangemelde burger, hiervoor zie Algemene REST API-specificaties | ACM OAuth met burgeridentificatie

Voor Front-end SSO, zie Aanvraagmodule - Authenticatie via Single Sign-on (SSO)

Afhandeling foutberichten

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

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.

WINDOW_RESIZED event

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

Dit event zorgt ervoor dat de formulier-pagina rapporteert over welke reële hoogte/breedte die 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 wanneer nieuwe velden zichtbaar worden.

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

FORM_INITIALIZED event

Zodra de gebruiker het formulier begint in te vullen, kan er dataverlies zijn 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.

Het is aangeraden een informatieve pagina te tonen waarbij de gebruiker expliciet de aanvraag moet starten. Die actie kan dan de FORM_INITIALIZED event triggeren.

Zodra dit event getriggerd is in de context van een formulier, kan de gebruiker het zijpaneel in Mijn Burgerprofiel niet sluiten zonder een waarschuwing te krijgen.

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 ze in te dienen, of wanneer alle stappen in het formulier doorlopen zijn zonder een dossier te starten, kan het formulier een knop tonen om de aanvraag te sluiten.

De gebruiker krijgt geen extra waarschuwing en het zijpaneel wordt toegeklapt. De gebruiker blijft op de pagina 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. Na indiening wordt er een dossier opgestart zodat de gebruiker later de status van de aanvraag kan opvolgen.

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

Idealiter is het dossier ook direct zichtbaar als ingediende aanvraag. Dit is echter afhankelijk van de flow die bij het loket gevolgd wordt om de dossierstatusinformatie (DOSIS) te integreren.

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)

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

API-specificaties voor aanbieders van formulieren