Calcasa.Api 1.3.0

Calcasa.Api - the C# library for the Calcasa Public API v1

The Calcasa API is used to connect to Calcasa provided services. This is the first production version of the service

Client packages

Nuget - Packagist - PyPI

Client implementation notes

Clients should at all times be tolerant to the following:

• Extra fields in responses
• Empty or hidden fields in responses
• Extra values in enumerations
• Unexpected error responses in the form of Problem Details

OpenAPI Specification

This API is documented in OpenAPI format version 3 you can use tools like the OpenAPI Generator to generate API clients for for example the languages we don't provide a pre-built client for. This is documented here.

Changelog

2023-10-24 (v1.3.0)

• Add geldverstrekker field to the CallbackInschrijving model.
• Add support for mTLS on the callback service.
  • By default when requested by the target server the public CA signed TLS certificate with the appropriate domain as Common Name will be offered as the client certificate.
  • Public TLS Certificates rotate every couple of months.
• Change a couple of date-time fields that only contained a date to pure date fields. This might result is a different type in the generated clients and the service-side validation will be more strict. Times included in values will no longer be silently dropped, but will generate an error.
  • Change Modeldata model waardebepalingsdatum field to type date in OpenAPI spec.
  • Change Bestemmingsdata model datumBestemmingplan field to type date in OpenAPI spec.
  • Change Bodemdata model datumLaatsteOnderzoek field to type date in OpenAPI spec.
  • Change Referentieobject model verkoopdatum field to type date in OpenAPI spec.
  • Change VorigeVerkoop model verkoopdatum field to type date in OpenAPI spec.
  • Change waarderingInputParameters model peildatum field to type date in OpenAPI spec. This is an input field and will now require a date without a time.
• Add desktopTaxatieHerwaardering product to enumeration ProductType.
• The service no longer returns CORS headers.
• Actions now correctly report the 'application/problem+json' Content-Type in the documentation for the HTTP 422 Unprocessable Entity responses.
• Added energielabelData field to Objectdata model to contain the extra information about the energy label.
• The OpenAPI spec generation was changed slightly and thus the generated and published clients might be affected. There might be some slight breaking changes at compile time, but the functionality remains the same.
  • For example for C# and PHP AdresInfoAdres is now just covered by Adres
  • Likewise for the Omgevingsdata* models that are now all covered by Gebiedsdata
  • For a lot of the Waardering* models they are now using the correct model names, like WaarderingModel → Modeldata

2023-04-17 (v1.2.1)

• Add externeReferentie field to the CallbackInschrijving and WaarderingWebhookPayload models.

2022-08-04 (v1.2.0)

• Add support for managing CallbackSubscription's, this allows you to subscribe to callbacks for valuations that were not created with your API client.
  • GET /v1/callbacks/inschrijvingen
  • POST /v1/callbacks/inschrijvingen
  • GET /v1/callbacks/inschrijvingen/{bagNummeraanduidingId}
  • DELETE /v1/callbacks/inschrijvingen/{bagNummeraanduidingId}
• Add taxateurnaam field to the Taxatiedata model.
• Callback URIs should now end in / not just contain it to help stop common errors (ending in = is also still allowed when using a query string).
• Updating configuration in the POST /v1/configuratie/callbacks endpoint now clears stored but decommissioned versions from the configuration object.
• Add klantkenmerk to the WaarderingInputParameters and Waardering models.

2022-07-12 (v1.1.7)

• Added support for the OAuth 2.0 authorization code flow for use of the API with user accounts.
• Add bouweenheid to FunderingSoortBron enumeration.

2022-05-19 (v1.1.6)

• Added ltvTeHoogOverbrugging value to the BusinessRulesCode enumeration.

2022-04-13 (v1.1.5)

• Fix the schema for Operation value field for the benefit of the PHP and Python code generators, these will now correctly support any value type.

2022-04-12 (v1.1.4)

• Added proper Content-Disposition headers to the GET /v1/rapporten/{id} and GET /v1/facturen/{id} endpoints with the correct filename.
• Fix Mime Types for the POST /v1/configuratie/callbacks endpoint to only accept application/json.
• Fix C# API client to correctly use the application/json-patch+json content type in requests that require it.
• Fix C# client's FileParameter type correct handling of response headers like Content-Disposition and Content-Type.
• Removed C# client's useless implementation of IValidatableObject.
• Fix Python client's internal namespace name being illegal calcasa-api → calcasa.api.

2022-03-22 (v1.1.3)

• Add 402 (Payment required) and 422 (Unprocessable entity) as potential response for PATCH /v1/waarderingen/{id}.

2022-03-17 (v1.1.2)

• Fixed response type for GET /v1/geldverstrekkers/{productType} endpoint.

2022-03-08 (v1.1.1)

