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.

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

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