API documentation Bronhouderportaal BRO

Met deze API is het mogelijk om volledig geautomatiseerd brondocumenten aan te levern aan het Bronhouderportaal BRO. De API is RESTful opgezet, waarbij de volgende resource is gedefinieerd: Levering.

In vogelvlucht werkt de API door eerst een levering aan te maken door een POST request te sturen met als body de XML van het brondocument. Vervolgens kan de status van de levering periodiek worden opgevraagd, waarbij uiteindelijk een BRO-ID teruggeven wordt.

Ter ondersteuning van de kwaliteitscontrole van een levering is het mogelijk om een levering en/of de brondocumenten van een levering te verrijken met extra gegevens.

Daarnaast kunnen brondocumenten gevalideerd worden, zonder dat hiervoor een levering wordt aangemaakt. Deze functionaliteit is tevens geschikt om te testen of de koppeling met de API correct functioneert.

Dit levert o.a. de volgende API endpoints op:

  • POST /bpbro-frontend/external/validatie HTTP/1.1 [1]
  • POST /bpbro-frontend/external/leveringen HTTP/1.1 [2]
  • GET /bpbro-frontend/external/leveringen/0000000001 HTTP/1.1 [3]
Alle endpoints worden hieronder in meer details beschreven.

Authenticatie

Om van de API gebruik te kunnen maken, dient een aanlevertoken te worden aangemaakt in het Bronhouderportaal. Dit aanlevertoken bestaat uit twee delen: een token username en het daadwerkelijke token (password) zelf. Let op dat het password eenmalig wordt verstrekt. Het password is in een later stadium niet meer op te vragen en is ook niet bekend binnen het Bronhouderportaal.

De API gebruikt HTTP basic authentication. Dit betekent dat bij elk request een Authorization header meegestuurd moet worden bestaande uit de Base64 encoding van de string USERNAME:PASSWORD waarbij:

USERNAME
de token username (e.g. 0dce6fc98256|123456789|1234)
PASSWORD
het eenmalig gegenereerde token (e.g. cf573933d8be536a8ad18edfe4f69bd010f944a686abf1f6b13c5d2a455cdc32)

Succesvol kunnen authenticateren kan getest worden door een validatie verzoek te sturen via het validatie endpoint van API. Dit endpoint valideert brondocumenten zonder de betreffende omgeving te vervuilen met testleveringen.

Valideren

De API kan brondocumenten valideren zonder dat hiervoor een levering hoeft te worden aagemaakt. De aanroep is vrijwel identiek aan het aanmaken van een levering, met als grootste verschil dat bij het aanmaken van een levering de brondocumenten asynchroon worden gevalideerd, terwijl hier het valideren synchroon plaatsvindt. Het response geeft dus meteen aan of het brondocument valide is, en zoniet, wat de gevonden problemen zijn.

HTTP request:

  POST /bpbro-frontend/external/validatie HTTP/1.1
  Host: acc.bronhouderportaal-bro.nl
  Content-Type: application/xml
  Authorization: Basic OTRlOWJjOGQ3ODM0fDI3MzY0MTc4fC0yOmQ0Y2IyNjU2NmIyYjhmZmJhZjQzYzlmODQ5YTM4ZTIxNTM3OTExNWFmZmZhMWIzMmE5MWVjZWUzM2M2ODNjZjQ=
              
HTTP request body:

  <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <ns:registrationRequest xmlns:ns="...">
    <ns1:requestReference>0001 Uniek request ref</ns1:requestReference>
    <ns1:deliveryAccountableParty>12345678</ns1:deliveryAccountableParty>
    <ns1:qualityRegime>IMBRO</ns1:qualityRegime>
    <ns:sourceDocument>
      <ns:CPT>
          ...
      </ns:CPT>
    </ns:sourceDocument>
  </ns:registrationRequest>
              

HTTP response:

  HTTP/1.1 200 Success
  Content-Type: application/json
  Content-Length: 813
              