• Added GET /v1/geldverstrekkers/{productType} endpoint.
• Restored all ProblemDetails models.

2022-03-07 (v1.1.0)

• Added isErfpacht to WaarderingInputParameters.
• Cleaned up serialization of null values, they should no longer appear in the output.

2021-02-04

• Added extra clarification to the documentation pertaining to the WaarderingInputParameters and which fields are required for the different input parameter combinations.

2022-01-11 (v1.0.2)

• Fixed GET /api/v1/bodem/{id} endpoint path parameter description, query parameter was never meant to be there.

2021-12-23

• Clarified the documentation pertaining to the WaarderingInputParameters and which fields are required for the different product types.

2021-12-22 (v1.0.1)

• Dates are now serialized in the ISO date-only format yyyy-MM-dd to stop any confusion around timezones and are all assumed to be in UTC.
  • peildatum in WaarderingsInputParameters
  • datum_bestemmingplan in Bestemmingsdata
  • datum_laatste_onderzoek in Bodemdata
  • verkoopdatum in Referentieobject
  • verkoopdatum in VorigeVerkoop
  • waardebepalingsdatum in Modeldata
• Reintroduced the WaarderingWebhookPayload model that was omitted.

2021-12-21

• Patching the status of a Waardering object will now immediatly reflect its new status in the response object.

2021-12-13 (v1.0.0)

• Initial release of v1 based on v0.0.6

Cross-Origin Resource Sharing

This API features Cross-Origin Resource Sharing (CORS) implemented in compliance with W3C spec. And that allows cross-domain communication from the browser. All responses have a wildcard same-origin which makes them completely public and accessible to everyone, including any code on any site.

Authentication

Authentication is done via OAuth2 and the client credentials grant type.

Previous versions changelogs

2022-02-02

• API version v0 was removed from service.

2021-12-23

• Mark v0 as officially deprecated. No further versions will be released. Every implementation should move to v1

2021-12-10 (v0.0.6)

• Added extra field peildatum to the WaarderingInputParameters model.

2021-11-25 (v0.0.5)

• Updated all reported OAuth2 scopes and reduced the superflous scope information on each endpoint.

2021-11-23 (v0.0.4)

• Added per square meter developments to the WaarderingOntwikkeling object (fields with the PerVierkantemeter suffix).

2021-11-15 (v0.0.3)

• Added callback update and read endpoints and models.
• Updated documentation.

2021-11-11

• Renamed /fundering endpoint to /funderingen to be more in line with other endpoints
• Renamed HerstelType to FunderingHerstelType.
• Added FunderingType values.

2021-11-10

• Adjusted OpenAPI Spec generation to fix some issues with certain generators. This also means that the nullable nature of certain fields is now correctly represented. Please refer to the Generation article for more information, the config files were updated aswell.

2021-11-09

• Added Status and Taxatiedatum to Taxatiedata model.

2021-11-08

• Renamed id field in AdresInfo model to bagNummeraanduidingId.
• Added GET /v0/fundering/{id} endpoint with corresponding models.
• Changed HTTP response code for the BusinessRulesProblemDetails error return type of POST /v0/waardering from 422 Unprocessable Entity to 406 Not Acceptable to fix a duplicate.

2021-10-13

• Added taxatie field to Waardering model.
• Added Taxatiedata model containing the taxatieorganisatie field for desktop valuations.

2021-09-29

• Added aangemaakt timestamp field to Waardering model.
• Added WaarderingZoekParameters model to replace WaarderingInputParameters in the POST /v0/waarderingen/zoeken endpoint.
• Split Omgevingsdata model into a set of separate Gebiedsdata models that also contain extra statistics.
• Added bijzonderheden field to VorigeVerkoop model.
• Renamed ReferentieBijzonderheden model to VerkoopBijzonderheden.

2021-09-22

• Initial release of v0

This C# SDK is automatically generated by the OpenAPI Generator project:

• API version: 1.3.0
• SDK version: 1.3.0
• Build package: org.openapitools.codegen.languages.CSharpNetCoreClientCodegen For more information, please visit https://www.calcasa.nl/contact

<a name="frameworks-supported"></a>

Frameworks supported

• .NET Core >=1.0
• .NET Framework >=4.6
• Mono/Xamarin >=vNext

<a name="dependencies"></a>

Dependencies

• Json.NET - 13.0.1 or later
• JsonSubTypes - 1.8.0 or later

The DLLs included in the package may not be the latest version. We recommend using NuGet to obtain the latest version of the packages:

Install-Package Newtonsoft.Json
Install-Package JsonSubTypes

<a name="installation"></a>

Installation

Generate the DLL using your preferred tool (e.g. dotnet build)

Then include the DLL (under the bin folder) in the C# project, and use the namespaces:

using Calcasa.Api.Api;
using Calcasa.Api.Client;
using Calcasa.Api.Model;

