...

...

...

...

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.net/l/c/LP1ZL8i6.

REST API

...

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)

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

Query parameters

...

Parameter

...

Beschrijving

...

limit, offset

...

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

...

productId

...

1 of meerdere IPDC-productcodes

...

nisCode

...

1 of meerdere niscodes

• Als de niscode niet wordt meegegeven, willen we alleen de Vlaamse dienstverlening(en) terugkrijgen.

• Wordt de niscode wel meegegeven, dan willen we zowel de Vlaamse als de lokale dienstverleningen, die voldoen aan de niscode-voorschriften, terugkrijgen.

...

allowIpdcOverwriteFromSource

...

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

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

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

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

Voor een eenvoudigere configuratie kan Aansluitingen een configuratie vragen die bij de formulieren aggregator kan ingeregeld worden, zie ook deze Jira template voor het aanmaken van een ticketje bij het dev-team

Minimale data die nodig is voor een eenvoudige aansluiting (met IPDC). Dit gaat open in een nieuwe tab:

...

"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": "willekeurighttps://uw-eloket-cname.formulieren.vlaanderenburgerprofiel.be/submission/urlcff3bebb-naardd1c-formulier4937-met-global-header"b335-f6c8c9543cb6 },
           },   "idssoTokenRegistrationApi": { "href": "ee5d582c-5c94-4f62-9f6b-424c41e129f7",
  "productId": "1456"
}

Door enkel de fallback mee te geven gaat deze open in een nieuwe tab. Enkel een unieke id (deze heeft verder geen betekenis in deze setup, gewoon een random UUID genereren) en een productId is vereist.

Een eenvoudig aansluiting toevoegen die onder *.vlaanderen.be valt (first-party). Deze formulieren kunnen ge-embed op Mijn Burgerprofiel worden, door de embed property toe te voegen:

{
  "_links": {https://uw-eloket-cname.formulieren.burgerprofiel.be/api/v1/temp-sso-token" }
          },
          "sso": {
          "embed": { "hrefaudience": "willekeurig-eloket.vlaanderen.be/url-naar-formulier" },93a4b91a-93f4-4cb2-bdc5-14bc53762cef"
       "fallback": { "href": "willekeurig-eloket.vlaanderen.be/url-naar-formulier-met-global-header" },
   },       "id": "ee5d582ccff3bebb-5c94dd1c-4f624937-9f6bb335-424c41e129f7f6c8c9543cb6",
          "productId": "1456697"
}

Voorbeeld eenvoudige aansluiting voor Fayatbeurs. Openen in een nieuwe tab (geen embed) en met overschrijving van IPDC properties (af te raden, IPDC zou leidend moeten zijn):

          {
        "_links"status": {"in-progress",
          "fallbackcreated": { "href": "https://fayatbeurzen.vlaanderen.be/" }2020-08-11T08:34:55.451Z",
        },         "id"updated": "9a283d7e2020-c350-45b5-aa14-0f5639d45425",08-19T10:58:12.379Z"
        "title": "Fayatbeurs",
},
       "provider": {
          "id_links": "OVO000032", {
              "nameembed": { "Departement Kanselarij en Buitenlandse Zaken"
  href": "https://formulieren.loket.vlaanderen.be/submission/80a5af1f-8786-4124-9d60-652e53428a8d?token={TEMP_SSO_TOKEN}", "templated": true },
     },         "descriptionfallback": { "Wilt u na uw masterdiploma verder studeren aan een buitenlandse topinstelling? En tegelijk Vlaanderen mee op de kaart zetten in het buitenland? Dan is een Fayatbeurs misschien iets voor u."
      }

...

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

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

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

...

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.

...

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.

...

FORM_FINISHED event

Wanneer de gebruiker de aanvraag wil onderbreken zonder die 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.

...

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"
})

...