HTTP response body:

  {
    "status": "NIET_VALIDE",
    "errors": ["Put geschiedenis.inrichtingsdatum put (WellHistory.wellConstructionDate) = (2117-12-31, JJJJ-MM-DD) waarde is niet correct: mag niet in de toekomst liggen."]
  }
              

Voorbeeld aanroep met curl:

  curl https://acc.bronhouderportaal-bro.nl/bpbro-frontend/external/validatie \
    --verbose \
    --user "0dce6fc98256|123456789|1234:cf573933d8be536a8ad18edfe4f69bd010f944a686abf1f6b13c5d2a455cdc32" \
    --header "Content-Type: application/xml" \
    --data "@gmwRegistrationRequest.xml"
                

Levering aanmaken

Een brondocument aanleveren gaat door een POST request naar het Levering resource endpoint te sturen met als body het aan te leveren XML bestand. Het resultaat is een aangemaakte Levering met daarin één Brondocument. De Location header geeft aan hoe de status van de aangemaakt levering kan worden opgevraagd.

HTTP request:

  POST /bpbro-frontend/external/leveringen HTTP/1.1
  Host: acc.bronhouderportaal-bro.nl
  Content-Type: application/xml
  Authorization: Basic OTRlOWJjOGQ3ODM0fDI3MzY0MTc4fC0yOmQ0Y2IyNjU2NmIyYjhmZmJhZjQzYzlmODQ5YTM4ZTIxNTM3OTExNWFmZmZhMWIzMmE5MWVjZWUzM2M2ODNjZjQ=
            
HTTP request body:

  <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <ns:registrationRequest xmlns:ns="...">
    <ns1:requestReference>0001 Uniek request ref</ns1:requestReference>
    <ns1:deliveryAccountableParty>12345678</ns1:deliveryAccountableParty>
    <ns1:qualityRegime>IMBRO</ns1:qualityRegime>
    <ns:sourceDocument>
      <ns:CPT>
          ...
      </ns:CPT>
    </ns:sourceDocument>
  </ns:registrationRequest>
            

HTTP response:

  HTTP/1.1 201 Created
  Location: https://acc.bronhouderpotaal-bro.nl/bpbro-frontend/external/leveringen/0000000001
            

Voorbeeld aanroep met curl:

  curl https://acc.bronhouderportaal-bro.nl/bpbro-frontend/external/leveringen \
    --verbose \
    --user "0dce6fc98256|123456789|1234:cf573933d8be536a8ad18edfe4f69bd010f944a686abf1f6b13c5d2a455cdc32" \
    --header "Content-Type: application/xml" \
    --data "@gmwRegistrationRequest.xml"
              

Standaard wordt voor het aangeleverde Brondocument een willekeurige bestandsnaam gegenereerd. Het is mogelijk om een zelfgekozen bestandsnaam te specificeren in het aanleververzoek door het meegeven van een filename query parameter. Het is vereist dat de meegegeven bestandsnaam eindigt op de extensie .xml In dit geval wordt de aanroep: /bpbro-frontend/external/leveringen?filename=zelf-gekozen-bestandsnaam.xml

Status opvragen van een levering

Een levering ondergaat een aantal verschillende stadia. Voorbeelden zijn: Aangemaakt, Goedgekeurd, Geaccordeerd, etc. Voor een complete lijst, zie de gebruikershandleiding van het Bronhouderportaal. Met behulp van dit endpoint kan de status van een levering worden opgevraagd. Deze informatie kan steeds anders zijn totdat de levering een eindstatus (zoals Doorgeleverd) heeft bereikt.

Bij de details van de levering wordt ook informatie over de inhoud van de levering, oftwel de brondocumenten, teruggegeven. Zodra de levering is doorgeleverd krijgt het brondocument uiteindelijk een Bro-ID van de BRO. Verder is het brondocument te identificeren aan de hand de bestandsnaam of het requestReference dat uit de XML afkomstig is.

