|
| 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 | + |
| 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 | + |
| 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