Sparkfly Aloha Developer Integration Guide

Summary

This document describes the guidelines for integrating with the Sparkfly Aloha integration.

Intended Audience

This document is useful for developing additional Aloha integrations or software that will integrate with our Aloha agent. For instance, if you are an online ordering provider and wish to apply loyalty or coupon credentials to the check in Aloha, and have the Sparkfly extension treat it as a credential of our own.

Adding a Credential to the Check

The Sparkfly extension uses a menu item to track applied credentials. A credential can represent a coupon code, a loyalty member or any other piece of identifying information tied to an offer, a loyalty account or individual. In order to create credentials on the check, the integrator must create a menu item using the same ID that is configured in the Sparkfly extension for use with credentials. The menu item is configured as a $0 item in Aloha.

The credential is applied as a menu item, with the contents of the credential itself stored as a "Special Message" attached to the menu item.

For example, this is what an applied credential looks like in Aloha:

Example Applied Credential

In this example, a coupon with code EDMS has been applied to the transaction.

A correctly applied credential will have the following:

  1. The credential is applied using the Aloha menu item configured for use with Sparkfly.
  2. The credential menu item has a SpecialMessage applied with the credential identifier stored therein. (EDMS in the example above.)
  3. The credential menu item has an object attribute with key SFITEM and value being the credential identifier. (EDMS in the example above.)
  4. The credential menu item has an object attribute with key SFCHECK containing the Aloha Check ID the credential was originally applied to. This is used in split-check/merge-check scenarios on the terminal and is critical.
  5. The credential menu item has an object attribute with key SFHASINFO and value TRUE.

Adding a Sparkfly Discount to the Check

When integrating with Sparkfly's agent, you may be communicating with Sparkfly's POS API. The Sparkfly API may instruct you to apply an offer to the transaction, as a part of the normal add_offers[] response received from that endpoint. Included in this response is a field sparkfly_auth_code. This value, along with a few others, are critical for applying an offer to the transaction in Aloha in a way that the Sparkfly agent will recognize as its own. If not applied correctly, the discount may not be recognized during finalization of the transaction, and the coupon may not be correctly redeemed.

The below table describes how each field in the add_offers[] response relates to applying a comp in Aloha. For reference, see: POS API Documentation (Offer).

A correctly applied discount will have the following:

  1. The discount is applied as an Aloha Comp.
  2. The comp number used is based on the value specified in the add_offers[]::pos_offer_code field.
  3. The amount of the applied comp matches that of the add_offers[]::amount field.
  4. The comp is correctly linked to the required Aloha menu items as specified in the add_offers[]::qualifying_items array.
  5. The comp has an object attribute with key SFOFFER and value matching that of the add_offers[]::sparkfly_auth_code field.
  6. The comp has an object attribute with key SFITEM and value matching that of the add_offers[]::credential_identifier field.
  7. The comp has an object attribute with key SFOWNED and value TRUE.

Credential Locking and Transaction Synchronization

When multiple systems are manipulating the same transaction with Sparkfly credentials and offers applied, it is important that all systems use the same method for identifying a given unique transaction. For this reason, the following considerations are important:

  1. The pos_transaction_id used when communicating with the Sparkfly POS API should be the Aloha Check ID.
  2. The operator_id used when communicating with the Sparkfly POS API should be the Aloha Employee ID.
  3. The terminal_id used when communicating with the Sparkfly POS API should be the Aloha Terminal ID. This may be an interface terminal ID in some cases.
  4. The site_id used when communicating with the Sparkfly POS API should match the SiteId configured in the Sparkfly agent. This value is provided by Sparkfly and is usually a prefix combined with the Aloha Unit Number.
  5. The business_date used when communicating with the Sparkfly POS API should be the Aloha Business Date (sometimes referred to as DOB by Aloha), in the format that Aloha provides it.

Failure to provide correct values for these fields may result in coupons or loyalty identifiers becoming locked and unusable on the active transaction or others.

Handling Prior Offers on Sparkfly-Owned Checks

