Skip to content
Integrations
Adora
Aloha Data Warehouse
Aloha Insights
Bob's
Crisp
Gilbarco
Heartland
IQ Metrix
Par
REST API
Radiant
Qu
Revel
SFTP
Square
Sicom
Toast
Verifone
Savi Integration Guide
Share
Explore

Integration Guide

This document is an overview of how to push data to Savi Solutions.
You must provide the following for each location:
External Location ID - A unique string allowing us to identify which location the data came from.

Supported Delivery Methods

●
REST API
⁠
⁠
○ JSON
○ XML
●
SFTP
⁠
- controlled by Savi or the client
○ XML File for each resource type
○ JSON File for each resource type
○ CSV File for each resource type
●
AWS S3
⁠
⁠
○ XML File for each resource type
○ JSON File for each resource type
○ CSV File for each resource type
⁠
Resource Types
⁠
⁠

SFTP

URL: sftp.getsavi.com
Port: 22
Home directory: /getsavi-sftp/YOUR_PROVIDED_USERNAME
Username: Provided to you by your Savi Representative
Password: Provided to you by your Savi Representative
Or if you’d prefer to use a static IP and host checking: 34.217.171.102
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCsjRKlFjznjL1l6f2xNMmj4qEaHjdBO0mjgnQG4ySfLfSspFG1ULP6bABQ59Y/THeY7TXGKGfwE2knZROxiltVtxcDFViakjINWrKy+YQwSmJe0B1yYI0aEk0mH5fJAYzvNrVExxWd+nhpsiOXdn+KTgVGRj3sX0L/QZqbLDAYkAACvEvyYBx4waGxLH9BsD1YwjJCAu2HqdRc/2P1Vt4YZLSct4VUXzflfLdzsvqx2CP4pK6buwZo8IGALXQI1enTkaaWLEZLMpikgmHIMdKhtyd7dleGyVElo94R1TYiDdEe0FyjnSQtv1ZS18hHE05UC8A/Iit2UrSkXaMcgQhL

Troubleshooting

Upon pushing a file in the above format to Savi’s servers, or upon Savi polling your SFTP servers, Savi will ingest files for each resource type.
You may get the following error message when uploading files, especially if using WinSCP:
The server does not support the operation.
Error code: 8
Error message from server (US-ASCII): SETSTAT unsupported
⁠
blob.png
19.3 kB
⁠
⁠
This is due to the fact that our SFTP server does not allow you to set the timestamp value when
you upload an object, therefore you have to turn off preserving timestamps.
To resolve this in WinSCP go to Preferences > Transfer then edit the Default preset and untick preserve timestamp, once this is set it will allow you to upload files.
⁠
blob.png
73.3 kB
⁠
⁠

AWS S3

Upon pushing a file in the below format to Savi’s S3 bucket, Savi will ingest files for each resource type.

REST API

Each top level resource is created one at a time. This allows us to achieve a real time integration if the data can be provided in real time by the client.
Please set the following to be set as request headers:
Authorization: Bearer #{SESSION_TOKEN} - Not required on authentication.
Content-Type: application/json
⁠
Authentication/Creating a Session token
⁠
⁠
Sessions live for 8 hours, and are refreshed upon use.

Supported Input Formats

JSON

Headers

Using the following headers you can authenticate your request
Table 3
Column 1
Column 2
Header Key
Header Value
Authorization
Bearer $SESSION_TOKEN
Version
3/12/20
Content-Type
application/json
There are no rows in this table
⁠
The Authorization header isn’t necessary during authentication requests.

Routes

The following routes are supported off of the following base URL:
Base URL:
⁠
https://api.getsavi.com/client/
⁠
Table 4
Column 1
Column 2
Column 3
Resource
HTTP Verb
Path
Authentication
POST
/login
Transactions
POST
/transactions
Cash Drawers
POST
/cash_drawers
Cash Drawer Events
POST
/cash_drawer_events
Void Reasons
POST
/void_reasons
Refund Reasons
POST
/refund_reason
Promotions
POST
/promotions
Discounts
POST
/discounts
Employees
POST
/employees
Time Entries
POST
/time_entries
Break
POST
/breaks
Break Type
POST
/break_types
Dining Options
POST
/dining_options
Operational Metrics
POST
/operational_metrics
There are no rows in this table
⁠

