CAPO API handleiding

CAPO API

De API van CAPO zorgt ervoor dat vrijwel alle functionaliteit in CAPO ook via een API is te gebruiken vanuit de eigen systemen.

Documentatie over de CAPO API is hier terug te vinden:

Productie: https://services.dsplatform.nl/api/capo/documentation/#/
Acceptatie: https://qas-services.dsplatform.nl/api/capo/documentation/#/

De documentatie is ook als .JSON te downloaden: https://services.dsplatform.nl/api/capo/documentation.json

Toegang krijgen tot de CAPO API

De CAPO API is beschikbaar voor netbeheerders en aannemers in de contractgebieden die CAPO ondersteunt. Zie hiervoor de lijst van ondersteunde contractgebieden op de CAPO wiki. Om als organisatie toegang te krijgen tot de API kan een Informatieverzoek service request worden aangemaakt op onze Servicedesk. Er wordt dan een token voor je organisatie aangemaakt en verstuurd naar de primaire contactpersoon van die organisatie. Met deze token kan de API vervolgens gebruikt worden.

Indien je organisatie toegang heeft gekregen tot de API en er later incidenten optreden dan kunnen deze gemeld worden via de servicedesk van Mijn Aansluiting. Voeg hier een verwijzing aan toe van de eerdere toekenning van toegang voor jouw organisatie aan de CAPO API.

Om gebruik te kunnen maken van één van de API’s, dient het volgende service request te worden gebruikt:

https://mijnaansluiting.atlassian.net/servicedesk/customer/portal/1/group/24/create/197

Let op!: voor alle API’s worden dezelfde credentials gebruikt.
Dus als de deelnemer al credentials heeft voor de DSP API, dan kunnen die credentials ook gebruikt worden voor de CAPO API, mits de deelnemer toegang heeft tot de API.

Voorbeeld:

Deelnemer maakt al gebruik van de DSP API en wil ook gebruik maken van de CAPO API.
Deelnemer legt een ticket in om toegang te krijgen tot de CAPO API.
Wanneer het ticket is afgerond, kan de deelnemer van de CAPO API gebruik maken met dezelfde credentials die hij voor de DSP API gebruikt.

Limiet aantal verzoeken

configuratie	waarde	beschrijving
rate limit	20	aantal verzoeken per seconde
burst	30	aantal verzoeken dat tegelijk mag binnen komen
inflight requests	3	aantal verzoeken dat tegelijk actief mag zijn

Rate limiting is per client op het geheel van services, niet per API endpoint.

Uitleg veel voorkomende scenario’s

Hieronder worden een aantal scenario’s wat verder uitgelegd met voorbeelden, naar aanleiding van vragen van gebruikers. Let op dat de documentatie in de APIs zelf leading is, en onderstaande ter aanvulling.

Uploaden toegewezen bijlage

In CAPO werken we met toegewezen bijlagen. De toegewezen bijlage kan gezien worden als een container waar deelnemers bestanden (bijlagen) aan kunnen toevoegen. Het doel van deze container is het begeleiden van de projectvoortgang, door duidelijk te maken welke partij er verantwoordelijk is, wat de inhoud is en wat de planning(/tijdigheid) is van dit deel van het project.

Een toegewezen bijlage is toegewezen aan een organisatie. Deze organisatie wordt geacht deze bijlage op te leveren
Onder een toegewezen bijlage kunnen tot aan oplevering meerdere bestanden/bijlagen worden geupload.
Na oplevering zijn er geen wijzigingen meer mogelijk op de toegewezen bijlage

Om via de API bijlagen (bestanden) te uploaden onder een toegewezen bijlage kunnen de volgende stappen worden gevolgd:

Vraag lijst bijlagen van specifiek project op
GET /project/{projectId}/bijlageassigned
Alternatief: alle bijlagen op naam van jezelf opvragen via GET /bijlageassigned
Vind juiste bijlageAssignedId. Bijv "bijlageAssignedId": "62c7d159eb277e1b79161430"
Maak een URL voor de bijlage die je wil uploaden
POST /project/{projectId}/bijlageassigned/{bijlageAssignedId}/bijlage
Gebruik de teruggegeven URL direct om het bestand te uploaden
Geef aan dat het bestand is geupload
PATCH /project/{projectId}/bijlage/{bijlageId} with content { "status": "uploaded" }
Als het het laatste bestand is voor deze bijlageAssigned; opleveren
PATCH /project/{projectId}/bijlageassigned/{bijlageAssignedId} with content { "status": "done" }

