DIRMEIER
smartschank

REST API for Cash Interface

• 1. Introduction
• 2. Schemas
  • 2.1. Credit
  • 2.2. CreditList
  • 2.3. Debit
  • 2.4. DebitList
• 3. Endpoints
  • 3.1. Credits
    • 3.1.1. GET /credits
    • 3.1.2. POST /credits
    • 3.1.3. GET /credits/{credit_id}
    • 3.1.4. DELETE /credits/{credit_id}
    • 3.1.5. PUT /credits/{credit_id}
  • 3.2. Debits
    • 3.2.1. GET /debits
    • 3.2.2. DELETE /debits
    • 3.2.3. GET /debits/{debit_id}
    • 3.2.4. DELETE /debits/{debit_id}
• 4. Use-Cases
  • 4.1. Send Credit
    • 4.1.1. Workflow:
    • 4.1.2. Example:
  • 4.2. Credit Cancellation
    • 4.2.1. Workflow:
    • 4.2.2. Example:
  • 4.3. Fetch Debits
    • 4.3.1. Workflow:
    • 4.3.2. Example:

1. Introduction

Dirmeier's REST API for Cash Interface provides a contemporary way to communicate between a cash register and Dirmeier's dispensing equipment. It lifts all known methods from the outdated serial communication to an HTTP/REST API, improving the process. No special equipment like serial cables and cash registers with COM-Ports are needed.

2. Schemas

2.1. Credit

{
  "type": "object",
  "properties": {
    "ID": { "type": "number" }, 
    "Waiter": { "type": "number" }, 
    "PLU": { "type": "number" }, 
    "Count": { "type": "number" }, 
    "Table": { "type": "number" },
    "Place": { "type": "number" },
    "ArticleName" : { "type": "string" },
    "StationID": { "type": "number" },
    "CustomerID": { "type": "number" }
  }
  "required": ["ID", "Waiter", "PLU", "Count"]
  // Note: For PUT requests, ID is passed separately as a URL parameter
}

Example:

{
  "Waiter": 1,
  "PLU": 101,
  "Count": 1
}
// Note: ID is passed separately as a URL parameter, (not shown here)

2.2. CreditList

{
  "type": "object",
  "properties": {
    "Credits": {
      "type": "array",
      "items": { "$ref": "#/components/schemas/Credit" }
    }
  }
}

Example:

{
  "Credits": [
    {
      "ID": 11696861732318,
      "Waiter": 2,
      "PLU": 103,
      "Table": 3,
      "Place": 4,
      "StationID": -1,
      "CustomerID": "5",
      "Count": 2
    },
    {
      "ID": 11696861732319,
      "Waiter": 1,
      "PLU": 103,
      "Table": 1,
      "Place": 1,
      "StationID": -1,
      "CustomerID": "3",
      "Count": 2
    }
  ]
}

2.3. Debit

{
  "type": "object",
  "properties": {
    "ID": { "type": "number" },
    "Waiter": { "type": "number" },
    "PLU": { "type": "number" },
    "Place": { "type": "number" },
    "Table": { "type": "number" },
    "Price": { "type": "number" },
    "Articlename": { "type": "string" },
    "Amount": { "type": "number" },
    "Count": { "type": "number" }
  }
}

Example:

{
  "ID": 10820,
  "Waiter": 1,
  "PLU": 201,
  "Place": 0,
  "Table": 5,
  "Price": 0,
  "Articlename": "Bt",
  "Amount": 0,
  "Count": 1
}

2.4. DebitList

{
  "type": "object",
  "properties": {
    "Debits": {
      "type": "array",
      "items": { "$ref": "#/components/schemas/Debit" }
    }
  }
}

Example:

{
  "Debits": [
    {
      "ID": 10820,
      "Waiter": 1,
      "PLU": 201,
      "Place": 0,
      "Table": 5,
      "Price": 0,
      "Articlename": "Cola",
      "Amount": 0,
      "Count": 1
    },
    {
      "ID": 10821,
      "Waiter": 1,
      "PLU": 201,
      "Place": 0,
      "Table": 5,
      "Price": 0,
      "Articlename": "Cola",
      "Amount": 0,
      "Count": 1
    }
  ]
}

3. Endpoints

3.1. Credits

3.1.1. GET /credits

• Summary: Show available Credits in System
• Responses:
  • 200 OK: List of credits (Example: single credit or multiple credits)
  • 410 Gone: No content available
  • 503 Service Unavailable: Service is paused (e.g., during Configuration Mode)

3.1.2. POST /credits

• Summary: Creates an empty credit resource. Sends back uri to empty resource in Location Header Field
• Responses:
  • 201 Created: Resource created successfully

3.1.3. GET /credits/

• Summary: Shows Credit information for a specific credit by ID
• Responses:
  • 200 OK: Credit information for the specified ID
  • 503 Service Unavailable: Service is paused (e.g., during Configuration Mode)

3.1.4. DELETE /credits/

• Summary: Deletes an existing credit by ID
• Responses:
  • 200 OK: Credit deleted successfully
  • 410 Gone: Credit is no longer available or has already been used
  • 503 Service Unavailable: Service is paused (e.g., during Configuration Mode)

3.1.5. PUT /credits/

• Summary: Updates a credit resource identified by ID. Update is only possible for empty Credits. Once Data is set, it can't be overriden.
• Responses:
  • 200 OK: Credit updated successfully
  • 202 Accepted: Service is paused, data received but processed later
  • 400 Bad Request: Invalid request
  • 404 Not Found: Credit not found

