Getting Started Without Sdk

GraphQl Interface

The GraphQl is the FDM 2.0 interface to communicate with the outside world. So every POS system should have a way to talk GraphQl if it wants to interface with the Checkbox or any FDM 2.0.

GraphQL is a powerful query language for APIs that allows you to request exactly the data you need, making communication between a client and server more efficient. Unlike REST, which returns fixed data structures, GraphQL lets clients specify their exact requirements in a single query, reducing multiple requests and improving performance.

To get started, you typically define types and queries in a GraphQL schema, and clients send queries to fetch or modify data. GraphQL servers can be set up in many programming languages, while clients use tools to interact with these APIs.

Connection Settings

  1. Locate Network Settings

    • To find the actual network address of a Checkbox, open the CheckTools application.
    • All network settings for each Checkbox are published and accessible in this application.

  2. Scan for mDNS

    • Alternatively, you can scan the network where the Checkbox is connected to for an mDNS record.
    • Each Checkbox advertises its FdmId on the network.

  3. Using the Checkbox Emulator

    • If you're working with a Checkbox Emulator, its network address can also be found in the CheckTools application.

Accessing the GraphQL API

Once you have determined the base address for either a physical Checkbox or the emulator, you can access the GraphQL API at the following endpoint:
{baseAddress}/graphql

A Simple Work In Mutation

As an example we will send a WorkIn mutation to the Api, with proper data, in order to get a result back.

Registration of "Work In" of employee (employeeId 80113078968)

Bash 
        
mutation SignWorkIn($data: WorkInOutInput!, $training: Boolean! = false)
{
    signWorkIn(data: $data, isTraining: $training)
    {
        posId
        posFiscalTicketNo
        posDateTime
        terminalId
        deviceId
        fdmSwVersion
        eventOperation
        digitalSignature
        bufferCapacityUsed
        fdmRef {
            fdmId
            fdmDateTime
            eventLabel
            eventCounter
            totalCounter
        }
        warnings {
            message
            locations {
                line
                column
            }
            extensions {
                category
                code
                showPos
                data {
                    name
                    value
                }
            }
        }
        informations {
            message
            locations {
                line
                column
            }
            extensions {
                category
                code
                showPos
                data {
                    name
                    value
                }
            }
        }
        footer
    }
}

Actual Data for the mutation

The data is then provided with a Json object, the mutation will now be executed with this data as the input object.

XML 
        
{
  "data": {
    "language": "NL",
    "vatNo": "BE0000000097",
    "estNo": "2000000042",
    "posId": "CPOS0031234568",
    "posFiscalTicketNo": 1010,
    "posDateTime": "2024-07-29T15:50:39+02:00",
    "posSwVersion": "1.8.3",
    "terminalId": "POS-2-REC",
    "deviceId": "80:1A:A6:75:66:FC",
    "bookingPeriodId": "dffcd829-a0e5-41ca-a0ae-9eb887f95637",
    "bookingDate": "2024-07-29",
    "ticketMedium": "NONE",
    "employeeId": "80113078968"
  }
}

The response from our mutation

If everything goes well, the Checkbox will answer with a response to the mutation. In our case this is a possible answer from the Checkbox

Bash 
        
{
  "data": {
    "signWorkIn": {
      "posId": "CPOS0031234568",
      "posFiscalTicketNo": 1010,
      "posDateTime": "2024-07-29T15:50:39+02:00",
      "terminalId": "POS-2-REC",
      "deviceId": "80:1A:A6:75:66:FC",
      "eventOperation": "WORK_IN",
      "fdmRef": {
        "fdmId": "FOD01000002",
        "fdmDateTime": "2024-07-29T13:50:39Z",
        "eventLabel": "S",
        "eventCounter": 7,
        "totalCounter": 30
      },
      "fdmSwVersion": "1.2.0",
      "bufferCapacityUsed": 0.25,
      "digitalSignature": "c7uwqjLZ+Wk+R8swA/KHilWp4qCPK4u1L6TGxuCOJbf7bY32Ra2G8NiI+TO9lFGNFTfU1UA/8HGiccVzMQrUcA==",
      "warnings":[],
      "informations": [],
      "footer": []
    }
  }
}

Important for an Emulator

If you want to talk to an emulator, it is very important to add 2 extra http headers to your GraphQl Request.

You need the Checkbox Client Key and also the actual Emulator Id you want to use to sign the request. So there should actually be 2 headers added to the request with their appropriate value. Those values can also be found in the CheckTools app.

  1. checkbox-client-key
  2. checkbox-id

Once those headers are in, the emulator will give you the correct answers. For a physical box these headers are not needed. But if they are present, it will also work fine.

GraphQl tooling

There are several tools on the world wide web you can use to send mutations, you can use Postman as a tool, for the emulator, we have integrated a Graphical UI on the endpoint, you can just simply browse to that endpoint, and fill in everything you have to send the mutation. You can also set the HTTP header values in the graphical UI.

This can only be used with the emulator!