Simphony Transaction Services Gen2 API Guide

All REST Endpoints

Checks API

The STS Gen2 Checks API is used to create and manage the checks within a revenue center (use the Organization Service to locate a revenue center). Configuration content (for example, menu items or discounts) from the Configuration API is used to populate a check.

Paths

The {basePath} for resources on the Checks API is:

https://{host/path}/api/v1/

The Checks API provides access to the get and modify checks in a revenue center. The context of the operation is defined by the {orgShortName}, {locRef}, and {rvcRef} parameters. In many cases the operations are executed by routing request to on-premises services. This has an increased latency over requests that are processed by cloud-base services.

Check operations that include a check in the request, get the value of the {orgShortName}, {locRef}, and {rvcRef} from the request body via the check header. Check operations that do not include check in the requests, specify these values in the header.

Delete a check: Method: delete
Path: {basePath}/checks/{checkRef}
Get a check: Method: get
Path: {basePath}/checks/{checkRef}
Get a list of checks: Method: get
Path: {basePath}/checks
Get printed check: Method: get
Path: {basePath}/checks/{checkRef}/printed
Post a new check: Method: post
Path: {basePath}/checks
Post a new round to a check: Method: post
Path: {basePath}/checks/{checkRef}/round
Post calculate totals for a check: Method: post
Path: {basePath}/checks/calculator

Checks API/Connection Status

The STS Gen2 Connection Status API is used to retrieve the connection status for a specified revenue center.

Paths

The {basePath} for resources on the Connection Status API is:

https://{host/path}/api/v1/

API to indicate status of check processing for a revenue center.

This request checks to see if STS has a connection for this property. The value of the connection status now does not represent a guarantee that the connection status will be the same at any point in the future.

Head connection status: Method: head
Path: {basePath}/checks/connectionStatus

Configuration API

The STS Gen2 Configuration Service is used to interact with POS system configuration including tables, menus, discounts, service charges, and tenders. Items are configured for each revenue center. Available revenue centers can be obtained from the Organization Service.

Paths

The {basePath} for resources on the Configuration API is:

https://{host/path}/api/v1/

The Configuration API provides access to the menu, discount, service charge, and tender resources configured for a revenue center.

Because each revenue center is uniquely identified by a combination of the {orgShortName}, {locRef}, and {rvcRef} then the path to each of the resources includes these values.

Get a menu: Method: get
Path: {basePath}/menus/{menuId}
Get a summary of all available menus: Method: get
Path: {basePath}/menus/summary
Get tax definitions: Method: get
Path: {basePath}/taxes
Get the barcode collection: Method: get
Path: {basePath}/barcodes/collection
Get the collection of unavailable menu items: Method: get
Path: {basePath}/menus/items/unavailable
Get the discount collection: Method: get
Path: {basePath}/discounts/collection
Get the service charge collection: Method: get
Path: {basePath}/serviceCharges/collection
Get the tender collection: Method: get
Path: {basePath}/tenders/collection

Employees API

The STS Gen2 Employees API is used to interact with an employee within a property (use the Organization Service to locate a property).

Paths

The {basePath} for resources on the Employees API is:

https://{host/path}/api/v1/

The Employees API provides access to the get an employee in a property. The context of the operation is defined by the {orgShortName} and {locRef} parameters.

Get an employee number: Method: get
Path: {basePath}/employees

Notifications API

The STS Gen2 Notifications Service is used to manage call back POST notifications messages that are sent to the integrator when they register to receive organization, configuration, check, and employee events.

Integrators must expose a service endpoint which accepts HTTP POST requests (webhook) to receive notifications from the STS Gen2 Notifications Service. The endpoint must implement TLS 1.2 and listen on port 443.The following top-level domains .com, .net, .org, .edu, .ca, .io, .site, .se, .sa are supported.

The following notifications are supported for STS Gen2 cloud integrations:
- Organizations Notification
- Configuration Notification
- Check Notification
- Employees Notification

The following notifications are supported for STS Gen2 on-premises integrations:
- Check Notification

