iController HTTPS datalink

This site explains how to load your debtor data into iController using the iController datalink. You should already have an export (in valid format) of the debtor data from your accounting software. For each subcompany there should be a separate file.

How to load data into iController

Production
Testing

Uploading a file

First you should send the debtor data file for each subcompany to iController using a HTTPS POST request with the following parameters:

url: https://<PLATFORM>.icontroller.eu/datalink/upload/
client id: this is usually empty and only used when the datalink is called from multiple machines
secret: a shared secret for authentication, you should have received this parameter already
name: the name of the debtor data file. Use the name of your subcompany + '.xml'
contents: the contents of the debtor data file

We recommend using the curl tool to send the data. Curl is a free opensource tool specifically designed to simplify HTTP requests. Because it can be used from the command line it is very easy to automate tasks. The POST request above translates to:

curl -u "<CLIENTID>:<SECRET>" --data-binary @<LOCAL-FILE-NAME> -H "Content-Type: application/x-binary" "https://<PLATFORM>.icontroller.eu/datalink/upload/?name=<SUB-COMPANY-NAME>.xml"

POST /datalink/upload/?name=<SUB-COMPANY-NAME>.xml HTTP/1.1
Host: <PLATFORM>.icontroller.eu
Content-Type: application/x-binary
Authorization: Basic <BASE64 ENCODED CLIENTID:SECRET>

<CONTENT>

Add-Type -AssemblyName System.Web

$platform    = "<PLATFORM>"
$clientId    = "<CLIENTID>"
$secret      = "<SECRET>"

$uploadName  = "<SUB-COMPANY-NAME>.xml"
$filePath    = "<FILEPATH>"

$params = @{
  Uri               = "https://${platform}.icontroller.eu/datalink/upload/?name=${uploadName}"
  Method            = "POST"
  Headers = @{
    "Content-Type"  = "application/x-binary"
    "Authorization" = "Basic " + [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes("${clientId}:${secret}"))
  }
  Body              = [System.IO.File]::ReadAllBytes($filePath)
}

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
Invoke-RestMethod @params

using System;
using System.Net.Http;
using System.Text;
using System.IO;
using System.IO.Compression;
using System.Net.Http.Headers;

namespace Icontroller
{
    public class Datalink
    {
        public static void Main(string[] args)
        {
            var uncompressedStream = new MemoryStream(Encoding.UTF8.GetBytes("<CONTENTS>"));
            var compressedStream = new System.IO.MemoryStream();
            using (var compressionStream = new GZipStream(compressedStream, CompressionMode.Compress)) {
                uncompressedStream.CopyTo(compressionStream);
            }

            using (var client = new HttpClient()) {
                HttpRequestMessage requestMessage = new HttpRequestMessage(new HttpMethod("POST"), "https://<PLATFORM>.icontroller.eu/datalink/upload/?name=<SUB-COMPANY-NAME>.xml.gz");
                requestMessage.Content = new ByteArrayContent(compressedStream.ToArray());

                requestMessage.Content.Headers.ContentType = new MediaTypeHeaderValue("application/x-binary");
                requestMessage.Headers.Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(System.Text.ASCIIEncoding.ASCII.GetBytes("<CLIENTID>:<SECRET>")));
                var task = client.SendAsync(requestMessage);
                task.Wait();
                Console.Out.WriteLine(task.Result.ReasonPhrase);
            }
        }
    }
}

import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.lang.InterruptedException;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import java.nio.charset.StandardCharsets;
import java.util.Base64;
import java.util.zip.GZIPOutputStream;

public class Icontroller {
    public static void main(String []args) throws IOException, InterruptedException {
        ByteArrayOutputStream compressedData = new ByteArrayOutputStream();
        try (GZIPOutputStream gzipOutputStream = new GZIPOutputStream(compressedData)) {
            gzipOutputStream.write("<FILE-CONTENTS>".getBytes(StandardCharsets.UTF_8));
        }

        HttpClient client = HttpClient.newBuilder().build();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://<PLATFORM>.icontroller.eu/datalink/upload/?name=<SUB-COMPANY-NAME>.xml.gz"))
            .header("Content-Type", "application/x-binary")
            .header("Authorization", "Basic " + Base64.getEncoder().encodeToString("<CLIENTID>:<SECRET>".getBytes(StandardCharsets.UTF_8)))
            .POST(HttpRequest.BodyPublishers.ofByteArray(compressedData.toByteArray()))
            .build();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}

Trigger import

After you have sent all files for each subcompany, you have to notify iController the data should be loaded into iController. You can do this by using a POST request with the following parameters:

url: https://<PLATFORM>.icontroller.eu/datalink/refresh/
client id: this is usually empty and only used when the datalink is called from multiple machines
secret: a shared secret for authentication, you should have received this parameter already

When using curl you can do:

curl -u "<CLIENTID>:<SECRET>" "https://<PLATFORM>.icontroller.eu/datalink/refresh/"

POST /datalink/refresh/ HTTP/1.1
Host: <PLATFORM>.icontroller.eu
Authorization: Basic <BASE64 ENCODED CLIENTID:SECRET>

Add-Type -AssemblyName System.Web

$platform = "<PLATFORM>"
$clientId = "<CLIENTID>"
$secret   = "<SECRET>"

$params = @{
  Uri     = "https://${platform}.icontroller.eu/datalink/refresh/"
  Method  = "POST"
  Headers = @{
    Authorization = "Basic " + [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes("${clientId}:${secret}"))
  }
}

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
Invoke-RestMethod @params

using System;
using System.Net.Http;
using System.Net.Http.Headers;

namespace Icontroller
{
    public class Datalink
    {
        public static void Main(string[] args)
        {
            using (var client = new HttpClient()) {
                HttpRequestMessage requestMessage = new HttpRequestMessage(new HttpMethod("POST"), "https://<PLATFORM>.icontroller.eu/datalink/refresh/");
                requestMessage.Headers.Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(System.Text.ASCIIEncoding.ASCII.GetBytes("<CLIENTID>:<SECRET>")));
                var task = client.SendAsync(requestMessage);
                task.Wait();
                Console.Out.WriteLine(task.Result.ReasonPhrase);
            }
        }
    }
}

import java.io.IOException;
import java.lang.InterruptedException;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import java.util.Base64;

