Page Comparison

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.

...

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.

...

• 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

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.

...

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

...

• 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:

1. Ophalen lijst Toegewezen bijlagen op een project:
   GET /project/{projectId}/bijlageassigned

2. Ophalen lijst (al geuploade) bijlagen op een project:
   GET /project/{projectId}/bijlage

3. 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:

1. Doorgeven als er Hoofdleiding nodig is (optioneel) → POST /project/{projectId}/hoofdleiding-aanleggen

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

3. Aangeven of je Mee in Combi gaat → POST /project/{projectId}/mic

Belangrijk hierbij is ook de volgorde; Let op: De Mee in Combi melden melding is altijd als de laatste doenhandeling.

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.

Contactgegevens gebruiker ophalen en doorgeven

Ophalen

Het emailadres van de individuele gebruiker die een actie heeft uitgevoerd in CAPO is beschikbaar via zowel de UI als de API. In de API vinden we deze informatie in de key email. Dit veld vinden we in de volgende types:

• type ActiviteitAct uitgebreid met key email

• type ActiviteitLogEntry bevat ActiviteitAct en is daarmee ook uitgebreid met key email

• type BijlageAct uitgebreid met key email

• type BijlageLogEntry uitgebreid met key email

Doorgeven

Sinds release 0.33.0 van de API is het mogelijk voor API gebruikers om deze gebruikers-informatie ook door te geven aan CAPO.

Elke POST, PUT en PATCH operatie ondersteunt nu de optionele header x-email hiermee is het mogelijk om aan iedereen te laten weten welke gebruiker de bewerking namens uw organisatie heeft uitgevoerd.

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 in dit project?

Dit is zichtbaar op de projectdetails, GET /project/{projectId}, 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.

Op dit moment zijn alle agd waarden binnen een project gelijk. Met het oog op de toekomst is het per produkt beschikbaar.

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:

1. De klant heeft een AGD aangegeven die eerder is dan de wachttijd van de netbeheerder
   → wensdatum = aanvraagDatum + wachttijd

2. De klant heeft geen AGD aangegeven
   → wensdatum = aanvraagDatum + wachttijd

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

Hoofdleiding projecten filteren op veranderingen

Filteren op Hoofdleiding projecten die veranderd zijn kan door in GET /hoofdleiding de parameters changedFrom en changedTo te gebruiken. Dit kijkt naar het veld changed en geeft alle projecten waar iets in veranderd is in de opgegeven tijdsspanne.

Filteren op projectplanning

Daarnaast is het mogelijk om de parameters planningChangedFrom en planningChangedTo te gebruiken. Deze filteren alleen op het veld planningChanged, waardoor er alleen projecten worden teruggegeven waarvan de startUitvoeringWeek is veranderd in de aangegeven periode.