Response

Upon the successful creation of your resource you will receive and HTTP 201 (Created), with an empty body.
Error Response
In the event of an error you may receive the following error codes:
Table 5
Code
Meaning
400
The server could not understand the request due to invalid syntax.
401
The client must authenticate itself to get the requested response. Please verify the API Token Header.
404
The server can not find the requested resource. Please verify the base url and path.
422
The request was well-formed but was unable to be followed due to semantic errors.
429
Too many requests have been sent in a given amount of time. Please retry sending the data after the time specified in the Retry-After header
500
The server has encountered a situation it doesn't know how to handle. Savi’s alerting system will alert our team, but please reach out to Savi.
502
This error response means that the server, while working as a gateway to get a response needed to handle the request, got an invalid response. Savi’s alerting system will alert our team, but please reach out to Savi.
503
The server is not ready to handle the request. Common causes are a server that is down for maintenance or that is overloaded. Savi’s alerting system will alert our team, but please reach out to Savi.
504
The server cannot be communicated with at this time. Savi’s alerting system will alert our team, but please reach out to Savi.
There are no rows in this table
⁠

Resource Types Version 1.3.0

Table 6
Column 1
Column 2
Column 3
Column 4
Authentication
Data type
Required?
Used to generate an API session token
api_key
String
Required
Provided by your Savi account representative
api_secret
String
Required
Provided by your Savi account representative. Similar to a password
There are no rows in this table
⁠
The following are the resource types accepted by Savi Solutions in order to integrate your data:
Table 7
Transaction
Data type
Required?
A sale or order
external_id
String
Uniquely identify incoming data. For example an invoice #
external_location_id
String
Identify which location the data came from
timestamp
ISO 8601 Timestamp
When the transaction closed
is_void
Boolean
Whether or not this transaction is void
is_refund
Boolean
Whether or not the transaction is a refund
subtotal
Float
Total before discount and taxes
total_discount
Float
Total discount value being applied
total_tax
Float
Total tax
total
Float
Total of the sale
register_id
String
The register the sale occurred at. We use this to map camera footage
line_items
Line Item (described below)
List of specific items or services purchased in a sale
dining_options
Array of Dining Option external_ids or dining_options
discounts
Array of Discount external_ids or discounts
List of specific discounts in a sale
employees
Array of Employee external_ids or promotions
promotions
Array of Promotion external_ids or promotions
List of specific promotions in a sale
refund_reasons
Array of Refund Reason external_ids or refund reasons
tenders
void_reasons
Array of Void Reason external_ids or void reasons
There are no rows in this table
⁠
Table 8
Line Item
Data type
Required?
Specific item or service purchased in a sale
external_id
Identifier of the unique line item from your system
display_id
external_line_item_id
SKU or other identifier of the product or service
title
Title of the item
description
Description of the item
unit_price
Price per unit of item
subtotal
Total before discount and taxes
total_discount
Total discount value being applied
total_tax
Total taxes
total
Total of the sale
There are no rows in this table
⁠
Table 9
Column 1
Column 2
Column 3
Column 4
Cash Drawer
Data type
Required?
The registers in use by a given location
external_id
String
Required
Used to identify the register in your system. Used to map to transactions
external_location_id
String
Required
Identify which location the data came from
name
String
Optional
Name of the register in your system
There are no rows in this table
⁠
Table 10
Void Reason
Data type
Required?
Entries in the system used to void transactions
external_id
Required
Used to identify the void reason in your system. Used to map to transactions
external_location_id
Required
Identify which location the data came from
name
Required
Name of the void reason in your system
is_active
Required
Whether or not the reason is still in use by system
There are no rows in this table
⁠
Table 11
Refund Reason
Data type
Required?
Entries in the system used to refund transactions
external_id
Optional
Used to identify the refund reason in your system. Used to map to transactions
external_location_id
Optional
Identify which location the data came from
name
Required
Name of the refund reason in your system
is_active
Optional, defaults to true
Whether or not the reason is still in use by your system
There are no rows in this table
⁠
Table 12
Promotion
Data type
Required?
Types of promotions listed in system
external_id
Required
Used to identify the promotion in your system. Used to map to transactions
external_location_id
Required
Identify which location the data came from
name
Required
Name of the promotion in your system
is_active
Required
Whether or not the promotion is still in use by your system
There are no rows in this table
⁠
Table 13
Discount
Data type
Required?
Types of discounts listed in system
external_id
Required
Used to identify the discount in your system. Used to map to transactions
external_location_id
Required
Identify which location the data came from
name
Required
Name of the discount in your system
is_active
Required
Whether or not the discount is still in use by your system
There are no rows in this table
⁠
Table 14
Employee
Data type
Required?
Employees listed in system
external_id
Used to identify the employee in your system. Used to map to transactions
external_location_id
Used to identify which location the data came from
name
Name of the employee in your system
email
Email of the employee in your system
is_active
Whether or not the employee is still in use by your system
There are no rows in this table
⁠
Table 15
Time Entry
Data type
Required?
Shift and pay rates by employee
external_id
Used to identify the shift/time entry in your system.
external_location_id
Identify which location the data came from
employee_id
References the employee during the transaction
start_date_time
Timestamp representing the start of the shift
end_date_time
Timestamp representing the end of the shift
wage
Hourly rate
There are no rows in this table
⁠
Table 16
Break
Data type
Required?
Breaks by time entry
external_id
Required
Used to identify the break entry in your system.
break_type_id
Required
References the break_type for a break
external_location_id
Required
Identify which location the data came from
employee_id
Required
References the employee for a time_entry
time_entry_id
Required
References the time_entry for a break
start_date_time
Required
Timestamp representing the start of the shift
end_date_time
Required
Timestamp representing the end of the shift
There are no rows in this table
⁠
Table 17
Column 1
Column 2
Column 3
Column 4
Break Type
Data type
Required?
Breaks types for a break
external_id
String
Required
Used to identify the break type in your system.
external_location_id
String
Required
Identify which location the data came from
name
String
Required
The break type name
There are no rows in this table
⁠
Table 18
Cash Drawer Events
Data type
Required?
Cash Drawer Events 2
external_id
Used to identify the cash drawer event in your system.
external_location_id
Identify which location the data came from
type
The cash drawer event type
variance
start_date_time
Timestamp representing the start of the event
end_date_time
Timestamp representing the end of the event
employee_id
References the employee for a cash_drawer_event
There are no rows in this table
⁠
Table 19
Column 1
Column 2
Column 3
Column 4
Operational Metrics
Data type
Required?
Operational metrics defined by your organization
external_location_id
String
Required
Identify which location the data came from
name
String
Required
The name of the metric
value
Float
Required
The value of the metric for the period
start_date_time
ISO 8601 Timestamp
Required
The start period for the metric, localized to the location time. Can be used to specify arbitrary levels of granularity.
end_date_time
ISO 8601 Timestamp
Required
The end period for the metric, localized to the location time. Can be used to specify arbitrary levels of granularity.
There are no rows in this table
⁠
Table 20
Column 1
Column 2
Column 3
Column 4
Dining Options
Data type
Required?
Types of dining options listed in system
external_id
String
Required
Used to identify the dining option in your system. Used to map to transactions
external_location_id
String
Required
Identify which location the data came from
name
String
Required
Name of the dining option in your system
type
String
Required
`delivery`, `dine_in`, `take_out`, or `other`
There are no rows in this table
⁠

Want to print your doc?
This is not the way.
Try clicking the ··· in the right corner or using a keyboard shortcut (
CtrlP
) instead.