3.2. Debits

3.2.1. GET /debits

• Summary: Returns a list of all debits in the system available for transfer to cash. (Get means "view", the data set is still available for transfer)
• Responses:
  • 200 OK: List of debits
  • 410 Gone: No content available
  • 503 Service Unavailable: Service is paused (e.g., during Configuration Mode)

3.2.2. DELETE /debits

• Summary: Deletes an array of debits on smartSCHANK. (Delete means "fetch","transfer to cash")
• Responses:
  • 200 OK: Debits deleted successfully
  • 410 Gone: Debits are no longer available

3.2.3. GET /debits/

• Summary: Get a single debit data set by ID. (Get means "view", the data set is still available for transfer)
• Responses:
  • 200 OK: Debit information for the specified ID
  • 410 Gone: Debit is no longer available
  • 503 Service Unavailable: Service is paused (e.g., during Configuration Mode)

3.2.4. DELETE /debits/

• Summary: Deletes a single debit data set identified by ID. (Delete means "fetch","transfer to cash")
• Responses:
  • 200 OK: Debit deleted successfully
  • 410 Gone: Debit is no longer available

4. Use-Cases

4.1. Send Credit

4.1.1. Workflow:

4.1.2. Example:

1. Creating an Empty Credit:

   POST /credits HTTP/1.1
   Host: http://192.168.2.39/cash/1.0
   Content-Type: application/json
   

   Response:

   HTTP/1.1 201 Created
   Location: /credits/11667928260823
   

2. Updating the Created Credit:

   PUT /credits/11667928260823 HTTP/1.1
   Host: http://192.168.2.39/cash/1.0
   Content-Type: application/json
   
   {
     "Waiter": 3,
     "PLU": 103,
     "Count": 3
   }
   

   Response:

   HTTP/1.1 200 OK
   

4.2. Credit Cancellation

4.2.1. Workflow:

Important Note for Users:
While it is possible to cancel an existing credit with the DELETE endpoint, it is recommendend to use this approach instead. The described cancellation process does not target a specific resource but rather cancels a product (identified by the PLU) from any available credits. For example, if there are two sets of POST & PUT requests, one with a count of 3 and another with a count of 2, these can be cancelled by a new POST followed by a PUT with a count of -5. The DELETE method, on the other hand, removes a specific resource. However, there might be cases where the resource is no longer available in the system, resulting in a 404 response. Therefore, for standard cancellation procedures, it is advisable to use the POST & PUT method. The DELETE method is primarily for handling exceptional cases and might not always be implemented.

4.2.2. Example:

1. Creating an Empty Credit for Cancellation:

   POST /credits HTTP/1.1
   Host: http://192.168.2.39/cash/1.0
   Content-Type: application/json
   

   Response:

   HTTP/1.1 201 Created
   Location: /credits/11667928260824
   

2. Cancelling the Credit with Negative Count:

   PUT /credits/11667928260824 HTTP/1.1
   Host: http://192.168.2.39/cash/1.0
   Content-Type: application/json
   
   {
     "Waiter": 4,
     "PLU": 104,
     "Count": -2
   }
   

   Response:

   HTTP/1.1 200 OK
   

4.3. Fetch Debits

4.3.1. Workflow:

4.3.2. Example:

1. Fetching List of Debits:

   GET /debits HTTP/1.1
   Host: http://192.168.2.39/cash/1.0
   

   Response:

   HTTP/1.1 200 OK
   Content-Type: application/json
   
   {
     "Debits": [
         {
             "ID": 18652,
             "Waiter": 2,
             "PLU": 13,
             "Place": 0,
             "Table": 802,
             "Price": 310.00,
             "Articlename": "Cola 1/2",
             "Amount": 550,
             "Count": 1
         },
         {
             "ID": 18653,
             "Waiter": 2,
             "PLU": 19,
             "Place": 0,
             "Table": 802,
             "Price": 0.00,
             "Articlename": "Orangenlimo 1/4",
             "Amount": 25,
             "Count": 1
         },
         {
             "ID": 18654,
             "Waiter": 2,
             "PLU": 19,
             "Place": 0,
             "Table": 802,
             "Price": 0.00,
             "Articlename": "Orangenlimo 1/4",
             "Amount": 25,
             "Count": 1
         }
       ]
     }
   

2. Deleting a Specific Debit:

   DELETE /debits/18652 HTTP/1.1
   Host: http://192.168.2.39/cash/1.0
   

   Response:

   HTTP/1.1 200 OK
   

3. Deleting Multiple Debits:

   DELETE /debits HTTP/1.1
   Host: http://192.168.2.39/cash/1.0
   Content-Type: application/json
   
   {
     "Debits": [
         {
             "ID": 18653,
             "Waiter": 2,
             "PLU": 19,
             "Place": 0,
             "Table": 802,
             "Price": 0.00,
             "Articlename": "Orangenlimo 1/4",
             "Amount": 25,
             "Count": 1
         },
         {
             "ID": 18654,
             "Waiter": 2,
             "PLU": 19,
             "Place": 0,
             "Table": 802,
             "Price": 0.00,
             "Articlename": "Orangenlimo 1/4",
             "Amount": 25,
             "Count": 1
         }
       ]
     }
   

   Response:

   HTTP/1.1 200 OK