-
Notifications
You must be signed in to change notification settings - Fork 1
/
index.Rmd
150 lines (123 loc) · 6.22 KB
/
index.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
---
output:
github_document:
html_preview: false
---
```{r, echo = FALSE, message = FALSE}
knitr::opts_chunk$set(
fig.align = 'center',
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-")
```
[![Build Status](https://travis-ci.org/StevenMMortimer/squareupr.svg?branch=master)](https://travis-ci.org/StevenMMortimer/squareupr)
[![AppVeyor Build Status](https://ci.appveyor.com/api/projects/status/github/StevenMMortimer/squareupr?branch=master&svg=true)](https://ci.appveyor.com/project/StevenMMortimer/squareupr)
[![CRAN_Status_Badge](http://www.r-pkg.org/badges/version/squareupr)](http://cran.r-project.org/package=squareupr)
[![Coverage Status](https://codecov.io/gh/StevenMMortimer/squareupr/branch/master/graph/badge.svg)](https://codecov.io/gh/StevenMMortimer/squareupr?branch=master)
<br>
<img src="man/figures/squareupr.png" width="120px" align="right" />
**squareupr** is an R package that connects to the Square APIs (Connect v1 & v2).
* OAuth 2.0 (Single sign-on) and Personal Access Token Authentication methods (`sq_auth()`)
* v2 Locations Endpoint (`sq_list_locations()`, `sq_get_location()`)
* v2 Transactions Endpoint (`sq_list_transactions()`, `sq_get_transaction()`)
* v2 Customers Endpoint - CRUD (Create, Retrieve, Update, Delete) methods for customers with:
* `sq_list_customers()`, `sq_search_customers()`, `sq_get_customer()`, `sq_create_customer()`, `sq_update_customer()`, `sq_delete_customer()`
* v1 Payments Endpoint (`sq_list_payments()`, `sq_get_payment()`)
* v1 Items Endpoint - CRUD (Create, Retrieve, Update, Delete) methods for items with:
* `sq_list_items()`, `sq_get_item()`, `sq_create_item()`, `sq_update_item()`, `sq_delete_item()`
* List v1 records (`sq_list_fees()`, `sq_list_categories()`, `sq_list_modifiers()`,
`sq_list_discounts()`)
## Table of Contents
* [Installation](#installation)
* [Usage](#usage)
* [Authenticate](#authenticate)
* [Transactions](#transactions)
* [Customers](#customers)
* [Credits](#credits)
* [More Information](#more-information)
## Installation
```{r, eval = FALSE}
# This package is not yet available on CRAN so you must install from GitHub
# install.packages("devtools")
devtools::install_github("StevenMMortimer/squareupr")
```
If you encounter a clear bug, please file a minimal reproducible example on
[GitHub](https://github.com/StevenMMortimer/squareupr/issues).
## Usage
### Authenticate
First, load the **squareupr** package and authenticate. There are two ways to authenticate:
1. Personal Access Token
2. OAuth 2.0
```{r auth, include = FALSE}
library(dplyr)
library(squareupr)
settings <- readRDS(here::here("tests", "testthat", "squareupr_test_settings.rds"))
suppressMessages(sq_auth(personal_access_token = settings$personal_access_token,
verbose = FALSE))
```
```{r, eval=FALSE}
library(dplyr)
library(squareupr)
# Using Personal Access Token (PAT)
sq_auth(personal_access_token = "sq-Th1s1sMyPers0nalAcessT0ken")
# Using OAuth 2.0 authentication
sq_auth()
```
NOTE: Before using OAuth 2.0 authentication it is necessary that you set up your
own Connected App in the Square dashboard. An App ID and App Secret will be
provided, then you will be able to plug into your script like so:
```{r other-params, eval=FALSE}
options(squareupr.app_id = "sq0-99-thisisatest99connected33app22id")
options(squareupr.app_secret = "sq0-Th1s1sMyAppS3cr3t")
sq_auth()
```
OAuth 2.0 credentials will be cached locally in a file entitled `".httr-oauth-squareupr"`
in the current working directory so that a new token is not needed each session.
### Transactions
Transactions are organized by location. With the v2 Locations endpoint you can pull
information regarding all locations first to obtain the location IDs. Then with the
`sq_list_transactions()` function you can provide the location and timeframe to search.
The function defaults to pulling transactions from the previous day using `Sys.Date() - 1`.
Once you obtain the transactions the `tenders` field lists all methods of payment
used to pay in the transaction.
```{r transactions-by-location}
# list all locations
our_locations <- sq_list_locations()
our_transactions <- sq_list_transactions(location = our_locations$id[2],
begin_time = as.Date('2019-07-09'),
end_time = as.Date('2019-07-10'))
our_transactions
```
### Customers
Once you pull data about transactions you can take the customer_id from the transaction
`tenders` field and match that up with customer details. In Square customers can
be placed into groups that allow for the analysis of transactions at a group-level.
```{r customers}
# list customers created in the last 30 days
created_start <- format(Sys.Date() - 30, '%Y-%m-%dT00:00:00-00:00')
created_end <- format(Sys.Date(), '%Y-%m-%dT00:00:00-00:00')
our_customers <- sq_search_customers(query = list(filter=
list(created_at=
list(start_at=created_start,
end_at=created_end))))
our_customers$given_name <- "{HIDDEN}"
our_customers$family_name <- "{HIDDEN}"
our_customers %>% select(id, created_at, updated_at,
given_name, family_name, preferences, groups)
# show the groups that each customer belongs to
# filter to the groups designated automatically by Square
sq_extract_cust_groups(our_customers) %>%
filter(grepl("^CQ689YH4KCJMY", groups.id))
```
## Credits
This application uses other open source software components. The authentication
components are mostly verbatim copies of the routines established in the **googlesheets**
package (https://github.com/jennybc/googlesheets). We acknowledge and are grateful
to these developers for their contributions to open source.
## More Information
This package makes requests best formatted to match what the APIs require as input.
This articulation is not perfect and continued progress will be made to add and improve
functionality. For details on formatting, attributes, and methods please refer to
[Square's documentation](https://docs.connect.squareup.com/api/connect/v2)
as they are explained better there.
[Top](#)