HTTP request:

  GET /bpbro-frontend/external/leveringen/0000000001 HTTP/1.1
  Host: acc.bronhouderportaal-bro.nl
  Authorization: Basic MGRjZTZmYzk4MjU2fDI3MzY0MTc4fC0yOmNmNTczOTMzZDhiZTUzNmE4YWQxOGVkZmU0ZjY5YmQwMTBmOTQ0YTY4NmFiZjFmNmIxM2M1ZDJhNDU1Y2RjMzI=
            

HTTP response:

  HTTP/1.1 200 OK
  Content-Type: application/json
  Content-Length: 813
              

HTTP response body (doorgeleverd aan de Landelijke Voorzieningen):

  {
    "identifier": "0000000001",
    "status": "DOORGELEVERD",
    "lastChanged": "2018-03-15T09:41:36.856",
    "brondocuments": [
      {
        "filename" : "filename1.xml",
        "requestReference" : "unique-request-ref-123",
        "status": "OPGENOMEN_LVBRO",
        "lastChanged": "2018-03-15T09:41:38.755",
        "broId": "GMW000000000001"
      }
    ]
  }
            

HTTP response body (validatiefouten):

    {
      "identifier": "0000000001",
      "status": "GEVALIDEERD",
      "lastChanged": "2018-03-15T09:41:36.856",
      "brondocuments": [
        {
          "filename" : "filename1.xml",
          "requestReference" : "unique-request-ref-123",
          "status": "NIET_VALIDE",
          "lastChanged": "2018-03-15T09:41:38.755",
          "errors": [
            "Put geschiedenis.inrichtingsdatum put (WellHistory.wellConstructionDate) = (2117-12-31, JJJJ-MM-DD) waarde is niet correct: mag niet in de toekomst liggen."
          ]
        }
      ]
    }
              

Voorbeeld aanroep met curl:

  curl https://acc.bronhouderportaal-bro.nl/bpbro-frontend/external/leveringen/0000000001 \
    --verbose \
    --user "0dce6fc98256|123456789|1234:cf573933d8be536a8ad18edfe4f69bd010f944a686abf1f6b13c5d2a455cdc32"
                

Leveringen van de eigen organisatie opvragen

Via dit endpoint kunnen de identifiers van alle leveringen van de eigen organisatie opgevraagd worden. De query parameter actie filtert het resultaat: actie=CONTROLEREN geeft bijvoorbeeld alleen de identifiers van de leveringen met als volgende status 'Controleren' terug. Mogelijke waarden voor actie zijn VALIDEREN, CONTROLEREN, VASTSTELLEN, DOORLEVEREN en ARCHIVEREN.

HTTP request:

  GET /bpbro-frontend/external/leveringen?actie=CONTROLEREN HTTP/1.1
  Host: acc.bronhouderportaal-bro.nl
  Authorization: Basic MGRjZTZmYzk4MjU2fDI3MzY0MTc4fC0yOmNmNTczOTMzZDhiZTUzNmE4YWQxOGVkZmU0ZjY5YmQwMTBmOTQ0YTY4NmFiZjFmNmIxM2M1ZDJhNDU1Y2RjMzI=
                    

HTTP response:

  HTTP/1.1 200 OK
  Content-Type: application/json
  Content-Length: 40
                    

HTTP response body:

  ["0000000001","0000000004","0000000012"]
                    

Voorbeeld aanroep met curl:

  curl https://acc.bronhouderportaal-bro.nl/bpbro-frontend/external/leveringen?actie=CONTROLEREN \
    --verbose \
    --user "0dce6fc98256|123456789|1234:cf573933d8be536a8ad18edfe4f69bd010f944a686abf1f6b13c5d2a455cdc32"
                

Levering verrijken

Na aanmaak van een levering kan een (intern) controleur de levering goedkeuren of afkeuren. Ten behoeve van deze controle kunnen er gegevens worden toegevoegd aan de levering of aan de brondocumenten van de levering. Het gaat hierbij om notities (tekst) en/of bijlagen (bestanden).

Notities toevoegen aan een levering

Er kunnen 3 types notities worden toegevoegd: info-, warning- en error-notities. Voor elk type is een apart endpoint (/info, /warnings en /errors).

