# C# Integration

Before the integration can begin, artifactory must be added as source so that the NuGet packages can be installed. Instructions on how to do this can be found here.

# Required Packages

The following packages must be installed:

anybill.POS.Client
anybill.POS.Client.Abstractions

Optional Packages:

anybill.POS.Client.Microsoft.Extensions.DependencyInjection
anybill.POS.Client.Newtonsoft

# Initialization

After all required packages are installed, you can continue with the initialization of the AnybillClientFactory and the creation of the AnybillClient. For this the following parameters are necessary:

Username
Password
ClientId

var clientFactory = new AnybillClientFactory();
var anybillClient = clientFactory.Create(x => x.WithUsername(username).WithPassword(password).WithClientId(clientId), AnybillEnvironment.Staging);

The environment can be optionally added when creating the AnybillClient. By default, Production is stored here.

# Authentication

After the AnybillClient exists, the authentication can be executed in a second step. An AccessToken is requested and stored internally.

await anybillClient.Authentication.EnsureAsync();

# Register new bill

If you want to display a QR code already during the checkout process and before the purchase is completed, you can request a new BillId using the RegisterIdAsync method.

var registerBillId = new RegisterBillId
{
    StoreId = storeId
};

var registerBillIdResponse = await anybillClient.Bill.RegisterIdAsync(registerBillId);

switch (registerBillIdResponse)
{
    case IRegisterBillIdUrlResponse registerBillIdUrlResponse:
        // do something
        break;
    case IRegisterBillIdExternalIdResponse registerBillIdExternalResponse:
        // do something
        break;
}

The result is an interface of type IRegisterBillIdUrlResponse or IRegisterBillIdExternalIdResponse. The difference between the 2 interfaces is that the IRegisterBillIdExternalIdResponse only contains the BillId, while the IRegisterBillIdUrlResponse additionally contains the Url to display the QR code. Since IRegisterBillIdExternalIdResponse has already been assigned to a user, it is no longer necessary to display the QR code here.

# Add Bill

Adding the bill is composed of the bill itself and the associated billOptions. As a result one of the following interfaces is returned:

IExternalIdResponse
ILoyaltyCardResponse
IMatchedBillResponse
IUrlBillResponse
IUserIdResponse

var billResponse = await anybillClient.Bill.CreateAsync(bill, billOptions);

switch (billResponse)
{
    case IExternalIdResponse externalIdResponse:
        // do something
        break;
    case ILoyaltyCardResponse loyaltyCardResponse:
        // do something
        break;
    case IMatchedBillResponse matchedBillResponse:
        // do something
        break;
    case IUrlBillResponse urlBillResponse:
        // do something
        break;
    case IUserIdResponse userIdResponse:
        // do something
        break;
}

# Exception Handling

The following list describe all exceptions which can occur in case of an error.

AuthenticationException: Occurs when authentication fails, e.g. when no username is specified.
BadRequestException: Occurs when the request fails. For example due to a validation error.
ForbiddenException: Occurs when the user does not have the necessary rights to access this endpoint.
NotFoundException: Occurs when the endpoint could not be found.
UnauthorizedException: Occurs when the user is not authenticated.
UnhandledException: Occurs if an unexpected error occurs.

# Example

The following example shows the simplest implementation of the C# SDK and should serve as a help.

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using anybill.POS.Client.Exceptions;
using anybill.POS.Client.Factories;
using anybill.POS.Client.Models.Bill;
using anybill.POS.Client.Models.Bill.CashRegister;
using anybill.POS.Client.Models.Bill.Data;
using anybill.POS.Client.Models.Bill.Data.VatAmount;
using anybill.POS.Client.Models.Bill.Head;
using anybill.POS.Client.Models.Bill.Misc;
using anybill.POS.Client.Models.Bill.Misc.Extension;
using anybill.POS.Client.Models.Bill.Response;
using anybill.POS.Client.Models.Bill.Security;
using anybill.POS.Client.Models.Bill.Security.Extension;
using anybill.POS.Client.Options;

