Sitoo Digital Receipts SPI

The Digital Receipts SPI enables external integrations to receive receipt data when receipts are created at a POS, allowing for automated digital receipt delivery.

SPI (Service Provider Interface)

The SPI is the definition of the API required to use the service in Sitoo. Therefore, the external service needs to fully implement the API definition.

Digital Receipt Transactions

The transactions are based on emitted receipts from the POS system. When a transaction is completed and a customer is identified as eligible for digital receipts, the system will send the complete receipt data to the configured endpoint. The receipt includes all transaction details, including items, payments, customer information, and additional metadata.

Stores must have an external store ID, which is used to identify the location where the transaction occurred.

Authentication

The calls' authentications are done using the HTTP basic authentication mechanism. Requests to the endpoint will add an Authorization header to the request. Example:

Authorization: Basic c2l0b286ZGlnaXRhbC1yZWNlaXB0cy1zcGktaW50ZWdyYXRpb24tc2VydmVyLXRva2Vu

Digital Receipt Flow

The POS starts the flow if digital receipts have been configured and it can find a CRM user with an identifier for receipts. It initiates by calling POST /recipient-lookup with the identifier. If the lookup is successful, the receipt will either be sent automatically or by choice, depending on the configuration, using POST /digital-receipts.

Receipt QR Code

A receipt entry can carry a QR code that the merchant configured on the POS profile. Show it at the bottom of the receipt, after the footer text (receiptpost). qrcodecontent is the value to encode, for example a URL, and qrcodemessage is plain text to show directly below the QR code. Both are optional and are only sent when a QR code is configured. The receiving service renders the QR code from qrcodecontent. If the receipt format can't show a QR code, show the content as text or leave it out.

Compatibility

New optional properties can be added to the request bodies without a new API version. The server implementing the SPI must ignore properties it doesn't recognise instead of rejecting the request.

Public Server

The URL used for the service needs to have public access with a valid SSL certificate.

Errors

When a request is not successful, an error object should be returned. It should consist of the request_id, an error_code and an error_data field. The error code is defined as one of the following strings

• bad-request
• unauthorized
• forbidden
• not-found
• too-many-requests
• bad-gateway
• other

Example error message:

{
  "error_code": "bad-request",
  "error_data": {
    "message": "ssn is required"
  },
  "request_id": "123e4567-e89b-12d3-a456-426614174123"
}

Limitations

The following limitations exist for the service.

Customer Identification

The service requires customer identification data to be present in the receipt. Recipients must be identifiable through email, phone number, or personal ID to receive digital receipts.