Bekijk Source

Inleiding

De OfferteService een cruciaal onderdeel van het http://Mijnaansluiting.nl platform, is ontworpen met een sterke nadruk op gebruiksvriendelijkheid. Deze service stelt gebruikers in staat om hun aanvragen snel en efficiënt in te dienen en te beheren.

Transformatie naar REST-gebaseerde Service

De overgang naar een REST-gebaseerde service heeft aanzienlijke verbeteringen met zich meegebracht:

Meer flexibiliteit en schaalbaarheid
Betere compatibiliteit met moderne architecturen, middleware en netwerken

Deze verbeteringen hebben een directe positieve impact op de gebruikerservaring, verkorten de doorlooptijd van aanvragen en verhogen de algehele efficiëntie van netwerkbeheer. Door deze transitie kunnen gebruikers nu profiteren van een robuustere en toekomstbestendige infrastructuur, wat resulteert in een meer gestroomlijnd en betrouwbaar offerteproces

Inhoudsopgave

Handleiding

1. POST /offerte

Beschrijving: Dit endpoint wordt gebruikt om een nieuwe offerte aan te maken. De offerte bevat een PDF-bestand en bijbehorende metadata.

Doel: Creëer een nieuwe offerte item voor een aantal aansluitingen bij een een aanvraag.

sequenceDiagram
    participant client
    participant auth
    participant gateway
    participant offerte service
    participant blob storage
    participant event broker

    client->>auth: authenticatie
    auth->>client: token

    client->>offerte service: payload + (token)
    offerte service ->> client: OK + response

Headers

Header Name	Verplicht	Type	Beschrijving
Authorization	Ja	String	JWT Bearer token voor authenticatie
Content-Type	Ja	String	`application/json`

Request Body

Parameter	Verplicht	Type	Beschrijving
aanvraagId	Ja	Integer	De unieke ID van de aanvraag.
offerteReferentie	Nee	String	Een referentie voor de offerte. Max lengte: 100 karakters.
organisatieCode	Nee	String	Code van de organisatie. Max lengte: 10 karakters.
disciplineIDs	Nee	Array	Een lijst van discipline IDs gerelateerd aan de offerte.
omschrijving	Nee	String	Een omschrijving van de offerte.
automatischAanvraagAfronden	Nee	Boolean	Of de aanvraag automatisch moet worden afgerond na de offerte.
vervalDatum	Nee	DateTime	De datum waarop de offerte vervalt.
bestandsnaam	Nee	String	De naam van het offertebestand inclusief extensie. Max lengte: 35 karakters.
mimeType	Nee	String	Het MIME-type van het bestand. Standaardwaarde: `application/pdf`. Max lengte: 100 karakters.

codevoorbeeld (curl)

curl -X POST https://services-acc.mijnaansluiting.nl/services/offerte \
-H "Authorization: Bearer {JWT_Token}" \
-H "Content-Type: application/json" \
-d '{
  "aanvraagId": {aanvraagId},
  "offerteReferentie": "{offerteReferentie}",
  "organisatieCode": "{organisatieCode}",
  "disciplineIDs": [{disciplineID1}, {disciplineID2}],
  "omschrijving": "{omschrijving}",
  "automatischAanvraagAfronden": {true/false},
  "vervalDatum": "{vervalDatum}",
  "bestandsnaam": "{bestandsnaam}",
  "mimeType": "{mimeType}"
}'

2. GET / offerte

Korte beschrijving: Dit endpoint wordt gebruikt om een lijst van offertes op te halen die voldoen aan de opgegeven zoekcriteria.

Doel: Het zoeken en filteren van offertes op basis van verschillende parameters, zoals aanvraag-ID, referentie, processtatus en datum.

sequenceDiagram
    participant client
    participant auth
    participant gateway
    participant offerte service
    participant blob storage
    participant event broker

    client->>auth: authenticatie
    auth->>client: token

    client->>offerte service: payload + (token)
    offerte service ->> client: OK + response

Query Parameters

