Import API: Data Specification

Payload

• Version (integer) required
  The version number for the data specification. Current version is 10000 but is subject to change in the future.
• Head (complex) required
  See “Head” for more information.
• Data (complex) required
  See “Data” for more information.

Head

• SystemName (string - max length 50 characters) required
  External system name which identifies the point of sale. Specified by the customer/restaurant the first time a connection is attempted. SystemName is then included in every connection and is used to identify the customer/restaurant. We recommend that SystemName follows the structure of Company Name + Location/Display Name, for example “Caspeco – Uppsala Bar”. Special symbols should be avoided and trim spaces at the end. Also do note that this field should not be changed after the first export to Caspeco, either by you or by the customer. If the name is changed, the identification and authentication will not match the previous registered values and the export will be denied by the API. If a SystemName must be changed you should also create a new Guid for said SystemName.
• ComputerName (string - max length 50 characters) required
  The name of the computer connecting to the API. Must be unique for each machine that communicates with the API. The name is specified by the customer/restaurant every time a new machine is used to connect to the API. ComputerName is then included in every connection and is used to identify the customer/restaurant.
• Guid (string) required
  A “Globally Unique Identifier” that should be unique for every machine that connects to the API. Generated by the customer/restaurant at the first connection with a new machine. Guid is then included in every connection and is used to identify the machine for the customer/restaurant.
• Vendor (string) required
  A unique name for identifying customer/provider. Vendor is specified by Caspeco and is delivered to the customer before the first connection is made to the API.
• Hash (string) required
  A sha256-hash which is created from parts of the data that is sent in combination with the Guid together with a secret key. The hash is used to authenticate the connection and is validated every time a connection is attempted. The data used at the hash is a concatenating of the value in the field ‘RecepitId’ for each ticket in the data. The complete string that is hashed hence is a concatenation of the secret key + guid + ReceiptID(1) + … + ReceiptID(n). For more detailed information regarding the creation of the hash we recommend to read the code examples that are included in the SDK.
  The secret key used in the hash is specified by Caspeco and delivered to the customer/restaurant before the first connection is made to the API.
• SecretRev (integer) required
  The revision for the secret key used in the hash. The first time a new customer connects to the API the audit will be 1. Should the secret key need to be changed in the future the revision will be increased with one level for each new key that is created.

Please note!

Note that the provided Vendor, SystemName & ComputerName always have to match the first values sent with the same Guid. If any of these three values needs to be changed you also need to provide a new Guid which will be considered a new import at our end.

Data

• Tickets (list) required
  A list containing tickets/receipts. See “Ticket” for more information.

Ticket

• Orders (list) required (not required if Tip is included)
  A list containing all orders for a specific receipt. See “Order” for more information.
• SiteId (string) required
  The ID for the place/location where the receipt was created and paid for.
• SiteName (string)
  The name of the location (i.e. the restaurant) where the receipt was created and paid for.
• ZoneId (string) required
  ID for the zone where the receipt was created and paid for.
• ZoneName (string)
  Name of the zone (i.e. “Bar” or “Dining room”) where the receipt was created and paid for.
• ReceiptId (string) required
  ID for the specific receipt.
• TableId (string) required
  ID for the table where the receipt was created and paid for.
• NumGuests (integer) required
  Total number of guests for the specific receipt (i.e. number of customers at the table).
• TableOpen (datetime)
  Date and time when the table/receipt was opened (i.e. 2016-02-23T11:30:00)
• TableClose (datetime) required if Tip is used
  Date and time when the table/receipt was closed/paid for (i.e. 2016-02-23T11:30:00)
• OperatorId (string) required
  ID for the specific waiter/waitress receiving the payment.
• OperatorName (string) required
  The name of the specific waiter/waitress receiving the payment.
• Tip (decimal) if used, TableClose is required
  Total tip/gratuity received for the specific receipt.
• TakeAway (boolean)
  The receipt was a take away order.
