PoS Integration

This documentation describes the Snabble API endpoints related to the Point of Sale (PoS) integration. These endpoints are available on the api subdomain. See General API access for general information about api access.

Operations

• Get checkout process: GET /{project}/pos/checkout/id/{id}
• Update checkout process: PUT /{project}/pos/checkout/id/{id}
• Partially update checkout process: PATCH /{project}/pos/checkout/id/{id}

Data Model

• Checkout Process

Workflow

The integration of Snabble into a Point of Sale software system (PoS) is implemented through a handover of an identifier from the Snabble app to the PoS using a standard QR-Code. After the handover the PoS can fetch and process the checkout. Finally, it updates it to reflect the outcome of the process.

The QR-Code presented by the user contains the identifier of the checkout process. It looks like this:

snabble:752dd716-ec0c-11e8-8528-68f7286a148f

The string after the colon is the identifier of the checkout process.

To build the URL of the process the base URL of the used Snabble environment (see General API access: Environments), the identifier of the project and the identifier of the checkout are required. This is the URL template:

<base URL>/<project id>/pos/checkout/id/<checkout id>

ie. https://api.snabble.io/test-project-12345/pos/checkout/id/752dd716-ec0c-11e8-8528-68f7286a148f.

After the PoS has accessed the identifier of the checkout process form the QR-Code and has build the URL as above, it should perform a request to update the state of the checkout process to processing. This communicates that it started to handle the checkout process. Additionally it might identify itself by sending an unique identifier. The service responds with the complete updated checkout process, which should be used by PoS to process the checkout. The call to the service might look like:

PATCH /project/pos/checkout/id/752dd716-ec0c-11e8-8528-68f7286a148f HTTP/1.1
Host: api.snabble.io
Content-Type: application/merge-patch+json
Authoirization: Bearer ...

{
  "state": "processing",
  "processedBy": "pos-1"
}

The service responds with:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "lineItems" : [
    {
      "scannedCode": "0000000000001",
      "totalPrice" : 798,
      "amount" : 2,
      "price" : 399,
      "taxRate" : 19,
      "sku" : "1"
    },
    {
      "scannedCode": "0000000000002"
      "price" : 1099,
      "totalPrice" : 1099,
      "amount" : 1,
      "taxRate" : 19
    }
  ],
  "taxShares" : [
    { "rate": "19", "net": "40382", "share": "7673", "total": "48055" }
  ],
  "netPrice" : 40382,
  "totalPrice" : 48055,
  "state": "processing",
  "processedBy": "pos-1",
  "loyaltyCard": "12345678"
}

After successfully processing the checkout the PoS should update the checkout process. It should update the line items and the price to reflect the performed checkout. Further, it should set the state to successful.

PATCH /project/pos/checkout/id/752dd716-ec0c-11e8-8528-68f7286a148f HTTP/1.1
Host: api.snabble.io
Content-Type: application/merge-patch+json
Authoirization: Bearer ...

{
  "lineItems" : [
    {
      "scannedCode": "0000000000001",
      "totalPrice" : 798,
      "amount" : 2,
      "price" : 399,
      "taxRate" : 19,
      "sku" : "1"
    },
    {
      "scannedCode": "0000000000002"
      "price" : 1099,
      "totalPrice" : 1099,
      "amount" : 1,
      "taxRate" : 19
    }
  ],
  "taxShares" : [
    { "rate": "19", "net": "40382", "share": "7673", "total": "48055" }
  ],
  "netPrice" : 40382,
  "totalPrice" : 48055,
  "state": "successful",
  "loyaltyCard": "12345678"
}

If the checkout could not be performed, the PoS should update the checkout process and set its state to failed. Optionally the PoS can provide an informal failedReason message, which describes the conditions of the failure.

PATCH /project/pos/checkout/id/752dd716-ec0c-11e8-8528-68f7286a148f HTTP/1.1
Host: api.snabble.io
Content-Type: application/merge-patch+json
Authorization: Bearer ...

{
  "state": "failed",
  "failedReason": "Payment failed"
}

Data Model

Checkout Process

Parameter	Type	Default	Description
lineItems	LineItem[]		List of the line items. See Line Item
taxShares	TaxShare[]	null	List of tax shares
netPrice	int		Net price
totalPrice	int		Total price
state	PaymentState		The Status of the payment process. Only pending, processing, successful, failed are used in this case
loyaltyCard	String		The loyalty card identifier provided by the user
processedBy	String		String identifying the PoS which processes the checkout process
failedReason	String		Message describing the conditions under which the checkout process was marked as failed

Tax Shares

Parameter	Type	Default	Description
rate	string		Tax rate as string encoded decimal
net	int		Net portion
share	int		Tax share for this rate
total	int		The total

Line Item

Parameter	Type	Default	Description
scannedCode	string		Scanned code
amount	int		Number of products / packages
weight	int	0	Weight of product in case of a weighable (a not packaged) product
units	int	0	Number of units in a package in case of bundle or piece product
price	int		The base price of one product / unit
totalPrice	int		The total price
taxRate	string		Tax rate as string encoded decimal

Example

{
  "lineItems" : [
    {
      "scannedCode": "0000000000001",
      "totalPrice" : 798,
      "amount" : 2,
      "price" : 399,
      "taxRate" : 19,
      "sku" : "1"
    },
    {
      "scannedCode": "0000000000002"
      "price" : 1099,
      "totalPrice" : 1099,
      "amount" : 1,
      "taxRate" : 19
    }
  ],
  "tax" : {
    "19" : 7673
  },
  "taxNet" : {
    "19" : 40382
  },
  "netPrice" : 40382,
  "price" : 48055,
  "state": "pending",
  "loyaltyCard": "12345678",
  "processedBy": "pos-1"
}

Get Checkout Process

GET /{project}/pos/checkout/id/{id}

Get the state of a Checkout Process.

Required permissions : checkoutRead for the checkout process

Success Response 200 OK

Content-Type : application/json

Data : Checkout Process

---

PUT Checkout Process

PUT /{project}/pos/checkout/id/{id}

Update the state of a Checkout Process.

Required permissions : updatePricingCheckoutProcess for the checkout process

Request

Content-Type : application/json

Data : Checkout Process.

Success Response 200 OK

Content-Type : application/json

Data : Checkout Process

---

PATCH Checkout Process

PATCH /{project}/pos/checkout/id/{id}

Partially update the state of a Checkout Process.

The patch is applied according to RFC 7386.

Required permissions : updatePricingCheckoutProcess for the checkout process

Request

Content-Type : application/merge-patch+json

Data : Checkout Process.

Success Response 200 OK

Content-Type : application/json

Data : Checkout Process

---