Versions Compared

Old Version 50

changes.mady.by.user Heidi Vannevel

Saved on

compared with

New Version Current

changes.mady.by.user Philippe Schottey

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents

...

Code Block
breakoutModefull-width
languagejson
{
    "_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",
          "nisCodesnisCode": [ "23096", "23038", "23081" ]
        },
        ...
      ]
    }
  }

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 nisCode om aan te geven voor welke lokale besturen 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 Aanvraagformulieren Aanvraagmodule - Third-party cookies)

Info

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

_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 https://vlaamseoverheid.atlassian.net/wiki/spaces/IKPubliek/pages/5848175061#Gebruikerscontext-doorgeven-aan-een-Aanvraagmodule

Info

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.

Note

Om een fallback-link te gebruiken moeten er een global header en footer geconfigureerd zijn.

Info

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 https://vlaamseoverheid.atlassian.net/wiki/spaces/IKPubliek/pages/6180832603/

Aanvraagformulieren

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

Aanvraagformulieren

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.

Note

Voorwaarde: een trust-relatie bij ACM (white-listed) van Mijn Burgerprofiel → klant
Zie ook: https://vlaamseoverheid.atlassian.net/wiki/spaces/IKPubliek/pages/6117854932/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.

nisCodes

nisCode

Voor formulieren die voor

één of meerdere

een lokale

besturen

bestuur beschikbaar

zijn

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.

Code Block
"
nisCodes
nisCode":
[
 "23096
", "23038
"
, "23081" ]
 Info
_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
limit, offset
Zie https://vlaamseoverheid.atlassian.net/wiki/spaces/IKPubliek/pages/2076934790/Algemene+REST+API-specificaties#Paginering
productId
1 of meerdere IPDC-productcodes
 Info
Bij meerdere productcodes wordt de parameter meerdere keren herhaald: 
(?productId=1234&productId=5678&productId=9752)
nisCode
1 of meerdere niscodes
 Info
Bij meerdere niscodes wordt de parameter meerdere keren herhaald: 
(?nisCode=12345&nisCode=67890&nisCode=85214)
  • Als de niscode niet wordt meegegeven, worden alleen de Vlaamse dienstverlening(en) teruggegeven. 
  • Wordt de niscode wel meegegeven, dan worden zowel de Vlaamse als de lokale dienstverleningen, die voldoen aan de niscode-voorschriften, teruggegeven. 
...
breakoutModefull-width

...
GET /api/v1/forms-submissions (optioneel)
 Code Block
