A simple module for the Django Framework to use with the Square API.

Rather than having to upload products into two seperate systems (DJango Admin/Square POS), users can use this program to update web applications as changes are made to square (IE: products, categories, etc.) via the Square dashboard or POS.

Square Business/Merchant Account needed before using.

written using Python 3

• Added Customer module - CRUD module with sq_customer class for customers (create customer, check email, update customer, update email, delete account.)

• Added catalog module - catalog module collects and creates json data of categories and items from API. It also has a product module that allows items associated with a category_id to be returned for data manipulation.
• Added Sq_Connect class with a connect_api function for connection to Square api.

If you have not created a square business account, please do so before continuing. The Connect class assumes that you have already set-up a square merchant account and have access to the following square credentials:

• Access Token
• Application ID
• Location(s) ID

Before you are able to use the Square API or Sq_Connect class, you have to first create your secrets.json file to use with the secrets.py file. Rather than hard coding your Access Token, Application ID, and Location ID headers everytime you send a request, these two files ensure that you only have to set-up once as well as protect your sensitive data.

There are two global variables : BASE_DIR and SECURITY KEY

BASE_DIR = os.path.dirname(os.path.abspath(__file__))
SECURITY_KEY = os.path.join(BASE_DIR, 'secrets.json')

They are currently set to the connect module file path. You can change the file path to your desired path.

Just remember to assign the SECURITY_KEY file path to where you will be storing your secrets.json file.

To use the get_secrets() refer below

This is the json file is where you will store all sensitive data used for the Square API headers, module file storage directories, etc.

Sample Structure

{
	"ACCESS_TOKEN": "[square access token goes here.]",
	"APPLICATION_ID": "[square application id goes here.]",
	"LOCATION_ID": "[square store location goes here.]",
}

NOTE: You may have more than one location you are using. Just create a new key such as "LOCATION_ID_2" : "value"

This method is used to parse the secrets.json file, retrieve desired setting, and returns value from json file.

To access your settings from the secrets.json file, you can import and use the get_secrets() method found on secrets.py.

This example uses the json sample from above.

from sqware.connect.secrets import get_secrets

ACCESS_TOKEN = get_secrets('ACCESS_TOKEN') 
LOCATION_ID = get_secrets('LOCATION_ID')

This will return the value of that setting to be used in headers, or other methods that may require sensitive data. You will see a working example with the Sq_Connect class.

The Sq_Connect class utilizes the GET, POST, PUT, DELETE http methods through the Requests library. These methods conincide with the CRUD endpoints of the Square API: Endpoint Names and Return Values.

Within each class method you will find this variable:

sq_connection = requests.get('https://connect.squareup.com' + request_path, headers = self.request_headers, timeout=3)

This is where all the work is done using the Requests library. The Square Connect http path is already hard coded and should not be changed unless there has been a change to Square's API

The request_path variable is provided by you when you create the Sq_Connect instance. See below.

The headers variable is set to the self.request_headers variable in the init constructor.

For the GET method, a TIMEOUT parameter is provided. You can change this to your desired limit. This will end the connection at the set time if there are any connection hangups. See Requests documentation for more information.

Depending on which http method you use you may see the json=data parameter included. This for those methods that have to send json data to the Square API endpoint. See examples below.

In order to send data to the Square API, it requires a header that passes the square access token: Get Started with Square.

Without this header, all requests will return errors.

To prevent this, the Sq_Connect class is set up to recieve all data from your secrets.json file via the get_secrets method.

You can find the variables within the init constructor method.

def __init__(self):
		'''constructor for class'''
		self.access_token = get_secrets('ACCESS_TOKEN')
		self.request_headers = {
			'Authorization': 'Bearer ' + self.access_token,
			'Accept':        'application/json',
			'Content-Type':  'application/json'
			}

NOTE: You may decided to change your json setting keys on the secrets.json file. If you do that make sure you update those setting keys within the init method or an error will return.

def __init__(self):
		'''constructor for class'''
		self.access_token = get_secrets('CHANGED_KEY')

In order to call the necessary http methods, an instance of Sq_Connect is needed.

from sqware.connect import Sq_Connect

self.connect = Sq_Connect()

Once an instance is set, we can call the neccessary http method needed.

The GET/DELETE http methods only require the path to the requested Square API endpoint(s).

Example

from sqware.connect import Sq_Connect

self.connect = Sq_Connect()

self.connect.get(endpoint_path)

or

self.connect.get('/v2/locations')

In this example, this will return a json response object of all locations associated with the Square account. See the Square API Documentation for more information about their endpoints.

For this application the DELETE method has only been used to delete customer information. This is explained further in the Sq_Customer class. More info: Square API Documentation

NOTE:

There may be times that you may have to hardcode a path into your GET method to retrieve certain data/data types from the Square API.

For example if you wanted to search for a complete list of items in the store catalog, your path may look like this:

self.connect.get('/v2/catalog/list?types=item')

See Square Documentation for more information

Similar in execution to the GET/DELETE methods, the POST/PUT methods require an additional parameter.

from sqware.connect import Sq_Connect

self.connect = Sq_Connect()

self.connect.post(endpoint_path, data)

The data parameter accepts the json/dict data needed to be passed to the Square API.

from sqware.connect import Sq_Connect

self.json_data = {
	"given_name": "John",
	"family_name": "Doe"
	}

self.connect = Sq_Connect()

self.connect.post('/v2/customers', self.data)

NOTE:

When using the POST/PUT methods, certain Square API endpoints may require the User's ID. You can either hard code (not recommended) or assign/pass the ID to a variable and string it with the endpoint path.

There is a method in the Sq_Customer class that helps retrieve customer data without hardcoding it.

self.customer_id = 'test_id_1'


self.connect.put('/v2/customers/' + self.customer_id, self.json_data)

This project is licensed under the MIT License.