Parameter	Verplicht	Type	Beschrijving
offerteReferentie	Nee	String	De referentie van de offerte die gezocht wordt.
aanvraagId	Nee	Integer	De unieke ID van de aanvraag.
procesStatus	Nee	String	De huidige status van de offerte.
beginAanmaakDatum	Nee	String	Begin van het aanmaakdatum van de offerte in `YYYY-MM-DD` formaat.
eindAanmaakDatum	Nee	String	Eind van het aanmaakdatum van de offerte in `YYYY-MM-DD` formaat.
beginWijzigingsDatum	Nee	String	Begin van de wijzigingsdatum van de offerte in `YYYY-MM-DD` formaat.
eindWijzigingsDatum	Nee	String	Eind van de wijzigingsdatum van de offerte in `YYYY-MM-DD` formaat.
beginVervalDatum	Nee	String	Begin van de vervaldatum van de offerte in `YYYY-MM-DD` formaat.
eindVervalDatum	Nee	String	Eind van de vervaldatum van de offerte in `YYYY-MM-DD` formaat.
skip	Nee	Integer	Het aantal over te slaan resultaten (voor paginering).
take	Nee	Integer	Het aantal resultaten om terug te geven (voor paginering).

Headers

Header Name	Verplicht	Type	Beschrijving
Authorization	Ja	String	JWT Bearer token voor authenticatie
Content-Type	Nee	String	`application/json`

Response

Succes (200 OK)

{
  "count": {aantal},
  "skip": {skip},
  "take": {take},
  "items": [
    {
      "offerteReferentie": "{offerteReferentie}",
      "organisatieCode": "{organisatieCode}",
      "aanvraagID": {aanvraagId},
      "disciplineIDs": [{disciplineID1}, {disciplineID2}],
      "url": "{url}",
      "omschrijving": "{omschrijving}",
      "inkoopNummer": "{inkoopNummer}",
      "automatischAanvraagAfronden": {true/false},
      "bestandsnaam": "{bestandsnaam}",
      "mimeType": "{mimeType}",
      "aanmaakDatum": "{aanmaakDatum}",
      "vervalDatum": "{vervalDatum}",
      "wijzigingsDatum": "{wijzigingsDatum}"
    }
  ]
}

codevoorbeeld (curl)

curl -X GET https://services-acc.mijnaansluiting.nl/services/offerte \
-H "Authorization: Bearer {JWT_Token}" \
-G \
--data-urlencode "offerteReferentie={offerteReferentie}" \
--data-urlencode "aanvraagId={aanvraagId}" \
--data-urlencode "procesStatus={procesStatus}" \
--data-urlencode "beginAanmaakDatum={beginAanmaakDatum}" \
--data-urlencode "eindAanmaakDatum={eindAanmaakDatum}" \
--data-urlencode "beginWijzigingsDatum={beginWijzigingsDatum}" \
--data-urlencode "eindWijzigingsDatum={eindWijzigingsDatum}" \
--data-urlencode "beginVervalDatum={beginVervalDatum}" \
--data-urlencode "eindVervalDatum={eindVervalDatum}" \
--data-urlencode "skip={skip}" \
--data-urlencode "take={take}"

3. POST`/offerte/{aanvraagId}/referentie/{offerteReferentie}`

Korte beschrijving Deze endpoint wordt gebruikt om een offertebestand te uploaden voor een specifieke aanvraag-ID en offertereferentie.

Doel Het uploaden van een offertebestand gekoppeld aan een bestaande aanvraag en referentie. Dit bestand kan bijvoorbeeld een PDF-document van de offerte zijn

sequenceDiagram
    participant client
    participant auth
    participant gateway
    participant offerte service
    participant blob storage
    participant event broker

    client->>auth: authenticatie
    auth->>client: token

    client->>offerte service: payload + (token)
    offerte service ->> client: OK + response

URL-Parameters

Parameter	Verplicht	Type	Beschrijving
aanvraagId	Ja	Integer	De unieke ID van de aanvraag.
offerteReferentie	Ja	String	De referentie van de offerte waarvoor het bestand wordt geüpload.

Headers

Header Name	Verplicht	Type	Beschrijving
Authorization	Ja	String	JWT Bearer token voor authenticatie
Content-Type	Ja	String	`multipart/form-data`

Request Parameters

Parameter	Verplicht	Type	Beschrijving
netbeheerderCode	Ja	String	Code van de netbeheerder
id	Ja	String	Unieke ID voor het document
collectionId	Ja	String	Unieke ID van de collectie waar het bestand bij hoort

Request Body

Parameter	Verplicht	Type	Beschrijving
file	Ja	Binary	Het offertebestand dat geüpload moet worden.

codevoorbeeld (curl)

curl -X POST https://services-acc.mijnaansluiting.nl/services/offerte/{aanvraagId}/referentie/{offerteReferentie} \
-H "Authorization: Bearer {JWT_Token}" \
-H "Content-Type: multipart/form-data" \
-F "file=@{pad_naar_bestand}" \
--form "netbeheerderCode={netbeheerderCode}" \
--form "id={documentId}" \
--form "collectionId={collectionId}"

4. GET /offerte/{aanvraagId}/referentie/{offerteReferentie}

Deze methode stelt gebruikers in staat om de statussen vaan aansluitingen een specifieke offerte bij te werken. Het offerte-ID moet in de URL worden gespecificeerd, en de wijzigingen worden doorgegeven in de body van het verzoek.

Het /offerte endpoint met {offerteId} met de PATCH-methode biedt de functionaliteit om de status van aansluitingen in een een offerte te wijzigen.

sequenceDiagram
    participant client
    participant auth
    participant gateway
    participant aanvraag service
    participant event broker

    client->>auth: authenticatie
    auth->>client: token

    client->>aanvraag service: patch + aanvraagid + jsonbody + (token)
    aanvraag service ->> client: ok

URL-Parameters

Parameter	Verplicht	Type	Beschrijving
offerteId	Ja	Integer	De unieke ID van de offerte die moet worden bijgewerkt.

Headers

Header Name	Verplicht	Type	Beschrijving
Authorization	Ja	String	JWT Bearer token voor authenticatie
Content-Type	Ja	String	`application/json`

Request Body

Het verzoeklichaam bevat een array van statusobjecten die moeten worden bijgewerkt:

Parameter	Verplicht	Type	Beschrijving
offerteReferentie	Ja	String	De referentie van de offerte.
organisatieCode	Ja	String	Code van de organisatie die de offerte heeft uitgebracht.
procesStatus	Ja	String	De huidige status van de offerte. Geldige waarden: "4", "4.1", "4.2", "5".

codevoorbeeld (curl):

curl -X PATCH https://services-acc.mijnaansluiting.nl/services/offerte/{offerteId}/bulk \
-H "Authorization: Bearer {JWT_Token}" \
-H "Content-Type: application/json" \
-d '[
  {
    "offerteReferentie": "{offerteReferentie1}",
    "organisatieCode": "{organisatieCode1}",
    "procesStatus": "{procesStatus1}"
  },
  {
    "offerteReferentie": "{offerteReferentie2}",
    "organisatieCode": "{organisatieCode2}",
    "procesStatus": "{procesStatus2}"
  }
]'

8. HTTP return status codes

Statuscode	Betekenis	Beschrijving
200	OK	Het verzoek is geslaagd.
201	Created	Het verzoek is geslaagd en er is een nieuwe resource aangemaakt.
204	No Content	Het verzoek is geslaagd, maar er is geen inhoud om terug te sturen.
400	Bad Request	De server kon het verzoek niet begrijpen vanwege een onjuiste syntax.
401	Unauthorized	Authenticatie is vereist en is mislukt of nog niet verstrekt.
403	Forbidden	De server begrijpt het verzoek, maar weigert het uit te voeren.
404	Not Found	De gevraagde resource kon niet worden gevonden op de server.
500	Internal Server Error	De server heeft een fout gemaakt en kon het verzoek niet voltooien.
502	Bad Gateway	De server ontving een ongeldige reactie van de upstream-server.
503	Service Unavailable	De server is momenteel niet beschikbaar (door overbelasting of onderhoud).

Inleiding

Inhoudsopgave

Handleiding

1. POST /offerte

Headers

Request Body

codevoorbeeld (curl)

2. GET / offerte

Query Parameters

Headers

Response

Succes (200 OK)

codevoorbeeld (curl)

3. POST/offerte/{aanvraagId}/referentie/{offerteReferentie}

URL-Parameters

Headers

Request Parameters

Request Body

codevoorbeeld (curl)

4. GET /offerte/{aanvraagId}/referentie/{offerteReferentie}

URL-Parameters

Headers

Request Body

codevoorbeeld (curl):

8. HTTP return status codes

Swagger API specificatie

3. POST`/offerte/{aanvraagId}/referentie/{offerteReferentie}`