| Next Topic |
|---|
| Online Ordering Module 1a: Create User |
Overview of Online Ordering API Certification Tutorials
The online ordering API certification tutorials are a set of conceptual modules that help you learn how to integrate your online ordering system with the Punchh server using the Punchh online ordering APIs. The online ordering integration with Punchh allows you to offer the Punchh loyalty program to your guests from your online ordering system.
Information Architecture
The online ordering tutorials have a consistent look and feel to help you quickly navigate and find the information in the modules. Each module contains the following main sections:
- Goal
- Prerequisites
- Use Cases and Context
- Workflow
- Best Practices
- Related Topics
Many modules also include example code (e.g., cURL and Python) that shows how to construct the related API calls.
Tutorial Modules - Sequence and Goals
The tutorial modules are based on the general flow of online ordering integration. In general, the sequence of the online ordering modules depicts the order in which you need to call the online ordering API endpoints to implement the Punchh loyalty program, as shown in the following table.
| Tutorial Module | Goal |
| Module 1a: Create User | Create a new loyalty guest user in the online ordering system of a business via the website or mobile app. |
| Module 1b: Complete Sign-up for a POS "Dummy" Account | Create and sign in a user via the online ordering system whose account was initially created at the POS. |
| Module 2: Sign-in | Sign in a user via the online ordering system of a business via the website or mobile app. |
| Module 3a: Show Offers in Guest Account | Look up information about offers available to a user so that the offers can be displayed in the online ordering system of a business via the website or mobile app. |
| Module 3b: Show Account Balance | Look up the account balance information of a user so that it can be displayed in the online ordering system of a business via the website or mobile app. |
| Module 4: Update User Profile | Update the values of fields in the profile of a loyalty guest user in the online ordering system of a business via the website or mobile app. |
| Module 5: Redemptions | Implement Redemptions 2.0 (new redemptions framework) or Redemptions 1.0 (legacy redemptions framework) based on the requirements of the business. |
| Module 6: Check-in | Create a check-in for a loyalty guest and send check-in details to Punchh to grant the customer a visit or loyalty points. |
| Module 7: Updating/Voiding Transactions | Update the details of a transaction or cancel the transaction if “Pending Check-ins” is enabled. |
Example Code - Prerequisites and Setup
Many tutorial modules also include example code (e.g., cURL, Python, and Ruby) that shows how to construct the related API calls. Before you can run the Python and Ruby example code in each tutorial module, you need to create the generate_signature file (.py or .rb) and the http_client file (.py or .rb) as described in the following sections. Before running the Python and Ruby example code in a tutorial module, save each code sample to a file (.py or .rb) in the same directory where the generate_signature file (.py or .rb) and the http_client file (.py or .rb) are located.
Generating x-pch-digest Header
An x-pch-digest header is required for all Punchh online ordering API calls. You can use the following example code to create the generate_signature file (.py or .rb), which is required in order to run the Python and Ruby example code in each tutorial module.
import hmac
import hashlib
import json
def generate_signature(body, path):
# Secret for the environment that you are pointing the request to
secret = 'SECRET_GOES_HERE'
payload = ''.join((path,(body)))
signature = hmac.new(bytes(secret, 'UTF-8'), bytes(payload, 'UTF-8'), hashlib.sha1).hexdigest()
return signature
class GenerateSignature
# Secret for the environment that you are pointing the request to
SECRET = "SECRET_GOES_HERE"
def self.generate_signature(body, path)
payload = path + body
signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha1'), SECRET, payload)
return signature
end
end
Creating http_client Used To Make HTTP Requests
You can use the following example code to create the http_client file (.py or .rb) file, which is required in order to run the Python and Ruby example code in each tutorial module.
# You will need to install the Requests package before this code will work.
# To do so, see the installation instructions here: https://requests.readthedocs.io/en/latest/user/install/#install
import requests
from generate_signature import generate_signature
def send_request(path, http_verb, body):
base_uri = "https://server-name-goes-here.punchh.com"
url = base_uri + path
signature = generate_signature(body, path)
headers = {
'Accept': 'application/json',
'Content-Type': 'application/json',
'x-pch-digest': signature,
# A guest's access_token can be retrieved from the API response to a Sign Up or Sign In API call.
# To get an access_token for use with our Online Ordering APIs, this will need to be configured on the Punchh Platform.
# Please reach out to your Punchh representative in order to get that set up.
# NOTE: Remove this Authorization header for requests where it is not listed as a required header (e.g., sign-up, login, etc.).
'Authorization': 'Bearer ACCESS_TOKEN_GOES_HERE'
# Example only - change the User-Agent header as outlined here in the documentation:
# https://developers.punchh.com/docs/dev-portal-online-ordering/5a9dba2cf6dc0-user-agent
'User-Agent': 'Punchh/OnlineOrder/1.0/Web/BrowserVersion/OS_Type'
}
response = requests.request(method=http_verb, url=url, headers=headers, data=body)
if response.content:
return response.text
else:
return response.status_code
class HttpClient
require "json"
require "net/http"
require "openssl"
require "uri"
# Sandbox base URI:
BASE_URI = "https://server-name-goes-here.punchh.com"
def self.send_request(path, http_verb, body)
begin
concatenated_url = BASE_URI + path
url = URI("#{concatenated_url}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = ""
case http_verb
when "GET"
request = Net::HTTP::Get.new(url)
when "POST"
request = Net::HTTP::Post.new(url)
when "PATCH"
request = Net::HTTP::Patch.new(url)
when "PUT"
request = Net::HTTP::Put.new(url)
when "DELETE"
request = Net::HTTP::Delete.new(url)
else
return
end
request["Accept"] = "application/json"
request["Content-Type"] = "application/json"
# A guest's access_token can be retrieved from the API response to a Sign Up or Sign In API call.
# To get an access_token for use with our Online Ordering APIs, this will need to be configured on the Punchh Platform.
# Please reach out to your Punchh representative in order to get that set up.
# NOTE: Remove this Authorization header for requests where it is not listed as a required header (e.g., sign-up, login, etc.).
request["Authorization"] = "Bearer ACCESS_TOKEN_GOES_HERE"
# Example only - change the User-Agent header as outlined here in the documentation:
# https://developers.punchh.com/docs/dev-portal-online-ordering/5a9dba2cf6dc0-user-agent
request["User-Agent"] = "Punchh/OnlineOrder/1.0/Web/BrowserVersion/OS_Type"
unless body.nil?
request.body = body
end
puts "Request Body: #{request.body}"
signature = GenerateSignature::generate_signature(request.body, url.path)
request['x-pch-digest'] = signature
response = http.request(request)
end
if valid_json?(response.body)
puts "HTTP Status Code: #{response.code.to_i}|Response: #{JSON.parse(response.body)}"
else
puts "HTTP Status Code: #{response.code.to_i}"
end
end
def self.valid_json?(json)
JSON.parse(json)
return true
rescue JSON::ParserError => e
return false
end
end
Certification Process
Punchh provides APIs that third-party developers can consume to integrate their online ordering systems with the Punchh server to offer Punchh loyalty services to their customers. Punchh also supports certification of third-party developed integrations for online ordering systems. For more information, see Certification - Online Ordering.