/
Offerte Service API

Offerte Service API

Owned by Caspar Kleijne
Last updated: 19,03,25 by Aidan Mauricio
6 min read

 

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.

Via de REST-services wordt de offerte-proces voor de netbeheerder in 2 stappen gedaan. Eerst wordt er een offerte-concept aangemaakt en daarna wordt de offertebestand geüpload en wordt de offerte aangeboden aan de aanvrager. Bij het aanmaken van de offerte-concept krijgt de offerte een status 4c en is deze alleen zichtbaar voor de netbeheerder. Nadat de offerte pdf geüpload is, dan krijgt de offerte de status 4 en is deze zichtbaar aan de aanvrager.

De aansluitingen via disciplineIds die meegegeven worden krijgen een status 4 als een offerte is aangeboden aan de aanvrager. De aanvrager kan dan de offerte goedkeuren of weigeren en hierbij krijgen de aansluitingen respectievelijk de statussen 5 en 4.1. Voordat de aanvrager de offerte goedkeurt of weigert kan de netbeheerder ter aller tijde de offerte annuleren en krijgen de aansluitingen de status 4.2.

Er zit een maximale grootte aan de voorwaarden en de offertebestand. Samen mogen deze niet groter zijn dan 10MB.

Handleiding

1. POST /offerte

Beschrijving: Dit endpoint wordt gebruikt om een nieuwe offerte-concept aan te maken.

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

 

Headers

Header Name

Verplicht

Type

Beschrijving

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

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

Ja

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.

voorwaardeCodes

Nee

Array

Een lijst van voorwaardeCodes die actief zijn gedurende de looptijd van de offerte.

goedkeuringsProces

Nee

String

Het proces van goedkeuren. Keuze uit “Digitaal” en “Ondertekenen”. Default: “Ondertekenen”

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}", "voorwaardeCodes": [{voorwaardeCode1}, {voorwaardeCode2}], "goedKeuringsProces: {goedkeuringsProces}" }'

Response

Succes (200 OK)

{ "id": {id}, "collectionId": {collectionId}, "maxOfferteSize": {maxOfferteSize} }

Additionele informatie

Als er een offerte actief is op een aansluiting (status 4 of 4c), dan kan er geen nieuwe offertes hierop aangeboden worden. Nadat de offerte goedgekeurd/geweigerd/geannuleerd (status 4.1, 4.2 en 5) is dan kan er een nieuwe offerte hierop aangeboden worden.

Er zijn op dit moment 2 goedkeuringsproces, nl. digitaal en ondertekenen.

  • digitaal: Dit is de nieuwe manier van goedkeuren. Hierbij kan de aanvrager met vinkjes de voorwaarden en de offerte goedkeuren

  • ondertekenen: Hierbij moet de aanvrager een handtekening zetten op de offertes en voorwaarden en de ondertekende documenten uploaden om de offerte te goedkeuren.

De voorwaardecodes die meegegeven worden zijn codes van de voorwaarden die beheert worden in de beheer applicatie door de netbeheerder. Deze voorwaarden worden dan gekoppeld met de offerte.

In de response worden er 2 ids teruggegeven, nl. de id van de offerte document en de collection id van de offerte. Deze 2 worden gebruikt bij het uploaden van de offertebestand zodat het aan de goeie offerte gekoppeld wordt. Hiernaast wordt er ook een maxOfferteSize teruggegeven die de maximale grootte in bytes aangeeft dat de offertebestand kan zijn. Als de meegegeven voorwaarden de maximale grootte overschrijden dan wordt er een 400 BAD REQUEST teruggeven met een bericht dat dit is gebeurd.

 

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.

 

Query Parameters

Parameter

Verplicht

Type

Beschrijving

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

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}" "goedkeuringsProces": "{goedkeuringsProces}" } ] }

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

URL-Parameters

Parameter

Verplicht

Type

Beschrijving

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

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

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

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}

Korte beschrijving Deze endpoint wordt gebruikt om de details van een specifieke offerte op te halen op basis van de aanvraag-ID en offertereferentie.

Doel: Het verkrijgen van gedetailleerde informatie over een offerte die gekoppeld is aan een specifieke aanvraag-ID en referentie.

 

URL-Parameters

Parameter

Verplicht

Type

Beschrijving

Parameter

Verplicht

Type

Beschrijving

aanvraagId

Ja

Integer

De unieke ID van de aanvraag.

offerteReferentie

Ja

String

De referentie van de offerte die moet worden opgehaald.

Headers

Header Name

Verplicht

Type

Beschrijving

Header Name

Verplicht

Type

Beschrijving

Authorization

Ja

String

JWT Bearer token voor authenticatie

Content-Type

Nee

String

application/json

response:

Succes (200 OK):

{ "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}", "voorwaardeCodes": [{voorwaardeCode1}, {voorwaardeCode2}], "goedKeuringsProces: {goedkeuringsProces}" }

codevoorbeeld (curl):

curl -X GET https://services-acc.mijnaansluiting.nl/services/offerte/{aanvraagId}/referentie/{offerteReferentie} \ -H "Authorization: Bearer {JWT_Token}"

 

5. PATCH offerte/{aanvraagId}

Korte beschrijving Deze endpoint wordt gebruikt om de status van een offerte aan te passen.

Doel Het aanpassen van de status van een offerte die gekoppeld is aan een specifieke aanvraag-ID.

Parameters

URL-Parameters

Parameter

Verplicht

Type

Beschrijving

Parameter

Verplicht

Type

Beschrijving

aanvraagId

Ja

Integer

De unieke ID van de aanvraag waarvan de offerte moet worden opgehaald.

Headers

Header Name

Verplicht

Type

Beschrijving

Header Name

Verplicht

Type

Beschrijving

Authorization

Ja

String

JWT Bearer token voor authenticatie

Content-Type

Nee

String

application/json

Voorbeeld cURL-aanvraag

curl -X PATCH https://services-acc.mijnaansluiting.nl/services/offerte/{aanvraagId} \ -H "Authorization: Bearer {JWT_Token}"

Additionele informatie

Een netbeheerder kan alleen de status 4.2 doorgeven om de offerte te annuleren.

 

8. HTTP return status codes

Statuscode

Betekenis

Beschrijving

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

Swagger API specificatie

 

 

Related content