.NET

The Tables API is now archived. For up-to-date Pay at Table integrations, please use the Dojo API and EPOS Data API:

Dojo API
EPOS Data API (REST)
EPOS Data API (WebSocket)

Learn how to work with Dojo's .NET EPOS SDK for the Tables API.

The Dojo.Net.EPOS NuGet package simplifies integration with the Tables API. It offers a collection of C# interfaces and classes that facilitate interaction with the API, simplify WebSocket connection management, and handle various request and response formats.

Installing the SDK

The fastest way to start using the package is to install it using the .NET CLI dotnet add package command in your project directory:

dotnet add package Dojo.Net.EPOS

Alternatively, you can search for and install the package using the NuGet Package Manager in Visual Studio. The package page also includes commands for several other CLI formats, as well as an XML PackageReference option.

Using the package

Follow these three steps to implement the ITablesAPIServer interface, create a DojoTablesConnector instance, and pass the ITablesAPIServer instance to the connector.

Step 1. Implement the interface

Create a class that implements the ITablesAPIServer interface. This interface contains several methods that correspond to different API endpoints. You should provide custom implementation for each method.

public class MyTablesAPIServer: ITablesAPIServer {
  public async Task <ListSessionsResponse> AcceptMessageAsync(ListSessionsRequest request) {
    // Your custom implementation for handling the ListSessions request
  }
  public async Task <GetFullBillResponse> AcceptMessageAsync(GetFullBillRequest request) {
    // Your custom implementation for handling the GetFullBill request
  } 
  {
    // ... other methods from the ITablesAPIServer interface
  }
}

Step 2. Create a connector class

Create an instance of the DojoTablesConnector class and pass the required parameters as arguments:

• accountName - This is provided by your Partnership Development Manager (PDM).
• apiKey - The API key is used for authentication and is also provided by the PDM.
• softwareHouseId - This identifies the EPOS company you are working with to drive your integration. This value shouldn't be configurable — it will remain the same for all customers using particular EPOS software.
• isSandbox - This is an optional boolean. Set it to true for the sandbox environment, or false for the production environment.

var accountName = "your_account_name";
var apiKey = "your_api_key";
var softwareHouseId = "your_software_house_id";
var isSandbox = true; // or false for the production environment

var dojoTablesConnector = new DojoTablesConnector(accountId, apiKey, softwareHouseId, isSandbox);

Step 3. Pass the request handler to the API connector

Instantiate your implementation of the ITablesAPIServer interface and pass it to the DojoTablesConnector instance:

var myTablesAPIServer = new MyTablesAPIServer();

Now, call the StartAsync method on the DojoTablesConnector instance and pass the myTablesAPIServer instance and a cancellationToken:

await dojoTablesConnector.StartAsync(myTablesAPIServer, cancellationToken);

The code creates an instance of myTablesAPIServer and then starts the DojoTablesConnector by calling its StartAsync method with the myTablesAPIServer instance and a cancellationToken.

Stopping DojoTablesConnector

To stop the DojoTablesConnector, cancel the cancellationToken that you passed to the StartAsync method. This will close the WebSocket connection and stop any ongoing communication with the Dojo Tables API.

Here's an example of how you can stop the DojoTablesConnector using a CancellationTokenSource:

First, instantiate a CancellationTokenSource:

var cancellationTokenSource = new CancellationTokenSource();

Then pass the CancellationToken from the CancellationTokenSource to the StartAsync method:

await dojoTablesConnector.StartAsync(myTablesAPIServer, cancellationTokenSource.Token);

When you're ready to stop the DojoTablesConnector, call Cancel on the CancellationTokenSource:

cancellationTokenSource.Cancel();

Error handling

When your EPOS cannot process a request while implementing the ITablesAPIServer interface, it's important it returns the correct TablesErrorCode. The TablesException will be serialized and sent back to the Dojo server.

For example, consider a situation where you are implementing the AcceptMessageAsync(GetSessionRequest request) method from the ITablesAPIServer interface. If your EPOS can't find the requested session, the response should include a TablesException with the SessionNoSuchSession error code:

public async Task<GetSessionResponse> AcceptMessageAsync(GetSessionRequest request)
{
    // ... Your code to retrieve the session

    if (sessionDoesNotExist)
    {
        throw new TablesException(TablesErrorCode.SessionNoSuchSession, "The requested session does not exist.");
    }

    // ... Your code to return a GetSessionResponse
}

By responding with a TablesException with the appropriate error code and message, your EPOS is providing valuable information about the error scenario to the Dojo server.

Error code	Description
SessionNoSuchSession	The requested session does not exist.
SessionNotLocked	The requested session is not locked.
SessionAlreadyLocked	The requested session is already locked.
SessionUnableToUnlock	The EPOS is unable to unlock the requested session due to internal reasons.
PaymentNotRecorded	The EPOS cannot record the payment due to internal reasons.
PaymentAlreadyRecorded	The payment has already been recorded for the requested session.
ErrorParseError	The message sent by the Dojo cannot be read by the EPOS server.
ErrorInternalPosError	An internal EPOS error occurred while processing the request.
TableNoSuchTable	The requested table does not exist.
BillNoSuchBill	The requested bill does not exist.
WaiterIncorrectWaiterId	The provided waiter ID is incorrect or does not exist.

Logging

You can integrate your own ILogger instance with the DojoTablesConnector to handle logging during the connector's operation. To do this, follow these steps:

1. Ensure you have the necessary NuGet packages installed for logging, such as Microsoft.Extensions.Logging.
2. Either create a new ILogger instance in your project, or use an existing one.
3. Pass the ILogger instance as an argument to the DojoTablesConnector constructor.

Here's an example of how to create a simple console logger for the DojoTablesConnector.

First, import the logging namespaces and create an ILoggerFactory using LoggerFactory.Create.

using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.Console;

using ILoggerFactory loggerFactory =
    LoggerFactory.Create(builder =>
        builder.AddSimpleConsole(options =>
        {
            options.IncludeScopes = true;
            options.SingleLine = true;
            options.TimestampFormat = "HH:mm:ss";
        }));

Create an instance of the logger by calling the CreateLogger method:

ILogger<Program> TablesLogger = loggerFactory.CreateLogger<Program>();

Initialize the DojoTablesConnector with the ILogger instance

Create a new instance of the DojoTablesConnector class and pass the authentication parameters in a constructor. Then, pass the TablesLogger created earlier as a property:

DojoTablesConnector connector = new DojoTablesConnector(accountId, apiKey, softwareHouseId, isSandbox)
{
    ResellerId = resellerId, // optional    
    Logger = TablesLogger 
};

For any requests, bugs, or comments, open an issue or submit a pull request at the Dojo.Net.EPOS GitHub repository.