<a name="usage"></a>

Usage

To use the API client with a HTTP proxy, setup a System.Net.WebProxy

Configuration c = new Configuration();
System.Net.WebProxy webProxy = new System.Net.WebProxy("http://myProxyUrl:80/");
webProxy.Credentials = System.Net.CredentialCache.DefaultCredentials;
c.Proxy = webProxy;

Connections

Each ApiClass (properly the ApiClient inside it) will create an instance of HttpClient. It will use that for the entire lifecycle and dispose it when called the Dispose method.

To better manager the connections it's a common practice to reuse the HttpClient and HttpClientHandler (see here for details). To use your own HttpClient instance just pass it to the ApiClass constructor.

HttpClientHandler yourHandler = new HttpClientHandler();
HttpClient yourHttpClient = new HttpClient(yourHandler);
var api = new YourApiClass(yourHttpClient, yourHandler);

If you want to use an HttpClient and don't have access to the handler, for example in a DI context in Asp.net Core when using IHttpClientFactory.

HttpClient yourHttpClient = new HttpClient();
var api = new YourApiClass(yourHttpClient);

You'll loose some configuration settings, the features affected are: Setting and Retrieving Cookies, Client Certificates, Proxy settings. You need to either manually handle those in your setup of the HttpClient or they won't be available.

Here an example of DI setup in a sample web project:

services.AddHttpClient<YourApiClass>(httpClient =>
   new PetApi(httpClient));

<a name="getting-started"></a>

Getting Started

using System.Collections.Generic;
using System.Diagnostics;
using System.Net.Http;
using Calcasa.Api.Api;
using Calcasa.Api.Client;
using Calcasa.Api.Model;

namespace Example
{
    public class Example
    {
        public static void Main()
        {

            Configuration config = new Configuration();
            config.BasePath = "https://api.calcasa.nl";
            // Configure OAuth2 access token for authorization: oauth
            config.AccessToken = "YOUR_ACCESS_TOKEN";
            // Configure OAuth2 access token for authorization: oauth
            config.AccessToken = "YOUR_ACCESS_TOKEN";

            // create instances of HttpClient, HttpClientHandler to be reused later with different Api classes
            HttpClient httpClient = new HttpClient();
            HttpClientHandler httpClientHandler = new HttpClientHandler();
            var apiInstance = new AdressenApi(httpClient, config, httpClientHandler);
            var bagNummeraanduidingId = 789L;  // long | Een BAG Nummeraanduiding ID om een adres te specificeren.

            try
            {
                // Adres info op basis van BAG Nummeraanduiding Id.
                AdresInfo result = apiInstance.GetAdres(bagNummeraanduidingId);
                Debug.WriteLine(result);
            }
            catch (ApiException e)
            {
                Debug.Print("Exception when calling AdressenApi.GetAdres: " + e.Message );
                Debug.Print("Status Code: "+ e.ErrorCode);
                Debug.Print(e.StackTrace);
            }

        }
    }
}

<a name="documentation-for-api-endpoints"></a>

Documentation for API Endpoints

All URIs are relative to https://api.calcasa.nl

<a name="documentation-for-models"></a>

Documentation for Models

• Model.Aanvraagdoel
• Model.Adres
• Model.AdresInfo
• Model.Bestemmingsdata
• Model.BodemStatusType
• Model.Bodemdata
• Model.BusinessRulesCode
• Model.BusinessRulesProblemDetails
• Model.Callback
• Model.CallbackInschrijving
• Model.CbsIndeling
• Model.Energielabel
• Model.EnergielabelData
• Model.Factuur
• Model.Foto
• Model.FunderingDataBron
• Model.FunderingHerstelType
• Model.FunderingRisico
• Model.FunderingRisicoLabel
• Model.FunderingSoortBron
• Model.FunderingType
• Model.FunderingTypering
• Model.Funderingdata
• Model.Gebiedsdata
• Model.Geldverstrekker
• Model.InvalidArgumentProblemDetails
• Model.JsonPatchDocument
• Model.KlantwaardeType
• Model.Kwartaal
• Model.Modeldata
• Model.NotFoundProblemDetails
• Model.Notitie
• Model.Notities
• Model.Objectdata
• Model.Omgevingsdata
• Model.Operation
• Model.OperationType
• Model.PermissionsDeniedProblemDetails
• Model.ProblemDetails
• Model.ProductType
• Model.Rapport
• Model.Referentieobject
• Model.ResourceExhaustedProblemDetails
• Model.Taxatiedata
• Model.Taxatiestatus
• Model.ValidationProblemDetails
• Model.VerkoopBijzonderheden
• Model.VorigeVerkoop
• Model.Waardering
• Model.WaarderingInputParameters
• Model.WaarderingOntwikkeling
• Model.WaarderingOntwikkelingKwartaal
• Model.WaarderingStatus
• Model.WaarderingWebhookPayload
• Model.WaarderingZoekParameters
• Model.WoningType

