Restful Service

LinX runs on a Restful HTTP service that returns a JSON formatted result.

With each request to any of the services it is required to specify an ApiKey. In some cases, it is obligatory to specify options. These options define what is returned. These options must be sent with a bitwise and flags from the list below:

Field	Value	Description
None	0	No enrichment
Categories	1	Categorize the transactions
Businesses	2	Counterparties
Addresses	4	Add the addresses of the counterparties. Requires Businesses to be toggled.
Contact	8	Contact information, such as e-mail address, website address and telephone numbers. Requires Businesses to be toggled.
Activities	16	Activities are based on NACE rev 2 and for Dutch counterparties this is expanded with an SBI.
Properties	32	Properties: Personal, Counterpart, Transaction
Nace	64	The Nace corresponding to the transaction. For Dutch counterparties this is the SBI instead.

Clients choose a subscription for certain services. This toggles certain options. These options are configured based on the subscription and should match the options sent with each call.

By default, the options are set to Categories and Properties (33)

The data that is sent in the body is the raw content of the ZIP file.

The data should be sent as content (body).

The ApiKey should be sent in the header with each request.

The HTTP (REST) services return the following standard HTTP codes:

Value	Meaning
200	OK
400	Bad request - No data
403	Authentication failed - Invalid ApiKey or ApiKey has expired
500	Internal server error - File format was not recognized (No converter available) - File contains transactions prior to 1-1-2015 - Unexpected error (Exception)

API

For .NET there is an API available for the REST service.

An assembly is available for framework 4.5.2 or higher.

For each request sent to the REST service, the Microsoft.AspNet.WebApi.Cllient is used, which is available in GitHub.

The API contains clients for:

• WebAPI
• WebRequest

Exemplar WebApi

public static async Task<LinX.Sdk.Proxy.Entities.TransactionBatch> Convert(string fileName, string apiKey, ResultOptions options)
{
  LinX.Sdk.Proxy.Entities.TransactionBatch result = null;
  byte[] data = await GetData(fileName);
  using (HttpClient client = new HttpClient())
  {
    client.BaseAddress = new Uri(RemoteUrl);
    client.DefaultRequestHeaders.Add("ApiKey", apiKey);
    client.DefaultRequestHeaders.Add("Options", ((int)options).ToString());
    client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
    ByteArrayContent content = new ByteArrayContent(data);
    var response = await client.PostAsync("api/linx/convert", content);
    if (response.IsSuccessStatusCode)
    {
      result = await response.Content.ReadAsAsync<LinX.Sdk.Proxy.Entities.TransactionBatch>();
    }
    else
    {
      throw new Exception(string.Format("{0} : {1}", response.StatusCode, await response.Content.ReadAsStringAsync()));
    }
  }
  return result;
}

The advantage of this method is the usage of persistent objects.

Exemplar WebRequest

public static async Task<LinX.Sdk.Proxy.Entities.TransactionBatch> Convert(string fileName, string apiKey, ResultOptions options)
{
  LinX.Sdk.Proxy.Entities.TransactionBatch result = null;
  byte[] data = await ClientHelper.GetData(fileName);
  
  var request = (HttpWebRequest)WebRequest.Create(RemoteUrl + "/api/linx/convert");
  request.Method = WebRequestMethods.Http.Post;
  request.Accept = "application/json; charset=utf-8";
  request.Headers.Add("ApiKey", apiKey);
  request.Headers.Add("Options", ((int)options).ToString());
  
  using (var writer = new BinaryWriter(request.GetRequestStream()))
  {
    writer.Write(data, 0, data.Length);
    writer.Flush();
    writer.Close();
  }
  
  using (var response = await request.GetResponseAsync())
  {
    using (var resonse = response.GetResponseStream())
    {
      using (StreamReader sr = new StreamReader(resonse, Encoding.UTF8))
      {
        JsonTextReader reader = new JsonTextReader(sr);
        JsonSerializer serializer = JsonSerializer.Create();
        result = serializer.Deserialize<LinX.Sdk.Proxy.Entities.TransactionBatch>(reader);
      }
    }
  }
  return result;
}