HTTP request voor een info-notitie:

  POST /bpbro-frontend/external/leveringen/0000000001/info HTTP/1.1
  Host: acc.bronhouderportaal-bro.nl
  Content-Type: text/plain
  Authorization: Basic MGRjZTZmYzk4MjU2fDI3MzY0MTc4fC0yOmNmNTczOTMzZDhiZTUzNmE4YWQxOGVkZmU0ZjY5YmQwMTBmOTQ0YTY4NmFiZjFmNmIxM2M1ZDJhNDU1Y2RjMzI=
                    

HTTP request voor een warning-notitie:

  POST /bpbro-frontend/external/leveringen/0000000001/warnings HTTP/1.1
  Host: acc.bronhouderportaal-bro.nl
  Content-Type: text/plain
  Authorization: Basic MGRjZTZmYzk4MjU2fDI3MzY0MTc4fC0yOmNmNTczOTMzZDhiZTUzNmE4YWQxOGVkZmU0ZjY5YmQwMTBmOTQ0YTY4NmFiZjFmNmIxM2M1ZDJhNDU1Y2RjMzI=
                    

HTTP request voor een error-notitie:

  POST /bpbro-frontend/external/leveringen/0000000001/errors HTTP/1.1
  Host: acc.bronhouderportaal-bro.nl
  Content-Type: text/plain
  Authorization: Basic MGRjZTZmYzk4MjU2fDI3MzY0MTc4fC0yOmNmNTczOTMzZDhiZTUzNmE4YWQxOGVkZmU0ZjY5YmQwMTBmOTQ0YTY4NmFiZjFmNmIxM2M1ZDJhNDU1Y2RjMzI=
                    

HTTP request body:

  Tekstuele notitie
                    

HTTP response:

  HTTP/1.1 204 No Content
                    

Voorbeeld aanroep met curl:

  curl https://acc.bronhouderportaal-bro.nl/bpbro-frontend/external/leveringen/0000000001/info \
    --verbose \
    --user "0dce6fc98256|123456789|1234:cf573933d8be536a8ad18edfe4f69bd010f944a686abf1f6b13c5d2a455cdc32" \
    --header "Content-Type: text/plain" \
    --data "@mijn-notitie.txt"
                

Notities toevoegen aan een brondocument

Het toevoegen van notities aan brondocumenten werkt op dezelfde manier als het toevoegen van notities aan een levering.

HTTP request voor een info-notitie:

  POST /bpbro-frontend/external/brondocumenten/24/info HTTP/1.1
  Host: acc.bronhouderportaal-bro.nl
  Content-Type: text/plain
  Authorization: Basic MGRjZTZmYzk4MjU2fDI3MzY0MTc4fC0yOmNmNTczOTMzZDhiZTUzNmE4YWQxOGVkZmU0ZjY5YmQwMTBmOTQ0YTY4NmFiZjFmNmIxM2M1ZDJhNDU1Y2RjMzI=
                    

HTTP request voor een warning-notitie:

  POST /bpbro-frontend/external/brondocumenten/24/warnings HTTP/1.1
  Host: acc.bronhouderportaal-bro.nl
  Content-Type: text/plain
  Authorization: Basic MGRjZTZmYzk4MjU2fDI3MzY0MTc4fC0yOmNmNTczOTMzZDhiZTUzNmE4YWQxOGVkZmU0ZjY5YmQwMTBmOTQ0YTY4NmFiZjFmNmIxM2M1ZDJhNDU1Y2RjMzI=
                    

HTTP request voor een error-notitie:

  POST /bpbro-frontend/external/brondocumenten/24/errors HTTP/1.1
  Host: acc.bronhouderportaal-bro.nl
  Content-Type: text/plain
  Authorization: Basic MGRjZTZmYzk4MjU2fDI3MzY0MTc4fC0yOmNmNTczOTMzZDhiZTUzNmE4YWQxOGVkZmU0ZjY5YmQwMTBmOTQ0YTY4NmFiZjFmNmIxM2M1ZDJhNDU1Y2RjMzI=
                    

HTTP request body:

  Tekstuele notitie
                    