public class Icontroller {
    public static void main(String []args) throws IOException, InterruptedException {
        HttpClient client = HttpClient.newBuilder().build();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://<PLATFORM>.icontroller.eu/datalink/refresh/"))
            .header("Authorization", "Basic " + Base64.getEncoder().encodeToString("<CLIENTID>:<SECRET>".getBytes(StandardCharsets.UTF_8)))
            .build();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}

Change the secret

It is possible to change the secret using the API. You can do this at any time and as much as you like. We recommend to change te secret an a regular basis. This can be done by using the following parameters:

url: https://<PLATFORM>.icontroller.eu/datalink/change-secret/
client id: this is usually empty and only used when the datalink is called from multiple machines
secret: a shared secret for authentication, you should have received this parameter already
newSecret: the new secret

curl --data-urlencode secret=<SECRET> --data-urlencode newSecret=<NEW-SECRET> "https://<PLATFORM>.icontroller.eu/datalink/change-secret/"

POST /datalink/change-secret/ HTTP/1.1
Host: <PLATFORM>.icontroller.eu
Content-Type: application/x-www-form-urlencoded

secret=<SECRET>&newSecret=<NEW-SECRET>

Add-Type -AssemblyName System.Web

$platform  = "<PLATFORM>"
$clientId  = "<CLIENTID>"
$secret    = "<SECRET>"
$newSecret = "<NEW-SECRET>"

$params = @{
  Uri     = "https://${platform}.icontroller.eu/datalink/change-secret/"
  Method  = "POST"
  Body    = @{
    clientId  = "${clientId}"
    secret    = "${secret}"
    newSecret = "${newSecret}"
  }
}

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
Invoke-RestMethod @params

using System;
using System.Collections.Generic;
using System.Net.Http;

namespace Icontroller
{
    public class Datalink
    {
        public static void Main(string[] args)
        {
            using (var client = new HttpClient()) {
                var body = new FormUrlEncodedContent(new[] {
                    new KeyValuePair<string, string>("secret", "<SECRET>"),
                    new KeyValuePair<string, string>("newSecret", "<NEW-SECRET>"),
                });
                var task = client.PostAsync("https://<PLATFORM>.icontroller.eu/datalink/change-secret/", body);
                task.Wait();
                Console.Out.WriteLine(task.Result.ReasonPhrase);
            }
        }
    }
}

Uploading a file

First you should send the debtor data file for each subcompany to iController using a HTTPS POST request with the following parameters:

url: https://<PLATFORM>-testing.icontroller.eu/datalink/upload/
client id: this is usually empty and only used when the datalink is called from multiple machines
secret: a shared secret for authentication, you should have received this parameter already
name: the name of the debtor data file. Use the name of your subcompany + '.xml'
contents: the contents of the debtor data file

curl -u "<CLIENTID>:<SECRET>" --data-binary @<LOCAL-FILE-NAME> -H "Content-Type: application/x-binary" "https://<PLATFORM>-testing.icontroller.eu/datalink/upload/?name=<SUB-COMPANY-NAME>.xml"

POST /datalink/upload/?name=<SUB-COMPANY-NAME>.xml HTTP/1.1
Host: <PLATFORM>-testing.icontroller.eu
Content-Type: application/x-binary
Authorization: Basic <BASE64 ENCODED CLIENTID:SECRET>

<CONTENT>

Add-Type -AssemblyName System.Web

$platform    = "<PLATFORM>"
$clientId    = "<CLIENTID>"
$secret      = "<SECRET>"

$uploadName  = "<SUB-COMPANY-NAME>.xml"
$filePath    = "<FILEPATH>"

$params = @{
  Uri               = "https://${platform}-testing.icontroller.eu/datalink/upload/?name=${uploadName}"
  Method            = "POST"
  Headers = @{
    "Content-Type"  = "application/x-binary"
    "Authorization" = "Basic " + [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes("${clientId}:${secret}"))
  }
  Body              = [System.IO.File]::ReadAllBytes($filePath)
}

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
Invoke-RestMethod @params

using System;
using System.Net.Http;
using System.Text;
using System.IO;
using System.IO.Compression;
using System.Net.Http.Headers;

namespace Icontroller
{
    public class Datalink
    {
        public static void Main(string[] args)
        {
            var uncompressedStream = new MemoryStream(Encoding.UTF8.GetBytes("<CONTENTS>"));
            var compressedStream = new System.IO.MemoryStream();
            using (var compressionStream = new GZipStream(compressedStream, CompressionMode.Compress)) {
                uncompressedStream.CopyTo(compressionStream);
            }

            using (var client = new HttpClient()) {
                HttpRequestMessage requestMessage = new HttpRequestMessage(new HttpMethod("POST"), "https://<PLATFORM>-testing.icontroller.eu/datalink/upload/?name=<SUB-COMPANY-NAME>.xml.gz");
                requestMessage.Content = new ByteArrayContent(compressedStream.ToArray());

                requestMessage.Content.Headers.ContentType = new MediaTypeHeaderValue("application/x-binary");
                requestMessage.Headers.Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(System.Text.ASCIIEncoding.ASCII.GetBytes("<CLIENTID>:<SECRET>")));
                var task = client.SendAsync(requestMessage);
                task.Wait();
                Console.Out.WriteLine(task.Result.ReasonPhrase);
            }
        }
    }
}

import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.lang.InterruptedException;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import java.nio.charset.StandardCharsets;
import java.util.Base64;
import java.util.zip.GZIPOutputStream;

public class Icontroller {
    public static void main(String []args) throws IOException, InterruptedException {
        ByteArrayOutputStream compressedData = new ByteArrayOutputStream();
        try (GZIPOutputStream gzipOutputStream = new GZIPOutputStream(compressedData)) {
            gzipOutputStream.write("<FILE-CONTENTS>".getBytes(StandardCharsets.UTF_8));
        }

        HttpClient client = HttpClient.newBuilder().build();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://<PLATFORM>-testing.icontroller.eu/datalink/upload/?name=<SUB-COMPANY-NAME>.xml.gz"))
            .header("Content-Type", "application/x-binary")
            .header("Authorization", "Basic " + Base64.getEncoder().encodeToString("<CLIENTID>:<SECRET>".getBytes(StandardCharsets.UTF_8)))
            .POST(HttpRequest.BodyPublishers.ofByteArray(compressedData.toByteArray()))
            .build();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}

Trigger import

After you have sent all files for each subcompany, you have to notify iController the data should be loaded into iController. You can do this by using a POST request with the following parameters:

url: https://<PLATFORM>-testing.icontroller.eu/datalink/refresh/
client id: this is usually empty and only used when the datalink is called from multiple machines
secret: a shared secret for authentication, you should have received this parameter already

When using curl you can do:

curl -u "<CLIENTID>:<SECRET>" "https://<PLATFORM>-testing.icontroller.eu/datalink/refresh/"

POST /datalink/refresh/ HTTP/1.1
Host: <PLATFORM>-testing.icontroller.eu
Authorization: Basic <BASE64 ENCODED CLIENTID:SECRET>

Add-Type -AssemblyName System.Web

$platform = "<PLATFORM>"
$clientId = "<CLIENTID>"
$secret   = "<SECRET>"

$params = @{
  Uri     = "https://${platform}-testing.icontroller.eu/datalink/refresh/"
  Method  = "POST"
  Headers = @{
    Authorization = "Basic " + [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes("${clientId}:${secret}"))
  }
}

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
Invoke-RestMethod @params

using System;
using System.Net.Http;
using System.Net.Http.Headers;

namespace Icontroller
{
    public class Datalink
    {
        public static void Main(string[] args)
        {
            using (var client = new HttpClient()) {
                HttpRequestMessage requestMessage = new HttpRequestMessage(new HttpMethod("POST"), "https://<PLATFORM>-testing.icontroller.eu/datalink/refresh/");
                requestMessage.Headers.Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(System.Text.ASCIIEncoding.ASCII.GetBytes("<CLIENTID>:<SECRET>")));
                var task = client.SendAsync(requestMessage);
                task.Wait();
                Console.Out.WriteLine(task.Result.ReasonPhrase);
            }
        }
    }
}

import java.io.IOException;
import java.lang.InterruptedException;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import java.util.Base64;

public class Icontroller {
    public static void main(String []args) throws IOException, InterruptedException {
        HttpClient client = HttpClient.newBuilder().build();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://<PLATFORM>-testing.icontroller.eu/datalink/refresh/"))
            .header("Authorization", "Basic " + Base64.getEncoder().encodeToString("<CLIENTID>:<SECRET>".getBytes(StandardCharsets.UTF_8)))
            .build();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}

Change the secret

url: https://<PLATFORM>-testing.icontroller.eu/datalink/change-secret/
client id: this is usually empty and only used when the datalink is called from multiple machines
secret: a shared secret for authentication, you should have received this parameter already
newSecret: the new secret

curl --data-urlencode secret=<SECRET> --data-urlencode newSecret=<NEW-SECRET> "https://<PLATFORM>-testing.icontroller.eu/datalink/change-secret/"

POST /datalink/change-secret/ HTTP/1.1
Host: <PLATFORM>-testing.icontroller.eu
Content-Type: application/x-www-form-urlencoded

secret=<SECRET>&newSecret=<NEW-SECRET>

Add-Type -AssemblyName System.Web

$platform  = "<PLATFORM>"
$clientId  = "<CLIENTID>"
$secret    = "<SECRET>"
$newSecret = "<NEW-SECRET>"

$params = @{
  Uri     = "https://${platform}-testing.icontroller.eu/datalink/change-secret/"
  Method  = "POST"
  Body    = @{
    clientId  = "${clientId}"
    secret    = "${secret}"
    newSecret = "${newSecret}"
  }
}

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
Invoke-RestMethod @params

using System;
using System.Collections.Generic;
using System.Net.Http;

namespace Icontroller
{
    public class Datalink
    {
        public static void Main(string[] args)
        {
            using (var client = new HttpClient()) {
                var body = new FormUrlEncodedContent(new[] {
                    new KeyValuePair<string, string>("secret", "<SECRET>"),
                    new KeyValuePair<string, string>("newSecret", "<NEW-SECRET>"),
                });
                var task = client.PostAsync("https://<PLATFORM>-testing.icontroller.eu/datalink/change-secret/", body);
                task.Wait();
                Console.Out.WriteLine(task.Result.ReasonPhrase);
            }
        }
    }
}

Generate an example datalink package for your company using curl

Production
Testing

If you want to use curl we provide a working example data link for your company. Just fill in the data below to download the datalink package. To use it just extract all contents to a separate dir and run "export.bat". It will automatically export all xml-files and csv-files in the same folder to your iController.

Your iController url

https://

.icontroller.eu

Client Id

Secret

If you want to use curl we provide a working example data link for your company. Just fill in the data below to download the datalink package. To use it just extract all contents to a separate dir and run "export_to_testing.bat". It will automatically export all xml-files and csv-files in the same folder to your iController.

Your iController url

https://

-testing.icontroller.eu

Client Id

Secret