• Payment (string)
  The type of payment used. Supported values are Cash, Card, Swish, Coupon, Giftcard, Loyalty, Rikskuponger, Invoice, Hoteltab, Other.
• Currency (string)
  The ISO-4217 currency code of the currency used (e.g SEK, EUR).
• ProjectId (string)
  Id of any project this ticket is associated with.
• ProjectName (string)
  Name of any project this ticket is associated with.
• IsCorrection
  For the moment this will only apply to the Tip field. Only valid if the ticket does not contain orders and is used to correct Tip. In order to correct order rows the IsCorrection field on the Line object should be used instead.
• Tags (complex)
  An object/dictionary of arbitrary key-value pairs that could be used to enhance some features in the Caspeco analytics service. Keys duplicated in Orders or Lines will override values from Tickets. Should only be used in specific agreed upon use cases.

Order

• DateTime (datetime)
  Date and time of the order (i.e. 2016-02-23T11:30:00).
• OperatorId (string) required
  ID of the waiter/waitress receiving the order.
• OperatorName (string)
  Name of the waiter/waitress receiving the order.
• TableId (string) required
  ID of the table where the order was made. If you cannot provide a TableId please provide the value “-1”.
• Lines (list) required
  A list including articles ordered. See “Line” for more information.
• Tags (complex)
  An object/dictionary of arbitrary key-value pairs that could be used to enhance some features in the Caspeco analytics service. Keys duplicated in Lines will override values from Orders. Should only be used in specific agreed upon use cases.

Line

• MixedLines (list)
  A list of articles a mixed line consists of. See “MixedLines” for more information.
• Addons (list)
  A list of extra orders (extra cheese, extra fries). See “Addons” for more information.
• IsCorrection (boolean)
  Indicates if the specific row is a correction of an error. If the value is set to “true” the row will be treated as a correction and all values will be inverted.
• ArticleId (string - max length 50 characters) required
  ID of the specific article.
• ArticleName (string - max length 300 characters)
  Name of the specific article.
• ArticleGroup (complex) required
  This is the article group “branch”. The API supports import of several branches with arbitrary depth/levels but with a minimum of one group. In the current implementation however, only the first three levels of the branch is saved. Three levels is the recommended number of levels as it is the number of levels used by Caspeco. See “ArticleGroup” for more information.
• EanCode (string)
  The EAN-code for each article.
• Quantity (decimal) required
  Number of units ordered of the specific article.
• PriceExVat (decimal) required
  Price excluding VAT per unit of the specific article.
• Vat (decimal) required
  VAT rate in percent for the specific article/row
• Cost (decimal)
  The cost for each unit of the specific article (raw material cost).
• DiscountExVat (decimal)
  Discount that has been subracted from each unit of the specific article.
• TotalPriceIncVatAndDisc (decimal) required
  The total price the customer has paid for the total number of units of the specific article/row. Including VAT and any discount.
• Tags (complex)
  An object/dictionary of arbitrary key-value pairs that could be used to enhance some features in the Caspeco analytics service. Should only be used in specific agreed upon use cases.

ArticleGroup

• Parent (complex)
  Next group in the hierarchy. See “ArticleGroup” for more information.
• Id (string - max length: 50 characters) required
  ID of the articlegroup.
• Name (string) required
  Name of the articlegroup.

MixedLines/Addons

MixedLines and Addons has the same values as a “Line” except they cannot be corrections (corrections are made for complete rows, with MixedLines and Addons included) or have their own MixedLines or Addons.

• MixedLines (list)
  A list of articles/rows containing all articles the underlying row consists of. This is only used for mixed articles, e.g. predefined menus as “Hamburger with French fries and soda”. In this case the underlying row would be the menu whereas “MixedLines” would include the three separate articles, the hamburger, the French fries and the soda.
• Addons (list)
  A list of extra orders, e.g. extra sauce, extra fries.