The Sparkfly POS API should update the Promos, Comps, or Payments of a Sparkfly-owned check that has not been tendered. Each time we communicate with the Sparkfly POS API, we check if it has been tendered and if it contains any Promos, Comps, or Payments.

Credential Attribute Retrieval

A Sparkfly entry can be identified by its SFITEM attribute and has the following relationship to a Sparkfly POS API request:

Sparkfly Request Property Entry Attribute
credentials[]::sparkfly_identifier SFITEM
credentials[]::amount SFAMOUNT
credentials[]::tip SFTIP
credentials[]::override_amount SFAMTORIDE
credentials[]::pos_reference_id entry.ID

Get entry attributes with the following function: IIberFuncs12.GetObjectAttribute(int ObjectClassId,int ObjectId, string Name).

The following c# snippet is an example usage of GetObjectAttributes where the target entry attribute is SFITEM and the payment's ObjectId is 312: 

    string sfEntry = IIberFuncs12.GetObjectAttribute(560, 312, "SFITEM");
    bool isSparkflyItem = sfEntry != null || sfEntry != string.Empty;

Comp Attribute Retrieval

A Sparkfly comp can be identified by its SFITEM attribute and has the following relationship to a Sparkfly POS API request:

Sparkfly Request Property Comp Attribute
offers[]::credential_identifier SFITEM
offers[]::sparkfly_auth_code SFOFFER
offers[]::amount comp.VALUE as decimal
offers[]::name comp.NAME
offers[]::pos_offer_code comp.COMPTYPE_ID as string
offers[]::pos_offer_code_type "comp"
offers[]::quantity 1.00

Get comp attributes with the following function: IIberFuncs12.GetObjectAttribute(int ObjectClassId,int ObjectId, string Name).

The following c# snippet is an example usage of GetObjectAttributes where the target comp attribute is SFITEM and the payment's ObjectId is 231: 

    string sfComp = IIberFuncs12.GetObjectAttribute(580, 231, "SFITEM");
    bool isSparkflyComp = sfComp != null || sfComp != string.Empty;

Promo Attribute Retrieval

A Sparkfly promo can be identified by its SFITEM attribute and has the following relationship to a Sparkfly POS API request:

Sparkfly Request Property Promo Attribute
offers[]::credential_identifier SFITEM
offers[]::sparkfly_auth_code SFOFFER
offers[]::amount promo.AMOUNT as decimal
offers[]::name promo.IDENT
offers[]::pos_offer_code promo.PROMOTION_ID as string
offers[]::pos_offer_code_type "promo"
offers[]::quantity 1.00

Get promo attributes with the following function: IIberFuncs12.GetObjectAttribute(int ObjectClassId,int ObjectId, string Name).

The following c# snippet is an example usage of GetObjectAttributes where the target promo attribute is SFITEM and the payment's ObjectId is 312: 

    string sfPromo = IIberFuncs12.GetObjectAttribute(620, 312, "SFITEM");
    bool isSparkflyPromo = sfPromo != null || sfPromo != string.Empty;

Payment Attribute Retrieval

A Sparkfly payment can be identified by its SFITEM attribute and has the following relationship to a Sparkfly POS API request:

Sparkfly Request Property Payment Attribute
offers[]::credential_identifier SFITEM
offers[]::sparkfly_auth_code SFOFFER
offers[]::amount payment.AMOUNT as decimal
offers[]::pos_offer_code payment.TENDER_ID as string
offers[]::pos_offer_code_type "tender"
offers[]::quantity 1.00
offers[]::tip payment.TIP
offers[]::entryId payment.ID as string
offers[]::identifier payment.IDENT
offers[]::auth payment.AUTH

Get payment attributes with the following function: IIberFuncs12.GetObjectAttribute(int ObjectClassId, int ObjectId, string Name).

The following c# snippet is an example usage of GetObjectAttributes where the target payment attribute is SFITEM and the payment's ObjectId is 123: 

    string sfPayment = IIberFuncs12.GetObjectAttribute(600, 123, "SFITEM");
    bool isSparkflyPayment = sfPayment != null || sfPayment != string.Empty;

Additional Documentation

The following links are useful: