Getting Started With Sdk

Prior knowledge

A notion is required of C# for following examples.

You will also need .Net SDK to complete this tutorial

The SDK can be downloaded here .

Create your first project

In this example you will create a very simple cash register, the program will connect with the Checkbox, and it will send a first transation to the Checkbox, this will sign the transaction if possible and return a result to the cash register.

First we need to create a folder where you wish to create the project. Open a terminal (Windows, Linux, ...) and navigate to the newly created folder.

        
mkdir SimpleCashRegister
cd SimpleCashRegister
dotnet new sln -n SimpleCashRegister

This creates the SimpleCashRegister solution directory, this directory will serve as a base to contain all the projects for this tutorial.

You can execute the commands from this directory to add a console application to the solution.

Bash

        
mkdir src
cd src
dotnet new console -n CheckboxSign

A new folder will be created src/CheckboxSign where the project will reside.

CheckboxSign.csproj - project file
program.cs - main starting point of the program

Next, lets add a project to the solution with these commands.

Bash

        
cd ..
cd ..
dotnet sln add ./src/CheckboxSign

code ./

You can now open the solution with your preferred editor. In this example we will use Visual Studio Code.

Running the project

To start this simple program we just need to run following command.

Bash

        
cd src/CheckboxSign
dotnet run

Voeg de Checkbox SDK toe aan het project

Via nuget we will add a few packages to the project in order to be able to communicate with the Checkbox. Since we will use Dependency Injection as well we need to add these 2 packages

Checkbox.Fdm.Sdk - This SDK will handle all communication with the Checkbox.
Microsoft.Extensions.Hosting - With this package we will be able to use Dependency Injection.

Bash

        
dotnet add package Checkbox.Fdm.Sdk
dotnet add package Microsoft.Extensions.Hosting

Configure the Checkbox Sdk

Adjust the file program.cs like this so we will setup dependency injection (DI) and configure the SDK in our setup.

        
//Add on top of the program.cs file
using Checkbox.Fdm.Sdk;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

//Create the Dependency Injector host
var host = CreateHostBuilder(args).Build();


//Configure DI for this console app, place this at the bottom of the program.cs file
static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureServices(services =>
        {
            services.AddCheckbox("Uw Client Key");
        });

Now we need to inject the correct Checkbox Service

So we now configured the service so we can use it. We now need to fetch the required service via GetRequiredService,On the otherhand you can also simply inject it in a constructor like normal DI..

This will now handle our communication with the Checkbox. Lets initialize it a little more so it is ready to send the first transaction..

var myCheckboxService = host.Services.GetRequiredService<ICheckboxService>();

Initialize our physical Checkbox with the service

A checkbox can automatically fetch its settings via the SDK, so the configuration is not need to be set manually. But this is also an option off course.
Lets show both examples here. We can also initialize more than 1 checkbox with the service, in order to have failover handling in case one FDM is down for some reason. So the POS can continue working even if an FDM is failing.

        
var allCheckboxesInitialized = await myCheckboxService.InitializeCheckboxesAsync(
    ["Checkbox Id 1", "Checkbox Id 2"]);

OR a manual configuration

        
var allCheckboxesInitialized =  await myCheckboxService.InitializeCheckboxManuallyAsync(
            "Your Checkbox Id", new FdmSettings("192.168.1.100", bearer: "Your Checkbox Token"));

Checkbox Service is ready

At this point we are ready to send transactions and process them.

Lets define a imaginary POS system with employees, terminals etc.

        
// Define your company
Company myRestaurant = new()
{
    VatNo = "BE0000000097",
    EstNo = "200000000"
};

// Define all your terminals
PosTerminal myPosTerminal = new()
{
    DeviceId = "1631678d-7a85-4ac3-b296-bb4565e873fe",
    TerminalName = "POS-TERMINAL"
};

//Define all your employees
Employee myEmployee = new()
{
    FullName = "Francis",
    Insz = "84022899837"
};

// Define all your Pos systems
PosSystem myPos = new()
{
    PosId = "CPOS0031234567",
    SoftwareVersion = "1.0.0"
};

// Define the current pooking period
BookingPeriod myBookingPeriod = new()
{
    BookingDate = DateTime.Now.Date,
    BookingPeriodId = Guid.NewGuid()
};

Let Francis start his shift with the WorkIn Mutation

Everything is now ready to just transmit the request to the Checkbox. Lets do this now.

        
// Create a new action for an employee to start its work, this is done for myRestaurant, on myPos and on myPosTerminal
PosWorkAction workInAction = new PosWorkAction(myRestaurant, myPos, myPosTerminal, myEmployee)
{
    //The Pos system is handling the number of the action to sign, this should always increase for each action it wants to sign
    SalesActionNumber = 1,
    //The type of Work action
    Type = WorkType.WORK_IN
};

//Actual signing of this action
var result = await myCheckboxService.SignPosAction(workInAction);

The result will be yielded from the Checkbox. It can also contain errors. The result (with errors) need to be handled by the POS system.

Congratulations, you have completed the first transaction with success. You have a working connection, and now you can go further with the following cases.

Complete Program.cs

        
using Checkbox.Fdm.Core.PosModels;
using Checkbox.Fdm.Core.PosModels.Actions;
using Checkbox.Fdm.Sdk;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

Console.WriteLine("Hello, Checkbox!");

var host = CreateHostBuilder(args).Build();

// Fetch the checkbox service that will handle all future signings
var myCheckboxService = host.Services.GetRequiredService<ICheckboxService>();

var allCheckboxesInitialized = await myCheckboxService.InitializeCheckboxesAsync(
    ["Checkbox Reference Id"],
    CheckboxLoadbalancingMode.Manual);

// Define your company
Company myRestaurant = new()
{
    VatNo = "BE0000000097",
    EstNo = "200000000"
};

// Define all your terminals
PosTerminal myPosTerminal = new()
{
    DeviceId = "1631678d-7a85-4ac3-b296-bb4565e873fe",
    TerminalName = "POS-TERMINAL"
};

//Define all your employees
Employee myEmployee = new()
{
    FullName = "Francis",
    Insz = "84022899837"
};

// Define all your Pos systems
PosSystem myPos = new()
{
    PosId = "CPOS0031234567",
    SoftwareVersion = "1.0.0"
};

// Create a new action for an employee to start its work
PosWorkAction workInAction = new PosWorkAction(myRestaurant, myPos, myPosTerminal, myEmployee)
{
    //The date where this action is booked on
    BookingDate = DateTime.Now,
    //A Pos system should handle the bookingperiods
    BookingPeriodId = Guid.NewGuid(),
    //The Pos system is handling the number of the action to sign, this should always increase for each action it wants to sign
    SalesActionNumber = 1,
    //The type of Work action
    Type = WorkType.WORK_IN
};

//Actual signing of this action
var result = await myCheckboxService.SignPosAction(workInAction);

//Handle The result

return;

//Configure DI for this console app
static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureServices(services =>
        {
            services.AddCheckbox("Your Checkbox API Key");
        });

After this tutorial you can continue with actual examples, like a real Pos system will handle them.

There are example scenarios coming from FOD. We will handle them with the Checkbox SDK to show you how to handle them.