...

• 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

...

...

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:

...

}

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

  , en de respectievelijke testdomeinen.

• Een tweede item met extensies:

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

  • provider id en name: dit zijn de OVO-code en de naam van de bevoegde overheid

  • URLs die niet onder http://burgerprofiel.be vallen, hiervoor is een thirdPartyCookieApi verplicht (zie Aanvraagformulieren - 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.

...

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

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 Aanvraagformulieren - Authenticatie via Single Sign-on (SSO)

Afhandeling foutberichten

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

Minimale data voor een eenvoudige aansluiting

Voor een eenvoudigere configuratie kan Team Aansluitingen een configuratie vragen die bij de formulierenaggregator kan worden aangemaakt.

Minimale data nodig voor een eenvoudige aansluiting (met IPDC), die opent in een nieuwe tab:

{
  "_links": {
      "fallback": { "href": "willekeurig-eloket.vlaanderen.be/url-naar-formulier-met-global-header" },
   },
  "id": "ee5d582c-5c94-4f62-9f6b-424c41e129f7",
  "productId": "1456"
}

Door alleen de fallback mee te geven, opent dit formulier in een nieuwe tab. Verder zijn hier alleen de volgende elementen vereist:

• Een unieke id om een random UUID te genereren (deze heeft verder geen betekenis in de set-up)

• Een productId

Minimale data nodig voor een eenvoudige aansluiting die onder *.vlaanderen.be valt (first-party).

...

"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": "willekeurig-elokethttps://formulieren.loket.vlaanderen.be/submission/url80a5af1f-naar8786-formulier4124-met-global-header" },
   },
  "id": "ee5d582c-5c94-4f62-9f6b-424c41e129f7",
  "productId": "1456"
}

De embed-property zorgt ervoor dat dit formulier kan worden geëmbed in Mijn Burgerprofiel

Voorbeeld eenvoudige aansluiting voor Fayatbeurs

Opent in een nieuwe tab (dus geen embed in Mijn Burgerprofiel)

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" },
     {         "_links": {
          "fallbackssoTokenRegistrationApi": { "href": "https://fayatbeurzenformulieren.loket.vlaanderen.be/api/v1/temp-sso-token" },
          },
          "idsso": "9a283d7e-c350-45b5-aa14-0f5639d45425",{
        "title": "Fayatbeurs",         "provider"audience": {"d9da076d-3069-481c-9fa7-783ccb84ad61"
          },
          "id": "OVO00003280a5af1f-8786-4124-9d60-652e53428a8d",
          "nameproductId": "Departement1390"
 Kanselarij en Buitenlandse Zaken"      "nisCode": "23096",
 },         "descriptionstatus": "Wiltin-progress",
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."
      }      "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

...

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

...