<a name="documentation-for-authorization"></a>

Documentation for Authorization

<a name="oauth"></a>

oauth

• Type: OAuth
• Flow: application
• Authorization URL:
• Scopes:
  • all: Full permissions for all areas.
  • api:all: Full permissions for all areas of the public API.
  • api:bestemmingsplannen:all: Full permissions for the bestemmingsplannen area of the public API.
  • api:bodem:all: Full permissions for the bodem area of the public API.
  • api:buurt:all: Full permissions for the buurt area of the public API.
  • api:configuratie:all: Full permissions for the configuratie area of the public API.
  • api:callback:all: Full permissions for the callback area of the public API.
  • api:facturen:all: Full permissions for the facturen area of the public API.
  • api:fotos:all: Full permissions for the fotos area of the public API.
  • api:funderingen:all: Full permissions for the funderingen area of the public API.
  • api:rapporten:all: Full permissions for the rapporten area of the public API.
  • api:waarderingen:all: Full permissions for the waarderingen area of the public API.
  • api:adressen:read: Read permissions for the adressen area of the public API.
  • api:bestemmingsplannen:read: Read permissions for the bestemmingsplannen area of the public API.
  • api:bodem:read: Read permissions for the bodem area of the public API.
  • api:buurt:read: Read permissions for the buurt area of the public API.
  • api:configuratie:read: Read permissions for the configuratie area of the public API.
  • api:configuratie:write: Write permissions for the configuratie area of the public API.
  • api:callback:read: Read permissions for the callback area of the public API.
  • api:callback:write: Write permissions for the callback area of the public API.
  • api:facturen:read: Read permissions for the facturen area of the public API.
  • api:fotos:read: Read permissions for the fotos area of the public API.
  • api:funderingen:read: Read permissions for the funderingen area of the public API.
  • api:geldverstrekkers:read: Read permissions for the geldverstrekkers area of the public API.
  • api:rapporten:read: Read permissions for the rapporten area of the public API.
  • api:waarderingen:create: Create permissions for the waarderingen area of the public API.
  • api:waarderingen:patch: Patch permissions for the waarderingen area of the public API.
  • api:waarderingen:read: Read permissions for the waarderingen area of the public API.
  • api:waarderingen:ontwikkeling: Read permissions for the ontwikkelingen endpoint in the waarderingen area of the public API.

<a name="oauth"></a>

oauth

• Type: OAuth
• Flow: accessCode
• Authorization URL: https://authentication.calcasa.nl/oauth2/v2.0/authorize
• Scopes:
  • all: Full permissions for all areas.
  • api:all: Full permissions for all areas of the public API.
  • api:bestemmingsplannen:all: Full permissions for the bestemmingsplannen area of the public API.
  • api:bodem:all: Full permissions for the bodem area of the public API.
  • api:buurt:all: Full permissions for the buurt area of the public API.
  • api:configuratie:all: Full permissions for the configuratie area of the public API.
  • api:callback:all: Full permissions for the callback area of the public API.
  • api:facturen:all: Full permissions for the facturen area of the public API.
  • api:fotos:all: Full permissions for the fotos area of the public API.
  • api:funderingen:all: Full permissions for the funderingen area of the public API.
  • api:rapporten:all: Full permissions for the rapporten area of the public API.
  • api:waarderingen:all: Full permissions for the waarderingen area of the public API.
  • api:adressen:read: Read permissions for the adressen area of the public API.
  • api:bestemmingsplannen:read: Read permissions for the bestemmingsplannen area of the public API.
  • api:bodem:read: Read permissions for the bodem area of the public API.
  • api:buurt:read: Read permissions for the buurt area of the public API.
  • api:configuratie:read: Read permissions for the configuratie area of the public API.
  • api:configuratie:write: Write permissions for the configuratie area of the public API.
  • api:callback:read: Read permissions for the callback area of the public API.
  • api:callback:write: Write permissions for the callback area of the public API.
  • api:facturen:read: Read permissions for the facturen area of the public API.
  • api:fotos:read: Read permissions for the fotos area of the public API.
  • api:funderingen:read: Read permissions for the funderingen area of the public API.
  • api:geldverstrekkers:read: Read permissions for the geldverstrekkers area of the public API.
  • api:rapporten:read: Read permissions for the rapporten area of the public API.
  • api:waarderingen:create: Create permissions for the waarderingen area of the public API.
  • api:waarderingen:patch: Patch permissions for the waarderingen area of the public API.
  • api:waarderingen:read: Read permissions for the waarderingen area of the public API.
  • api:waarderingen:ontwikkeling: Read permissions for the ontwikkelingen endpoint in the waarderingen area of the public API.