Skip to content

Commit 974f5ae

Browse files
committed
smallbizhack sydney guide
1 parent 377fb5d commit 974f5ae

File tree

9 files changed

+214
-8
lines changed

9 files changed

+214
-8
lines changed

index.html

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -52,8 +52,7 @@ <h3>Build your app on the QuickBooks platform!</h3>
5252
<nav class="menu-navigation">
5353
<ul class="menu-navigation-list">
5454
<li class="menu-navigation-list-item feature"><a href="#oauth2title">OAuth2.0</a></li>
55-
<li class="menu-navigation-list-item feature"><a href="#helloworldtitle">HelloWorld</a></li>
56-
<li class="menu-navigation-list-item feature"><a href="#oauthtitle">OAuth1.0a</a></li>
55+
<li class="menu-navigation-list-item feature"><a href="#helloworldtitle">HelloWorld</a></li>
5756
<li class="menu-navigation-list-item feature"><a href="#webhookstitle">Webhooks</a></li>
5857
<li class="menu-navigation-list-item feature"><a href="#crudtitle">CRUD Samples</a></li>
5958
<li class="menu-navigation-list-item feature"><a href="#paymentstitle">Payments</a></li>
@@ -66,6 +65,7 @@ <h3>Build your app on the QuickBooks platform!</h3>
6665
<li class="menu-navigation-list-item language"><a href="#phptitle">PHP</a></li>
6766
<li class="menu-navigation-list-item language"><a href="#pythontitle">Python</a></li>
6867
<li class="menu-navigation-list-item language"><a href="#otherstitle">Other Samples</a></li>
68+
<li class="menu-navigation-list-item feature"><a href="#oauthtitle">OAuth1.0a</a></li>
6969
</ul>
7070
</nav>
7171
<div class="leadspace-buttons">
@@ -100,11 +100,6 @@ <h3>Build your app on the QuickBooks platform!</h3>
100100
<!-- hello work -->
101101
<div id="helloworldtitle" class="section-title feature"><span class="title">HELLO WORLD</span></div>
102102
<div id="helloworld" class="columns section in feature" style="height: auto;"></div>
103-
<div class="separator gap"></div>
104-
105-
<!-- oauth -->
106-
<div id="oauthtitle" class="section-title feature"><span class="title">OAUTH1.0a</span></div>
107-
<div id="oauth" class="columns section in feature" style="height: auto;"></div>
108103

109104
<!-- DotNet -->
110105
<div id="dotnettitle" class="section-title language"><span class="title">DOTNET</span></div>
@@ -142,7 +137,6 @@ <h3>Build your app on the QuickBooks platform!</h3>
142137
<!-- PHP -->
143138
<div id="phptitle" class="section-title language"><span class="title">PHP</span></div>
144139
<div id="php" class="columns section in language" style="height: auto;"></div>
145-
<div class="separator gap"></div>
146140

147141
<!-- invoice -->
148142
<div id="invoicetitle" class="section-title feature"><span class="title">INVOICING</span></div>
@@ -162,6 +156,12 @@ <h3>Build your app on the QuickBooks platform!</h3>
162156
<div id="otherstitle" class="section-title language"><span class="title">OTHER</span></div>
163157
<div id="others" class="columns section in language" style="height: auto;"></div>
164158

159+
<!-- oauth -->
160+
<div id="oauthtitle" class="section-title feature"><span class="title">OAUTH1.0a</span></div>
161+
<div id="oauth" class="columns section in feature" style="height: auto;"></div>
162+
<div class="separator gap"></div>
163+
164+
165165

166166
</div> <!-- /container -->
167167

269 KB
Loading
107 KB
Loading
171 KB
Loading
Loading
Loading
Loading

smallbizhack-sydney/Postman collection/QuickBooks APIs.json

Lines changed: 1 addition & 0 deletions
Large diffs are not rendered by default.

