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

Note!

Do not use the Sitoo API credentials for authenticating the call. The server implementing the SPI needs to have its own implementation of authentication.

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.

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.