namespace POSLibraryTestProject
{
    class Program
    {
        static async Task Main(string[] args)
        {
            // necessary login data + storeId
            const string username = "";
            const string password = "";
            const string clientId = "";
            const string storeId = "";
            
            // bill object with billOptions
            var bill = new AddBill
            {
                StoreId = storeId,
                Bill = new Bill()
                {
                    CashRegister = new CashRegister()
                    {
                      SerialNumber  = "1234",
                    },
                    Head = new Head()
                    {
                        Date = DateTimeOffset.Now
                    },
                    Data = new Data()
                    {
                        Currency = "EUR",
                        VatAmounts = new List<DataVatAmount>()
                        {
                            new()
                            {
                                Percentage = 7,
                                Vat = (decimal)1.00,
                                ExclVat = (decimal)12.00,
                                InclVat = (decimal)13.00
                            }
                        }
                    },
                    Security = new Security()
                    {
                        Extension = new AnybillSecurityExtension()
                        {
                            TseFailure = true,
                            TseRequired = false
                        }
                    },
                    Misc = new Misc()
                    {
                        Extension = new AnybillMiscExtension()
                        {
                            IsExample = true,
                            IsInvoice = false
                        }
                    }
                }
            };
            var billOptions = new AddBillOptions();

            // registerBillId object
            var registerBillId = new RegisterBillId
            {
                StoreId = storeId
            };

            // create clientFactory and anybillClient
            var clientFactory = new AnybillClientFactory();
            var anybillClient = clientFactory.Create(x => x.WithUsername(username).WithPassword(password).WithClientId(clientId), AnybillEnvironment.Staging);

            try
            {
                // 1. create authentication token
                await anybillClient.Authentication.EnsureAsync();

                // 2. create preGenerated billID (if necessary)
                var registerBillIdResponse = await anybillClient.Bill.RegisterIdAsync(registerBillId);
                switch (registerBillIdResponse)
                {
                    case IRegisterBillIdUrlResponse registerBillIdUrlResponse:
                        Console.WriteLine("BillID: " + registerBillIdUrlResponse.BillId);
                        Console.WriteLine("GetMy website: " + registerBillIdUrlResponse.Url);
                        break;
                    case IRegisterBillIdExternalIdResponse registerBillIdExternalResponse:
                        Console.WriteLine("BillID: " + registerBillIdExternalResponse.BillId);
                        break;
                }

                // 3. add Bill
                var billResponse = await anybillClient.Bill.CreateAsync(bill, billOptions);
                switch (billResponse)
                {
                    case IExternalIdResponse externalIdResponse:
                        Console.WriteLine("IsAssigned: " + externalIdResponse.IsAssigned);
                        break;
                    case ILoyaltyCardResponse loyaltyCardResponse:
                        Console.WriteLine("IsAssigned: " + loyaltyCardResponse.IsAssigned);
                        break;
                    case IMatchedBillResponse matchedBillResponse:
                        Console.WriteLine("IsAssigned: " + matchedBillResponse.IsAssigned);
                        break;
                    case IUrlBillResponse urlBillResponse:
                        Console.WriteLine("GetMy website: " + urlBillResponse.Url);
                        break;
                    case IUserIdResponse userIdResponse:
                        Console.WriteLine("IsAssigned: " + userIdResponse.IsAssigned);
                        break;
                }
            }
            catch (AuthenticationException authenticationException)
            {
                // Authentication failed because username, password or clientId is wrong.
                Console.WriteLine(authenticationException);
            }
            catch (BadRequestException badRequestException)
            {
                // Request failed. e.g. validation error.
                Console.WriteLine(badRequestException.Body);
            }
            catch (ForbiddenException forbiddenException)
            {
                // Request failed because user is not allowed to use the called endpoint.
                Console.WriteLine(forbiddenException);
            }
            catch (NotFoundException notFoundException)
            {
                // Request failed because called endpoint does not exists.
                Console.WriteLine(notFoundException);
            }
            catch (UnauthorizedException unauthorizedException)
            {
                // Request failed because user is not authorized.
                Console.WriteLine(unauthorizedException);
            }
            catch (UnhandledException unhandledException)
            {
                // Request failed for some reason.
                Console.WriteLine(unhandledException);
            }
            catch (Exception exception)
            {
                Console.WriteLine(exception);
            }
        }
    }
}

# Changelog

# 2022-06-20 (Version 3.0.0.14)

Added Ean128 to the AfterSalesCouponType in the AfterSalesCouponsDto

# 2022-05-29 (Version 3.0.0.13)

Added isPrintBuffer to the SDK

# 2022-05-02 (Version 3.0.0.12)

Added user endpoints to the SDK
added customer endpoints to the SDK

# 2022-04-28 (Version 3.0.0.11)

Added phoneNumber to head.extension:anybill
Added new type Barcode to the ReturnBarcodeType

# 2022-03-15

Added new optional attribute alignment in textCustomSectionData to align the text on the PDF receipt.
Adjusted user not found object when user couldn't find using the userIdentification object.

← Configuration Java Integration →