smallbizhack-sydney/README.md

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
# SmallBizHack Sydney
2+
Welcome to SmallBizHack Sydney 2018! Here you will find useful information and sample code to complete your app.
3+
4+
* [The challenge](#the-challenge)
5+
* [APIs at your disposal](#apis-at-your-disposal)
6+
* [Implementing the QuickBooks API](#implementing-the-quickbooks-api)
7+
8+
## THE CHALLENGE
9+
Create a solution that saves a small business time or money
10+
11+
12+
## APIs at your disposal
13+
This hack is all about creating new innovations that help small businesses. We encourage you to use the APIs below _(HINT HINT: there are special prizes for the teams who best utilise these APIs)_, but you're free to use any other APIs and frameworks to bring your app to life.
14+
15+
* For **QuickBooks API**, you're in the right place. Read on below!
16+
* For **Telstra API**, head [here](https://dev.telstra.com/apis)
17+
* For **Google cloud API**, head [here](https://dialogflow.com/docs/getting-started/basics)
18+
* For **PayPal API**, head [here](https://developer.paypal.com/)
19+
20+
# Implementing the QuickBooks API
21+
22+
## Intro to the QuickBooks APIs
23+
Every small business needs to track their income, expense and profits, pay employees or lodge tax. They use an accounting application like QuickBooks to automate these painful tasks. QuickBooks is designed as an open ecosystem for small businesses, so YOU can build an app which hooks onto QuickBooks, to solve the myriad of other painpoints associated with running a business.
24+
25+
Once your app is granted access to their QuickBooks account by a business owner, you can consume a rich set of financial data via the QuickBooks acccounting APIs. You can use this data and the available APIs to to help them run their business more efficiently.
26+
27+
Common tasks performed by the QuickBooks API include:
28+
* Manage customers and vendors databases
29+
* Manage sales-side transactions (invoices, sales receipt) and purchase-side (bills, expenses) transactions.
30+
* Retrieve reports: profit and loss, outstanding invoices...
31+
* Manage product inventory
32+
33+
Check the [API reference](https://developer.intuit.com/docs/api/accounting) for the complete list of APIs. Do also check our app marketplace [apps.com](https://www.apps.com) for example of use cases and apps which use our APIs.
34+
35+
36+
## Setting up OAuth access
37+
38+
There are available libraries to generate OAuth 2.0 tokens. For simplicty sake here we'll show you how to manually generate the token using our OAuth playground, and get to your first succesful API call in minutes.
39+
40+
1. Sign up for an account on [​developer.intuit.com](​https://developer.intuit.com)
41+
42+
2. Click on **my apps** and choose the **Just start coding**> option. Select access to the **accounting** API and click **create app**
43+
44+
![alt-text](https://github.com/jplemoussu/smallbizhack-sydney/blob/master/Images/create-app.png "create your QuickBooks app")
45+
46+
3. You should now be greeted by your QuickBooks app dashboard. Head over the **Keys** section and note down your `client Id` and `client secret`
47+
48+
4. Create a [Sandbox company](https://developer.intuit.com/v2/ui#/sandbox) to run APIs against. Select `Australia` in the drop down and click `add` to create a AU small business account with dummy data. Take a moment to login your sandbox account and play around the QuickBooks app to understand how it works.
49+
50+
5. Time to grant your app access to the Sandbox company and generate your access token using the [OAuth playground](https://developer.intuit.com/v2/ui#/playground). Select `Accounting` and `OpenID` for the scopes.
51+
52+
6. Click on `Get authorization code`. You will be presented with an authorisation dialogue. Select your sandbox company and click `connect`.
53+
54+
7. Back in the OAuth playground, click on `Get Token` to exhange the authorization code for your access and refresh tokens. If all goes well you should be presented with a response like below:
55+
56+
```json
57+
{
58+
"refresh_token": "xxxxxxxx",
59+
"access_token": "xxxxxxxx",
60+
"expires_in": 3600,
61+
"x_refresh_token_expires_in": 8726400,
62+
"id_token": "xxxxxxxx",
63+
"token_type": "bearer"
64+
}
65+
```
66+
67+
Here's a run down of the OAuth response from QuickBooks:
68+
69+
* `access_token`: token you will add in the authorization header of every API call to access data from your sandbox company. It is short lived: 1 hour. Can be refreshed before each call by calling the refresh token endpoint.
70+
* `refresh_token`: Required to acquire a short lived `access token`. These last 100 days, but whenever our token endpoint returns a new one for the same company, start using it instead for subsequent calls. If the token is lost, generate a new refresh token by re-authorising your app.
71+
* `id_token`: JSON web token containing information about the user and company which authorised your app. The token is base 64 encoded. You can head to https://jwt.io/ to decode it and check what is in there.
72+
73+
## Your first API call with POSTMAN
74+
75+
1. To construct your first API call and test access to your sandbox account, we will be using the API client POSTMAN.
76+
77+
NOTE: You can also skip this part and directly use the available QuickBooks SDKs or your prefered API client library if you prefer. The setup steps will depend on what you use. You will need to plug in your `client Id`, `client secret` and set the sandbox endpoint `https://sandbox-quickbooks.api.intuit.com`. The POSTMAN collection we've created is just a great way to navigate the API and test the capabilities of the API before you get your hands into the code.
78+
79+
TIP 1: If you use POSTMAN, there is a handy code generator which will generate code snippets in most available laguages.
80+
81+
![alt-text](https://github.com/intuitdeveloper.github.io/smallbizhack-sydney/blob/master/Images/postman-code-snippets.jpg "Postman code snippets")
82+
83+
84+
TIP 2: Change the user agent to something unique so your requests can be tracked by Intuit Engineers to help debug your code if necessary
85+
86+
87+
88+
2. For this example, I'll be using the `customer` entity and generate a data query using the QuickBooks `query` endpoint. I want to get a list of all the customers that owe my small business client money! The query API uses SQL like queries (_note: we will soon be launching a GraphQL version of the API which will improve performance and code efficiency_)
89+
90+
ex: ```SELECT * FROM customer WHERE Balance > '0.0'```
91+
92+
More details on the query API here
93+
94+
The constructed request looks like
95+
96+
```
97+
POST https://sandbox-quickbooks.api.intuit.com/v3/company/193514693720239/query
98+
99+
Request Headers:
100+
accept:"application/json"
101+
content-type:"application/text"
102+
authorization:"Bearer <YourAccessToken>"
103+
104+
Request Body:
105+
"SELECT * FROM customer WHERE Balance > '0.0'"
106+
```
107+
108+
Which gives the following JSON response
109+
110+
```json
111+
{
112+
"QueryResponse": {
113+
"Customer": [
114+
{
115+
"Taxable": false,
116+
"BillAddr": {
117+
"Id": "2",
118+
"Line1": "25 Stone Drive",
119+
"City": "Sydney",
120+
"CountrySubDivisionCode": "NSW",
121+
"PostalCode": "2001",
122+
"Lat": "-33.737492",
123+
"Long": "151.195909"
124+
},
125+
"Job": false,
126+
"BillWithParent": false,
127+
"Balance": 1650,
128+
"BalanceWithJobs": 1650,
129+
"CurrencyRef": {
130+
"value": "AUD",
131+
"name": "Australian Dollar"
132+
},
133+
"PreferredDeliveryMethod": "None",
134+
"domain": "QBO",
135+
"sparse": false,
136+
"Id": "1",
137+
"SyncToken": "0",
138+
"MetaData": {
139+
"CreateTime": "2020-07-25T22:02:17-07:00",
140+
"LastUpdatedTime": "2020-08-23T14:36:42-07:00"
141+
},
142+
"GivenName": "Adwin",
143+
"FamilyName": "Ko",
144+
"FullyQualifiedName": "Adwin Ko",
145+
"CompanyName": "Ko International Ltd",
146+
"DisplayName": "Adwin Ko",
147+
"PrintOnCheckName": "Adwin Ko",
148+
"Active": true
149+
},
150+
{
151+
"Taxable": false,
152+
"BillAddr": {
153+
"Id": "4",
154+
"Line1": "9 Temple St",
155+
"City": "Melbourne,",
156+
"CountrySubDivisionCode": "VIC",
157+
"PostalCode": "3001",
158+
"Lat": "-37.869967",
159+
"Long": "145.093636"
160+
},
161+
"Job": false,
162+
"BillWithParent": false,
163+
"Balance": 7150,
164+
"BalanceWithJobs": 7150,
165+
"CurrencyRef": {
166+
"value": "AUD",
167+
"name": "Australian Dollar"
168+
},
169+
"PreferredDeliveryMethod": "None",
170+
"domain": "QBO",
171+
"sparse": false,
172+
"Id": "3",
173+
"SyncToken": "0",
174+
"MetaData": {
175+
"CreateTime": "2020-07-25T22:02:21-07:00",
176+
"LastUpdatedTime": "2020-08-23T22:03:14-07:00"
177+
},
178+
"GivenName": "Benjamin",
179+
"FamilyName": "Yeung",
180+
"FullyQualifiedName": "Benjamin Yeung",
181+
"CompanyName": "Yeung's Architects",
182+
"DisplayName": "Benjamin Yeung",
183+
"PrintOnCheckName": "Benjamin Yeung",
184+
"Active": true
185+
}
186+
],
187+
"startPosition": 1,
188+
"maxResults": 5
189+
},
190+
"time": "2018-05-15T09:37:45.387-07:00"
191+
}
192+
```
193+
194+
If you made it here, well done. Take a small break before exploring the other endpoints!
195+
196+
197+
198+
199+
200+
201+
202+
203+
204+
205+

0 commit comments

Comments
 (0)