HTTP response:

  HTTP/1.1 204 No Content
                    

Voorbeeld aanroep met curl:

  curl https://acc.bronhouderportaal-bro.nl/bpbro-frontend/external/brondocumenten/24/info \
    --verbose \
    --user "0dce6fc98256|123456789|1234:cf573933d8be536a8ad18edfe4f69bd010f944a686abf1f6b13c5d2a455cdc32" \
    --header "Content-Type: text/plain" \
    --data "@mijn-notitie.txt"
                

Bijlagen toevoegen aan een levering

Dit endpoint is bedoeld voor het toevoegen van bestanden (bijvoorbeeld .pdf, .docx of .zip bestanden) aan een levering. Het gaat hierbij om bestanden die de kwaliteitscontroleur kan gebruiken bij het beoordelen van de levering.

HTTP request:

  POST /bpbro-frontend/external/leveringen/0000000001/attachments/mijn-bijlage.pdf HTTP/1.1
  Host: acc.bronhouderportaal-bro.nl
  Content-Type: application/octet-stream
  Authorization: Basic MGRjZTZmYzk4MjU2fDI3MzY0MTc4fC0yOmNmNTczOTMzZDhiZTUzNmE4YWQxOGVkZmU0ZjY5YmQwMTBmOTQ0YTY4NmFiZjFmNmIxM2M1ZDJhNDU1Y2RjMzI=
                    

HTTP request body:

  Binaire data
                    

HTTP response:

  HTTP/1.1 204 No Content
                    

Voorbeeld aanroep met curl:

  curl https://acc.bronhouderportaal-bro.nl/bpbro-frontend/external/leveringen/0000000001/attachments/mijn-bijlage.pdf \
    --verbose \
    --user "0dce6fc98256|123456789|1234:cf573933d8be536a8ad18edfe4f69bd010f944a686abf1f6b13c5d2a455cdc32" \
    --header "Content-Type: application/octet-stream" \
    --data-binary "@mijn-bijlage.pdf"
                

Bijlagen toevoegen aan een brondocument

Het toevoegen van bijlagen aan een brondocument werkt hetzelfde als het toevoegen van bijlagen aan een levering.

HTTP request:

  POST /bpbro-frontend/external/brondocumenten/24/attachments/mijn-bijlage.pdf HTTP/1.1
  Host: acc.bronhouderportaal-bro.nl
  Content-Type: application/octet-stream
  Authorization: Basic MGRjZTZmYzk4MjU2fDI3MzY0MTc4fC0yOmNmNTczOTMzZDhiZTUzNmE4YWQxOGVkZmU0ZjY5YmQwMTBmOTQ0YTY4NmFiZjFmNmIxM2M1ZDJhNDU1Y2RjMzI=
                    

HTTP request body:

  Binaire data
                    

HTTP response:

  HTTP/1.1 204 No Content
                    

Voorbeeld aanroep met curl:

  curl https://acc.bronhouderportaal-bro.nl/bpbro-frontend/external/brondocumenten/24/attachments/mijn-bijlage.pdf \
    --verbose \
    --user "0dce6fc98256|123456789|1234:cf573933d8be536a8ad18edfe4f69bd010f944a686abf1f6b13c5d2a455cdc32" \
    --header "Content-Type: application/octet-stream" \
    --data-binary "@mijn-bijlage.pdf"
                

Error afhandeling

Fouten worden op een uniforme manier teruggegeven volgens RFC 7807. De HTTP response code categoriseert de fout en de response body geeft meer gedetailleerde informatie weer. Hieronder is een beschrijving te zien van het JSON formaat waarin foutinformatie wordt teruggegeven.

Voorbeeld HTTP error response:

  HTTP/1.1 401 Unauthorized
  Content-Type: application/problem+json
  Content-Length: 173
                

Voorbeeld HTTP error response body:

  {
    "type": "https://www.bronhouderportaal-bro.nl/problems/authentication-problem",
    "title": "authenticatie fout",
    "status": 401,
    "detail": "No token found for authorization header."
  }