Let op:

{bijlageAssignedId} = ID van toegewezen bijlage
{bijlageId} = ID van specifiek bestand

Beoordelen toegewezen bijlage

Sommige bijlagen dienen beoordeeld te worden voordat ze opgeleverd worden. Welke dit zijn is per combi gebied vooraf instelbaar door de beheerder van het project.

Een te beoordelen toegewezen bijlage is te herkennen aan de boolean property requiresReview

Een toegewezen bijlage die beoordeeld moet worden volgt stap 1 t/m 5 van bovenstaand overzicht. Echter in plaats van direct opleveren (naar status done) gaat deze bijlage naar status review. Nadat de toegewezen bijlage is beoordeeld gaat deze bij goedkeur naar status done, na afkeur terug naar status uploaded (met verplicht een reden in veld reden) waarna het proces opnieuw begint.

Zie ook de uitleg van de statussen in de API’s onder PATCH '/project/{projectId}/bijlageassigned/{bijlageAssignedId} https://services.dsplatform.nl/api/capo/documentation/#/project%20type%20Hoofdleiding/patch_project__projectId__bijlageassigned__bijlageAssignedId_

Samenvattend;

de volgorde van statussen in de happy flow:
assigned → uploaded → review → done
Bij één afkeur in het proces is de volgorde:
assigned → uploaded → review → uploaded → review → done

Ophalen reeds geuploade bijlagen/bestanden van een project

Om reeds geuploade bijlagen (bestanden) van een project te downloaden en te achterhalen bij welke toegewezen bijlage zij horen, zijn er een aantal stappen:

Ophalen lijst Toegewezen bijlagen op een project:
GET /project/{projectId}/bijlageassigned
Ophalen lijst (al geuploade) bijlagen op een project:
GET /project/{projectId}/bijlage
Koppelen van bijlage aan bijlageAssigned dmv parentId uit antwoord van /bijlage, dit heeft dezelfde waarde als bijlageAssignedId uit het antwoord op /bijlageassigned

Quickscan volgorde

Bij het uitvoeren van de Quickscan via de API door een netbeheerder zijn er een aantal stappen:

Doorgeven als er Hoofdleiding nodig is (optioneel) → POST /project/{projectId}/hoofdleiding-aanleggen
Aangeven dat de Netbeheerder Extra werkvoorbereiding doet door een activiteit aan te maken van het type Extra werkvoorbereiding als dat relevant is → POST /project/{projectId}/activiteit
Aangeven of je Mee in Combi gaat → POST /project/{projectId}/mic

Let op: De Mee in Combi melding is altijd de laatste handeling.

De volgorde van handelingen tbv quickscan is belangrijk omdat, na de eerste combi melding van een netbeheerder, CAPO de quickscan beschouwt als afgerond. Hierna is het dan dus ook niet meer mogelijk om de andere twee handelingen te doen.

AGD: Aansluit Gereed Datum

In steeds meer gebieden wordt de klant gevraagd of hij/zij al gereed is, of op welke datum dat zal zijn. Deze werkwijze wordt per Contractgebied ‘aan’ gezet. Deze gegevens geven we ook door via de CAPO API.

Wordt AGD gebruikt?

Dit is zichtbaar op de projectdetails, dmv type agdRelevant. Bij waarde true wordt er op dit project AGD toegepast

Waar vind ik de AGD die de klant heeft doorgegeven?

De datum die de klant heeft doorgegeven geven we door op produkt niveau (= de combinatie van een aansluitobject en een discipline). Via GET /project/{projectId}, aansluitObjecten → produkten → agd. Het veldt geeft de datum die de klant heeft ingevuld. Deze kan ook leeg zijn als de klant niet weet wanneer hij aansluitgereed is. Dit kan dus per object en discipline verschillen

Wensdatum

Het veld wensdatum wordt ook gevuld bij projecten waarbij de AGD wordt gebruikt. Dit geeft, op projectniveau, aan wat de afgeleide aansluitgereeddatum zal zijn. Er zijn hiervoor 3 scenario’s:

De klant heeft een AGD aangegeven die eerder is dan de wachttijd van de netbeheerder
→ wensdatum = aanvraagDatum + wachttijd
De klant heeft geen AGD aangegeven
→ wensdatum = aanvraagDatum + wachttijd
De klant heeft een AGD aangegeven die later is dan de wachttijd van de netbeheerder:
→ wensdatum = de agd van het eerste produkt op dit project