Introduction

WMS2 is a service-oriented SaaS architecture that offers RESTful Web API functionalities for wealth management and pension provision. The platform is fully integrated into Lienhardt’s foundations and its bank and enables the creation and management of wealth and pension solutions (3a and vested benefits).

Target groups

Users of this guide should have a certain level of experience in web and software development. In addition, the format of the receipt means that we focus on specific tasks rather than providing a general introduction. We will not cover the software development aspect. Instead, we will focus on the most common APIs and how to use them through examples organized in step-by-step code snippets.

APIs

The structure of the WMS APIs is described with Swagger and can be found here. The responses of the APIs return JSON in accordance with the standard HTTP protocol.

Examples

The code snippets are written with .NET CORE and C#. You can download an example .NET CORE MVC web application that uses the same code snippets from https://github.com/descartes-finance/Descartes.Wms2.HowToUse.Mvc.

To avoid large and difficult to read code snippets, not all DTO definitions are listed. The DTO code definitions are part of the sample application.

DTOs are simple C# classes that map the JSON responses: 

									
  {
	"id": 0,
	"code": "string",
	"name": "string"
  }
											
										
									
  public class GenderOutputModel
  {
	public long Id { get; set; }
	public string Code { get; set; }
	public string Name { get; set; }
  }

Requirements

In order to work with the APIs, a JSON token is required for authorization. Without this token, any HTTP call will be considered unauthorized and will return a 401.

If you need a GUEST token, please contact us at info@descartes.swiss.

Once you have the authorization token, set the html header as shown below:

						
  Authorization: Bearer e+JhsciOiJIU3sd1NiIsI#°§R5cCI6IkpXVCJ9.eyJwcml$£3JpeXBzaWQiOiJZVUgiLCJuYW1è?xN0Iiwseg@xNjczaaI8lHpVy...

There are different types of authorization tokens: GUEST, CUSTOMER, SELLER, ADMIN and SUPERADMIN.

TThe GUEST token is required for customer self-registration or customer login. After registration or customer login, the Web API returns a CLIENT token, which must be used for all further API calls. Normally, the authorization token has a validity period of one hour.

There are cases in which the authorization token has a longer validity period. The GUEST token, which is used to initiate the customer's self-registration, or the token used to initiate the login process, has a long validity period. ADMIN tokens used in an integration solution with server-to-server calls can have a long validity period.

HTTP proxy

Once we have received the authorization token, we proceed with the initialization of an HTTP proxy: 

									
  const string BASE_URL = "https://test.wms2-app.descartes-finance.com";
  const string GUEST_TOKEN = "YOUR AUTHENTICATION TOKEN";

  using var httpClient = new HttpClient { BaseAddress = new Uri(BASE_URL) };
  httpClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json", 1));
  httpClient.DefaultRequestHeaders.AcceptLanguage.Add(new StringWithQualityHeaderValue("de-DE", 1));
  httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", GUEST_TOKEN);

This proxy is used for all other API calls.

Error handling

API errors conform to IETF Internet standards and are returned as HTTP response status codes. To help you understand the reason for the error, the API also returns a payload containing detailed information about the problem.

There are three different types of error response, based on the HTTP error code.

All Descartes ErrorCode are available to the address api/v1/system/error-codes.

Unauthorized

Response payload for HTTP response status code 401: 
							
{
	"ErrorCode": "string",
	"Message": "string",
	"RemainingAttempts": int
}

Bad Request

Response payload for HTTP response status code 400: 
								
{
  "ErrorCode": "string",
  "Message": "string"
  "ValidationErrors":
  {
	// Field name 1
	"string":
	[
	  {"ValidationErrorCode":"string","ValidationErrorMessage":"string"}
	],
	// Field name 2
	"string":
	[
	  {"ValidationErrorCode":"string","ValidationErrorMessage":"string"}
	],
	...
	...
	// Field name N
	"string":
	[
	  {"ValidationErrorCode":"string","ValidationErrorMessage":"string"}
	],
  }
}
The attribute “ValidationErrors” may be NULL, in case the bad response to the request refers to a general check. In this case, the JSON response payload of the will simply be: 
								
{
  "ErrorCode": "string",
  "Message": "string"
  "ValidationErrors": null
}
Example 1: Payload validation
Assuming you are making a POST/PUT request containing invalid values for CustomerID, CustomerName and CustomerSurname: 
							
  var payload = JsonConvert.SerializeObject(new
  {
	CustomerID = (Nullable)null, 
	CustomerName = "A", 
	CustomerSurname = "Dea#§"
  });

  var httpResponseMessage = awaut httpClient.PostAsync("api/v1/users/create", new StringContent(payload, Encoding.UTF8, "application/json"));
  if (httpResponseMessage.IsSuccessStatusCode == false)
  {
	if (httpResponseMessage.StatusCode == System.Net.HttpStatusCode.BadRequest)
	{
		var content = await httpResponseMessage.Content.ReadAsStringAsync();
		var validationErrorModel = JsonConvert.DeserializeObject<ValidationErrorModel>(content);
	}
  }
The response will have the HTTP status code 400 with an error payload as follows: 
							
  {
	"ErrorCode":"VALIDATION-ERRORS",
	"Message":"Request contains one or more invalid fields.",
	"ValidationErrors":
	{
	  "CustomerId":[{"ValidationErrorCode":"INVALID-FIELD","ValidationErrorMessage":"Customer ID is mandatory"}],
	  "CustomerName":[{"ValidationErrorCode":"INVALID-FIELD","ValidationErrorMessage":"Customer name is too short"}],
	  "CustomerSurname":[{"ValidationErrorCode":"INVALID-FIELD","ValidationErrorMessage":"Customer surname cannot contain special characters"}]
	}
  }
Example 2: Generic validation
For all cases where the bad request response does not have a list of invalid fields: 
						
  ....
  ....
  var httpResponseMessage = await httpClient.PostAsync(url);
  if (httpResponseMessage.IsSuccessStatusCode == false)
  {
	if (httpResponseMessage.StatusCode == System.Net.HttpStatusCode.BadRequest)
	{
		var errorContent = await httpResponseMessage.Content.ReadAsStringAsync();
		var validationErrorModel = JsonConvert.DeserializeObject<ValidationErrorModel>(errorContent);
	}
  }
The error payload will be: 
						
  {
	"ErrorCode":"STARTING-DATE-IS-NEEDED",
	"Message":"starting-from is mandatory.",
	"ValidationErrors": null
  }

All others errors

Response load for all other errors: 
							
{
	"ErrorCode": "string",
	"Message": "string"
}

Pagination

Pagination is a way of breaking up large parts of content into smaller pieces.

Some API endpoints can retrieve data using pagination. The pagination parameters are passed via a query string:

  • pageNumber
  • pageSize

As a result, the response will contain an X-Defi-PageMetadata HTTP header. This is a JSON object with the following pagination result properties:

  • totalCount
  • currentPage
  • pageSize
  • totalPages
  • previousPageLink
  • nextPageLink

HTTP POST

All HTTP POST and PUT requests return a payload containing the generated object.

Also for POST, the HTTP Location header contains the URL of the entity created.