|
1 | | -# quickbooks-python |
| 1 | +# python-quickbooks |
2 | 2 | ------------------- |
3 | 3 |
|
4 | | -A really simple, brute-force, Python class for accessing the Quickbooks API. |
| 4 | +A simple Python class for accessing the Quickbooks API. |
| 5 | +Complete rework of [quickbooks-python](https://github.com/troolee/quickbooks-python). |
5 | 6 |
|
6 | | -It was made to work alongside Django, but should work without it. |
| 7 | +These instructions were written for a Django application. Make sure to change it to whatever framework/method you're using. |
7 | 8 |
|
8 | | -Made much simpler with some major contributions from @HaPsantran. See HaPsantran's branch [here](https://github.com/HaPsantran/quickbooks-python). I've cleaned the script up a bit for a semi-clean v0.1.0. |
| 9 | +## Connecting your application to Quickbooks Online |
9 | 10 |
|
10 | | -As HaPsantran says in their ReadMe: |
| 11 | +1. Create the Authorization URL your application: |
11 | 12 |
|
12 | | ->Generally when using this module (or any of the QBO v3 API wrappers out there), keep in mind that there are some glaring omissions in it's functionality that (AFAIK) no one is able to get around programmatically. For example, you can't access (or create, update, or delete, obvi) Deposits or Transfers. |
| 13 | + quickbooks = QuickBooks( |
| 14 | + sandbox=DEBUG, |
| 15 | + consumer_key=QUICKBOOKS_CLIENT_KEY, |
| 16 | + consumer_secret=QUICKBOOKS_CLIENT_SECRET, |
| 17 | + callback_url=CALLBACK_URL |
| 18 | + ) |
13 | 19 |
|
14 | | -### New in v0.2 |
| 20 | + authorize_url = quickbooks.get_authorize_url() |
15 | 21 |
|
16 | | -* Pip package |
| 22 | + Store the authorize_url, request_token, and request_token_secret for use in the Callback method. |
17 | 23 |
|
18 | | -### New in v0.1.1 |
| 24 | +2. Handle the callback: |
19 | 25 |
|
20 | | -* Well, versioning :) |
21 | | -* Removed a lot of extraneous method calls that have essentially been replaced with query_object(). |
22 | | -* Brought in some pushes from various lovely folks. |
| 26 | + quickbooks = QuickBooks( |
| 27 | + sandbox=DEBUG, |
| 28 | + consumer_key=QUICKBOOKS_CLIENT_KEY, |
| 29 | + consumer_secret=QUICKBOOKS_CLIENT_SECRET, |
| 30 | + callback_url=CALLBACK_URL |
| 31 | + ) |
| 32 | + |
| 33 | + quickbooks.authorize_url = authorize_url |
| 34 | + quickbooks.request_token = request_token |
| 35 | + quickbooks.request_token_secret = request_token_secret |
| 36 | + quickbooks.set_up_service() |
| 37 | + |
| 38 | + quickbooks.get_access_tokens(request.GET['oauth_verifier']) |
| 39 | + |
| 40 | + realm_id = request.GET['realmId'] |
| 41 | + access_token = quickbooks.access_token |
| 42 | + access_token_secret = quickbooks.access_token_secret |
23 | 43 |
|
24 | | -## Running the script |
| 44 | + Store realm_id, access_token, and access_token_secret need to be stored for later use. |
25 | 45 |
|
26 | | -Works like any Python module, but you'll need [rauth](http://rauth.readthedocs.org/en/latest/). |
27 | 46 |
|
28 | | -## Getting Access. |
| 47 | +## Accessing the API |
29 | 48 |
|
30 | | -These instructions were written for a Django application. Make sure to change it to whatever framework/method you're using. |
| 49 | +Setup the client connection using the stored `access_token` and the `access_token_secret` and `realm_id`: |
31 | 50 |
|
32 | | -1. Make sure you have set up your Quickbooks App. You can check whether you have on their [Manage](https://developer.intuit.com/Application/List) page. If you need help doing that, look at [their documentation](https://developer.intuit.com/docs/0025_quickbooksapi/0010_getting_started/0020_connect/0010_from_within_your_app#Implement_the_OAuth_Authorization_Workflow) <- Have fun, this page only works in Firefox. |
33 | 51 |
|
34 | | -2. When your callback method gets triggered, set up a QuickBooks object, and get a URL for authorization, and then access it: |
35 | | - ``` |
36 | | - qbObject = QuickBooks( |
37 | | - consumer_key = QB_OAUTH_CONSUMER_KEY, |
38 | | - consumer_secret = QB_OAUTH_CONSUMER_SECRET, |
39 | | - callback_url = QB_OAUTH_CALLBACK_URL, |
| 52 | + client = QuickBooks( |
| 53 | + sandbox=True, |
| 54 | + consumer_key=QUICKBOOKS_CLIENT_KEY, |
| 55 | + consumer_secret=QUICKBOOKS_CLIENT_SECRET, |
| 56 | + access_token=access_token, |
| 57 | + access_token_secret=access_token_secret, |
| 58 | + company_id=realm_id |
40 | 59 | ) |
41 | 60 |
|
42 | | - authorize_url = qbObject.get_authorize_url() # will create a service, and further set up the qbObject. |
43 | | -
|
44 | | - # access URL, however you want to |
45 | | - ``` |
46 | | -3. Access the existing `qbObject`, fetch the `oauth_verifier` and `realmId` from the URL, and set up a session (`request` is Django's [`HttpRequest`](https://docs.djangoproject.com/en/dev/ref/request-response/) object): |
47 | | - ``` |
48 | | - oauth_token = request.GET['oauth_token'] |
49 | | - oauth_verifier = request.GET['oauth_verifier'] |
50 | | - realm_id = request.GET['realmId'] |
51 | | -
|
52 | | - session = qbObject.get_access_tokens(oauth_verifier) |
53 | | -
|
54 | | - # say you want access to the employees. |
55 | | - url = "https://qbo.intuit.com/qbo1/" |
56 | | - url += "resource/employees/v2/%s" % (realm_id) |
57 | | -
|
58 | | - r = session.request( #This is just a Rauth request |
59 | | - "POST", |
60 | | - url, |
61 | | - header_auth = True, |
62 | | - realm = realm_id, |
63 | | - params={"format":"json"} |
64 | | - ) |
65 | | - ``` |
66 | | -4. Store the `access_token` and the `access_token_secret` and `realm_id`, use them whenever you want to set up a new QB Object: |
67 | | -
|
68 | | - ``` |
69 | | - qb = QuickBooks( |
70 | | - consumer_key = QB_OAUTH_CONSUMER_KEY, |
71 | | - consumer_secret = QB_OAUTH_CONSUMER_SECRET, |
72 | | - access_token = qbtoken.access_token, # the stored token |
73 | | - access_token_secret = qbtoken.access_token_secret, # the stored secret |
74 | | - company_id = qbtoken.realm_id #the stored realm_id |
75 | | - ) |
76 | | - ``` |
77 | | -## Accessing the API |
78 | 61 |
|
79 | | -Once you've gotten a hold of your QuickBooks access tokens, you can create a QB object: |
| 62 | +List of objects: |
80 | 63 |
|
81 | | - qb = QuickBooks(consumer_key = QB_OAUTH_CONSUMER_KEY, |
82 | | - consumer_secret = QB_OAUTH_CONSUMER_SECRET, |
83 | | - access_token = QB_ACCESS_TOKEN, |
84 | | - access_token_secret = QB_ACCESS_TOKEN_SECRET, |
85 | | - company_id = QB_REALM_ID |
86 | | - ) |
87 | 64 |
|
88 | | -__Note:__ This is a work-in-progress. It was made public to help other developers access the QuickBooks API, it's not a guarantee that it will ever be finished. |
| 65 | + customers = Customer.all() |
89 | 66 |
|
90 | | -## Available methods |
91 | 67 |
|
92 | | -you can access any object via the query_object method. |
| 68 | +Filtered list of objects: |
93 | 69 |
|
94 | | - qb.query_objects(business_object, params, query_tail) |
95 | 70 |
|
96 | | -The available business objects are: |
| 71 | + customer = Customer.filter(Active=True) |
97 | 72 |
|
98 | | - "Account","Attachable","Bill","BillPayment", |
99 | | - "Class","CompanyInfo","CreditMemo","Customer", |
100 | | - "Department","Employee","Estimate","Invoice", |
101 | | - "Item","JournalEntry","Payment","PaymentMethod", |
102 | | - "Preferences","Purchase","PurchaseOrder", |
103 | | - "SalesReceipt","TaxCode","TaxRate","Term", |
104 | | - "TimeActivity","Vendor","VendorCredit" |
105 | 73 |
|
106 | | -Example: |
| 74 | +Get single object by Id and update: |
107 | 75 |
|
108 | | - qb.query_objects("Bill") |
109 | | - > [{u'DocNumber': ... }] |
110 | 76 |
|
| 77 | + customer = Customer.get(1) |
| 78 | + customer.CompanyName = "New Test Company Name" |
| 79 | + customer.save() |
111 | 80 |
|
112 | 81 |
|
113 | | -## From HaPsantran's README |
114 | | ------------------- |
115 | 82 |
|
116 | | -Update: As I try using the pnl function in report.py, I notice that not all of the activity is making it in. I have to assume it basically doesn't work then. Rather than rebuild it, though, I'm probably going to use other tools outside the module to massage the ledger_lines I get out of massage.py (rather than build special reporting tools within the quickbooks package). |
| 83 | +Create new object: |
117 | 84 |
|
118 | | -Intuit has promised reporting features, but who knows... |
119 | 85 |
|
120 | | -http://stackoverflow.com/questions/19455750/quickbooks-online-api-financial-data |
| 86 | + customer = Customer() |
| 87 | + customer.CompanyName = "Test Company" |
| 88 | + customer.save() |
121 | 89 |
|
122 | | -### License |
123 | 90 |
|
124 | | -The MIT License (MIT) |
125 | 91 |
|
126 | | -Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: |
| 92 | +__Note:__ This is a work-in-progress. It was made public to help other developers access the QuickBooks API, it's not a guarantee that it will ever be finished. |
127 | 93 |
|
128 | | -The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. |
129 | 94 |
|
130 | | -THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
0 commit comments