breakoutModefull-width
{
    "_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" },
      "selflast": { "href": "https://fl-test-eportal.skryv.comdienstenleverancier.be/api/v1/form-submissions?limit=10&offset=020" },
    },
    "first_pageMetadata": {
      "hrefoffset": "https://fl-test-eportal.skryv.com/api/v1/form-submissions?limit=10&offset=0" },0,
      "size": 10,
      "totalItems": 26
    },
   "next_embedded": {
"href      "items": "https://fl-test-eportal.skryv.com/api/v1/form-submissions?limit=10&offset=10" },[
        {
          "_links": {
              "lastembed": { "href": "https://fluw-testeloket-eportalcname.formulieren.skryvburgerprofiel.combe/api/v1/form-submissions?limit=10&offset=20" },
    },submission/cff3bebb-dd1c-4937-b335-f6c8c9543cb6?token={TEMP_SSO_TOKEN}", "templated": true },
      "_pageMetadata": {       "offsetfallback": 0,
      "size": 10,
 { "href": "https://uw-eloket-cname.formulieren.burgerprofiel.be/submission/cff3bebb-dd1c-4937-b335-f6c8c9543cb6 },
    "totalItems": 26     },    "_embeddedssoTokenRegistrationApi": {       "items": [
        {"href": "https://uw-eloket-cname.formulieren.burgerprofiel.be/api/v1/temp-sso-token" }
          },
          "_linkssso": {
              "embedaudience": { "href": "https://fl-test-eportal.skryv.com/#/80a5af1f-8786-4124-9d60-652e53428a8d" },"93a4b91a-93f4-4cb2-bdc5-14bc53762cef"
          },
        "fallback": { "hrefid": "https://fl-test-eportal.skryv.com/#/80a5af1f-8786-4124-9d60-652e53428a8d" },cff3bebb-dd1c-4937-b335-f6c8c9543cb6",
          "productId": "697"
        "form": { "hrefstatus": "https://fl-test-eportal.skryv.com/#/dossier-info/8350d7ed-ae18-4525-ac2c-abaa49656e3c" },in-progress",
          "created": "2020-08-11T08:34:55.451Z",
        "thirdPartyCookieApi": { "hrefupdated": "https://fl-test-eportal.skryv.com/api/v1/third_party_cookies" }2020-08-19T10:58:12.379Z"
          },
        {
  "id": "80a5af1f-8786-4124-9d60-652e53428a8d",       "_links": {
  "formId": "8350d7ed-ae18-4525-ac2c-abaa49656e3c",           "statusembed": { "href": "in-progresshttps://formulieren.loket.vlaanderen.be/submission/80a5af1f-8786-4124-9d60-652e53428a8d?token={TEMP_SSO_TOKEN}", "templated": true  },
      "provider": {            "fallback": { "idhref": "OVO000106"https://formulieren.loket.vlaanderen.be/submission/80a5af1f-8786-4124-9d60-652e53428a8d" },
              "namethirdPartyCookieApi": { "Wonen-Vlaanderenhref",
 : "https://formulieren.loket.vlaanderen.be/api/v1/third_party_cookies" },
        },      "ssoTokenRegistrationApi": {    "createdhref": "2020-08-11T08:34:55.451Z",
https://formulieren.loket.vlaanderen.be/api/v1/temp-sso-token" }
         "updated": "2020-08-19T10:58:12.379Z" },
        },  "sso": {
     ...       ]"audience": "d9da076d-3069-481c-9fa7-783ccb84ad61"
          },
  }
Het bovenstaande codevoorbeeld geeft items terug met deze extra extensies:
  • status: in progress zodat het formulier tussentijds kan bewaard worden 
  • provider id en name: de OVO-code en de naam van de bevoegde overheid
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
...
        "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
limit, offset
Zie https://vlaamseoverheid.atlassian.net/wiki/spaces/IKPubliek/pages/2076934790/Algemene+REST+API-specificaties#Paginering
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:
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 Aanvraagformulieren Aanvraagmodule - Authenticatie via Single Sign-on (SSO) 
Afhandeling foutberichten
...
Een aanvraag starten 
 Inc drawio
custContentId
zoom1
simple0
custContentId6183060345
pageId5873176651
6183060345lbox1
diagramDisplayNameformulieren-sequence.drawio
hiResPreview0
baseUrlhttps://vlaamseoverheid.atlassian.net/wiki
imgPageId5873176651
diagramNameform-lifecycles.drawioimgPageId5873176651
pCenter1
aspectE67gfSI1WxzeGBtbC1I_ 1
width1141
includedDiagram1
aspectHash6b6e031c3405ec3e39dad7538d7667c7c25f2438
linksauto
tbstyletop
height1091
...
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.
 Inc drawio
custContentId
zoom1
simple0
custContentId6183060345
pageId5873176651
6183060345lbox1
diagramDisplayNameformulieren-sequence.drawio
hiResPreview0
baseUrlhttps://vlaamseoverheid.atlassian.net/wiki
imgPageId5873176651
diagramNameform-lifecycles.drawioimgPageId5873176651
pCenter1
aspectp2fdbZiMIzNi8GB3PEac 1
width881841
includedDiagram1
aspectHashaab47bcc5c555fae86620677b51a64bd056d95f0
linksauto
tbstyletop
height1021
...
 Info
Het is aangeraden een informatieve pagina te tonen waarbij de gebruiker expliciet de aanvraag moet te 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. 
...
 Note
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 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. 
...
 Info
Idealiter is het dossier ook direct zichtbaar als ingediende aanvraag. Dit is echter afhankelijk van de flow die bij het loket gevolgd wordt voor om de integratie met de dossierstatusinformatiedossierstatusinformatie (DOSIS) te integreren. 
 Code Block
languagejs
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"
})
...