Example notification message

{
        "messages": [
            {
                "id": "8253c2a5-5b3c-497d-a87f-f8bb2e250ba7",
                "creationDate": "2021-08-13T15:40:43.511Z",
                "messageType": {
                    "id": "CheckNotification"
                },
                "resource": {
                    "orgShortName": "tfoinc",
                    "locRef": "fdmnh144",
                    "rvcRef": "42",
                    "checkRef": "929aacee2c6d42c78ae877e824c28eed00000431"
                },
                "data": {
                    "status": "Submitted",
                    "timeStampUtc": "2021-08-13T15:40:44.501Z"
                }
            }
        ]
    }

Retry logic

At present retries are not supported. A notification will be sent only once.

Paths

The {basePath} for resources on the Notifications API is:

https://{host}/api/v1/

Delete a subscriber: Method: delete
Path: {basePath}/notifications/registration
Delete subscriptions: Method: delete
Path: {basePath}/notifications/subscriptions
Delete the subscription by a subscriptionId: Method: delete
Path: {basePath}/notifications/subscriptions/{subscriptionId}
Get message types: Method: get
Path: {basePath}/notifications/discovery
Get subscriptions: Method: get
Path: {basePath}/notifications/subscriptions
Get the subscription by a subscriptionId: Method: get
Path: {basePath}/notifications/subscriptions/{subscriptionId}
Post create a subscription: Method: post
Path: {basePath}/notifications/subscriptions
Post creates an integrator registration: Method: post
Path: {basePath}/notifications/registration
PUT creates or updates integrators registration: Method: put
Path: {basePath}/notifications/registration

Notifications API/Webhook

STS Gen2 includes resource level notifications that it facilitates via webhooks.

Integrators must expose a service endpoint which accepts HTTP POST requests (webhook) to receive notifications from the STS Gen2 Notifications Service. The endpoint must implement TLS 1.2 and listen on port 443. The following top-level domains .com, .net, .org, .edu, .ca, .io, .site, .se, .sa are supported. Timeout for HTTP requests to subscribers is 15 seconds with no retry

The following notifications are supported for STS Gen2 cloud integrations:
- Organizations Notification
- Configuration Notification
- Check Notification
- Employees Notification

The following notifications are supported for STS Gen2 on-premises integrations:
- Check Notification

Post Webhook: Method: post
Path: webhook

Organization API

The STS Gen2 Organization API is used to interact with organizations, locations, and revenue centers within the organization. It also provides a search capability to support the ability to find locations in an organization or revenue centers within a single location based on geographic location.

Paths

The {basePath} for resources on the Organization API is:

https://{host}/api/v1/

The Organization API provides access to organizations, locations, and revenue center resources.

An organization has one or more locations, and each location has one more revenue centers. The identifier for an organization in the API is orgShortName, the identifier for a location in the API is locRef, and the identifier for a revenue center in the API is rvcRef. The identifiers for locations are not unique across all organizations and similarly the identifiers for revenue centers are not unique across all locations within an organization. Since there is no uniqueness the path to access each of the resources must include its parent resource. For this reason, we end up with the following paths to GET each resource.

Get a list of all locations for an organization: Method: get
Path: {basePath}/organizations/{orgShortName}/locations
Get a list of all revenue centers for a location: Method: get
Path: {basePath}/organizations/{orgShortName}/locations/{locRef}/revenueCenters
Get a list of organizations: Method: get
Path: {basePath}/organizations
Get a location by the specified identifier for an organization: Method: get
Path: {basePath}/organizations/{orgShortName}/locations/{locRef}
Get a revenue center by the specified identifier for a location: Method: get
Path: {basePath}/organizations/{orgShortName}/locations/{locRef}/revenueCenters/{rvcRef}
Get an organization by the specified identifier: Method: get
Path: {basePath}/organizations/{orgShortName}
Get search for locations within an organization: Method: get
Path: {basePath}/search/locations
Get search for revenue centers within a location: Method: get
Path: {basePath}/search/revenueCenters