Versions Compared

Old Version 47

changes.mady.by.user Heidi Vannevel

Saved on

compared with

New Version 48

changes.mady.by.user Heidi Vannevel

Saved on

Key

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

...

REST API

GET /api/v1/forms

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": "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" ]

...

 },

...

...
      ]
    }

...

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

    • 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

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.

...

}

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:

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 *

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

InfoBij meerdere productcodes

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/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 6180832603/Aanvraagformulieren+-+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 - 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/

6180832603

6117854932/

Aanvraagformulieren+-+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 - 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

Voor formulieren die voor één of meerdere lokale besturen beschikbaar zijn.

  • 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": [ "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

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

Voor formulieren die voor één of meerdere lokale besturen beschikbaar zijn.

  • 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": [ "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

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

    Bij meerdere niscodes wordt de parameter meerdere keren herhaald:
    (?productIdnisCode=123412345&productIdnisCode=567867890&productIdnisCode=9752)

    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.


    GET /api/v1/forms-submissions (optioneel)

    Code Block
    breakoutModefull-width
    {
    "_links": {
      "self": { "href": "https://fl-test-eportal.skryv.com/api/v1/form-submissions?limit=10&offset=0" },
      "first": { "href": "https://fl-test-eportal.skryv.com/api/v1/form-submissions?limit=10&offset=0" },
      "next": { "href": "https://fl-test-eportal.skryv.com/api/v1/form-submissions?limit=10&offset=10" },
      "last": { "href": "https://fl-test-eportal.skryv.com/api/v1/form-submissions?limit=10&offset=20" },
    },
    "_pageMetadata": {
      "offset": 0,
      "size": 10,
      "totalItems": 26
    },
   "_embedded": {
      "items": [
        {
          "_links": {
              "embed": { "href": "https://fl-test-eportal.skryv.com/#/80a5af1f-8786-4124-9d60-652e53428a8d" },
              "fallback": { "href": "https://fl-test-eportal.skryv.com/#/80a5af1f-8786-4124-9d60-652e53428a8d" },
              "form": { "href": "https://fl-test-eportal.skryv.com/#/dossier-info/8350d7ed-ae18-4525-ac2c-abaa49656e3c" },
              "thirdPartyCookieApi": { "href": "https://fl-test-eportal.skryv.com/api/v1/third_party_cookies" }
          },
          "id": "80a5af1f-8786-4124-9d60-652e53428a8d",
          "formId": "8350d7ed-ae18-4525-ac2c-abaa49656e3c",
          "status": "in-progress",
          "provider": {
            "id": "OVO000106",
            "name": "Wonen-Vlaanderen",
          },
          "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

    • 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

    ...