# Avalara AvaTax Python SDK
[](https://travis-ci.org/avadev/AvaTax-REST-V2-Python-SDK)
[](https://pypi.python.org/pypi/Avalara)
This GitHub repository is the Python SDK for Avalara's world-class tax service, AvaTax. It uses the AvaTax REST v2 API, which is a fully REST implementation and provides a single client for all AvaTax functionality. For more information about AvaTax REST v2, please visit [Avalara's Developer Network](http://developer.avalara.com/) or view the [online Swagger documentation](https://sandbox-rest.avatax.com/swagger/ui/index.html).
## Installation:
Install simply with pip.
```pip install Avalara```
**OR**
1. Clone this repository to your local machine.
```
$ git clone https://github.com/avadev/AvaTax-REST-V2-Python-SDK.git
```
2. Once downloaded, cd into the ```AvaTax-REST-V2-Python-SDK``` directory.
```
$ cd AvaTax-REST-V2-Python-SDK
```
3. Begin a new virtual environment with Python 3 and activate it.
```
AvaTax-REST-V2-Python-SDK $ python3 -m venv ENV
AvaTax-REST-V2-Python-SDK $ source ENV/bin/activate
```
4. [pip](https://pip.pypa.io/en/stable) install this package as well as the testing set of extras into your virtual enviroment.
```
(ENV) AvaTax-REST-V2-Python-SDK $ pip install -e .
(ENV) AvaTax-REST-V2-Python-SDK $ pip install -e .[testing]
```
## Usage:
### Create a transaction
**Import the AvataxClient from the avalara module**
First thing to do is to import the AvataxClient constructor module to your name space, or your python script.
```
from avalara import AvataxClient
```
**Now we are ready to construct a client object**
Create a new AvaTaxClient object:
```
client = AvataxClient('my test app',
'ver 0.0',
'my test machine',
'sandbox')
```
The client constructor takes four string parameters, in squence they are `app_name(required)`, `app_version(required)`, `machine_name(optional)`, and `environment(required)`.
The app_name, app_version, machine_name will be used to construct the [Client Header](https://developer.avalara.com/avatax/client-headers/) associated with each call made by this client. It will be returned within the response object to help you keep track of the API calls.
The `environment` variable can be either `"sandbox"` or `production`, they correspond to the two different environments for AvaTax service.
If you are a regular or free trial customer please use `"production"`. If you don't have an account, you can sign up for a free trail account on our [developer site](https://developer.avalara.com/avatax/signup/), this will be a production account as well.
If you wish to obtain a Sandbox account, please contact your [Customer Account Manager](https://help.avalara.com/Frequently_Asked_Questions/Avalara_AvaTax_FAQ/How_do_I_get_access_to_our_development%2F%2Fsandbox_account%3F)
**Ping the service**
Now we have a client object, we can ping the AvaTax REST V2 server to ensure connectivity.
```
response = client.ping()
# to view respnse text
print(response.text())
# to view json version of the response
print(response.json())
# to view the status code
print(response.status_code())
# to view the raw response
print(response.raw())
```
Note that the response from all REST calls made using this SDK will be [Request](http://docs.python-requests.org/en/master/user/quickstart/#response-content) object, which contains status code, response text, raw josn, and more information on the respnse.
**Add credentials to your client object**
Unlike `ping`, most methods in our REST V2 API requires you to be authenticated in order to associate those information provided by you with your account.
To find out if a method requires authentication, visit our [API Reference](https://developer.avalara.com/api-reference/avatax/rest/v2/methods/Transactions/) page.
To add credential on the current client object:
```
client = client.add_credentials('USERNAME/ACCOUNT_ID', 'PASSWORD/LICENSE_KEY')
```
The `add_credential` method will hash your username/password, or account_id/license_key pair and attach to every call made by your client object, meaning you only have to add credential once to each client you prepare to use.
To verify that you have added a valid credential, simply call the `ping` method again, this time in the response text you should see `"authenticated": true`.
**To create a transaction using your client object**
Now our client object is authenticated, we can call the create_transaction method which calls the [CreateTransaction API](https://developer.avalara.com/api-reference/avatax/rest/v2/methods/Transactions/CreateTransaction/)
```
transaction_response = client.create_transaction(tax_document)
print(transaction_response.text())
tax_document = {
'addresses': {'SingleLocation': {'city': 'Irvine',
'country': 'US',
'line1': '123 Main Street',
'postalCode': '92615',
'region': 'CA'}},
'commit': False,
'companyCode': 'DEFAULT',
'currencyCode': 'USD',
'customerCode': 'ABC',
'date': '2017-04-12',
'description': 'Yarn',
'lines': [{'amount': 100,
'description': 'Yarn',
'itemCode': 'Y0001',
'number': '1',
'quantity': 1,
'taxCode': 'PS081282'}],
'purchaseOrderNo': '2017-04-12-001',
'type': 'SalesInvoice'}
```
The create_transaction method takes in a model, in python it's a dictionary type object. Which you will fill out to include all of your transaction information. In this case, we are using the [TransactionModel](https://developer.avalara.com/api-reference/avatax/rest/v2/models/TransactionModel/)
For information on other models use by AvaTax APIs, visit our information page [here](https://developer.avalara.com/api-reference/avatax/rest/v2/models)
### Use other methods
Like our SDKs in other languages, the Python SDK includes all methods offered by the AvaTax REST V2 API. To find a mehtod corresponding to a specific API endpoint, simply visit this [code page](https://github.com/avadev/AvaTax-REST-V2-Python-SDK/blob/master/src/client_methods.py)
To learn more about integrating our REST API into your system, visit our [developer guide](https://developer.avalara.com/avatax/dev-guide/getting-started-with-avatax/) that contains information on using the powerful features offered by our API.
### Use transaction builder
We realize that having to format the TransactionModel can be complicated and time consuming, thus we created a tool called Transaction Builder to help you put together a transaction model, and create it!
First import the transaction builder constructor into your name space:
```from avalara.transaction_builder import TransactionBuilder```
Then, let's create a transaction builder object:
```
tb = TransactionBuilder(client, "DEFAULT", "SalesInvoice", "ABC")
```
The builder takes four required parameters, in sequence they are
- The client object
- Company name(created through AvaTax portal or by calling [CreateCompany API](https://developer.avalara.com/api-reference/avatax/rest/v2/methods/Companies/CreateCompanies/))
- The type of transaction, a [full list](https://developer.avalara.com/api-reference/avatax/rest/v2/models/enums/DocumentType/) of options.
- The customer code, an unique code identifying the customer that requested this transaction.
Now you are free to add transaction details to this object, by using methods like `with_address`, `with_line`, `with_parameter`.
For a fulll list of transaction builder methods available and the parameters they take in, visit the [code page](https://github.com/avadev/AvaTax-REST-V2-Python-SDK/blob/master/src/transaction_builder_methods.py)
In the end, you may call the `create` method on your builder object, which will call the CreateTransaction API with the transaction model you have build so far, and return back the response.
### Setup Test Credentials
If you wish to run the integration and unit testings, you must store a pair of credentials in the current enviroment.
Add the following to the ```activate``` file in your environment, and restart bash.
OR simply ```export``` them directly:
```
export SANDBOX_USERNAME='your_sandbox_username'
export SANDBOX_PASSWORD='your_sandbox_password'
# OR
SANDBOX_ACCOUNTID='your_sandbox_account_id'
SANDBOX_LICENSEKEY='your_sandbox_license_key'
```
Note: Only *Sandbox credentials* should be used for testing, as the test case will commit/adjust/void dummy transactions on the account to verify functionalities.
### Logging
Logging is implemented using standard Python logging framework.
1. All relevant methods from `AvataxClient` class are decorated with `ava_log` decorator.(This is achieved using another decorator at class level, `decorate_all_methods`)
2. `ava_log` decorator collects relevant request data, response data useful for instrumentation and logs error data in case of exception.
3. `AvataxClient` constructor is modified with optional parameter, `is_log_req_resp_allowed` (defaulted to False), to control if log entry should contain request and response objects.
4. SDK Consumer code can also set logger property of `AvataxClient` to use already configured logger instance. e.g.
```
from logging import config
# configure logging using file config or dictConfig
# or by setting basicConfig (this is default in case no logger is set)
config.fileConfig("logger_config.conf")
logger = logging.getLogger()
# set logger property
client.logger = logger
```
## Issue or suggestion
User feedbacks are highly valued here at Avalara, we want to ensure the best experience for every customer using our services. If you have any concern with this SDK or AvaTax in general, please post your queston/suggestion on our [Developer Relation Forum](https://community.avalara.com/avalara/category_sets/developers) as we will reply to you in a timely manner.
If you wish to contribute to this SDK, please fork the [repository](https://github.com/avadev/AvaTax-REST-V2-Python-SDK) and submit your pull request from the forked version. We are happy to review your contribution, and merge them if all checks has passed!
## Original Contributors
[Han Bao](https://www.linkedin.com/in/hbao2016)
[Philip Werner](https://www.linkedin.com/in/philip-werner-421aa66a)
[Robert Bronson](https://www.linkedin.com/in/robert-bronson)
[Adrienne Karnoski](https://www.linkedin.com/in/adrienne-karnoski)
Raw data
{
"_id": null,
"home_page": "https://github.com/avadev/AvaTax-REST-V2-Python-SDK",
"name": "Avalara",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Han Bao, Adrienne Karnoski, Robert Bronson, Philip Werner, Genevieve Conty",
"author_email": "han.bao@avalara.com",
"download_url": "https://files.pythonhosted.org/packages/4b/89/f0a5944456f610f39b96d1bf25bb3c5b21cb6afad7576e19fcca2b3b4a2a/avalara-24.10.0.tar.gz",
"platform": null,
"description": "# Avalara AvaTax Python SDK\n[](https://travis-ci.org/avadev/AvaTax-REST-V2-Python-SDK)\n[](https://pypi.python.org/pypi/Avalara)\n\nThis GitHub repository is the Python SDK for Avalara's world-class tax service, AvaTax. It uses the AvaTax REST v2 API, which is a fully REST implementation and provides a single client for all AvaTax functionality. For more information about AvaTax REST v2, please visit [Avalara's Developer Network](http://developer.avalara.com/) or view the [online Swagger documentation](https://sandbox-rest.avatax.com/swagger/ui/index.html).\n\n\n## Installation:\n\nInstall simply with pip.\n```pip install Avalara```\n\n**OR**\n\n1. Clone this repository to your local machine.\n```\n$ git clone https://github.com/avadev/AvaTax-REST-V2-Python-SDK.git\n```\n2. Once downloaded, cd into the ```AvaTax-REST-V2-Python-SDK``` directory.\n```\n$ cd AvaTax-REST-V2-Python-SDK\n```\n3. Begin a new virtual environment with Python 3 and activate it.\n```\nAvaTax-REST-V2-Python-SDK $ python3 -m venv ENV\nAvaTax-REST-V2-Python-SDK $ source ENV/bin/activate\n```\n4. [pip](https://pip.pypa.io/en/stable) install this package as well as the testing set of extras into your virtual enviroment.\n```\n(ENV) AvaTax-REST-V2-Python-SDK $ pip install -e .\n(ENV) AvaTax-REST-V2-Python-SDK $ pip install -e .[testing]\n```\n\n## Usage:\n\n### Create a transaction\n\n\n**Import the AvataxClient from the avalara module**\n\nFirst thing to do is to import the AvataxClient constructor module to your name space, or your python script.\n\n```\nfrom avalara import AvataxClient\n```\n\n**Now we are ready to construct a client object**\n\nCreate a new AvaTaxClient object:\n```\n client = AvataxClient('my test app',\n 'ver 0.0',\n 'my test machine',\n 'sandbox')\n```\nThe client constructor takes four string parameters, in squence they are `app_name(required)`, `app_version(required)`, `machine_name(optional)`, and `environment(required)`.\nThe app_name, app_version, machine_name will be used to construct the [Client Header](https://developer.avalara.com/avatax/client-headers/) associated with each call made by this client. It will be returned within the response object to help you keep track of the API calls.\nThe `environment` variable can be either `\"sandbox\"` or `production`, they correspond to the two different environments for AvaTax service.\nIf you are a regular or free trial customer please use `\"production\"`. If you don't have an account, you can sign up for a free trail account on our [developer site](https://developer.avalara.com/avatax/signup/), this will be a production account as well.\nIf you wish to obtain a Sandbox account, please contact your [Customer Account Manager](https://help.avalara.com/Frequently_Asked_Questions/Avalara_AvaTax_FAQ/How_do_I_get_access_to_our_development%2F%2Fsandbox_account%3F)\n\n\n**Ping the service**\n\nNow we have a client object, we can ping the AvaTax REST V2 server to ensure connectivity.\n```\n response = client.ping()\n\n # to view respnse text\n print(response.text())\n\n # to view json version of the response\n print(response.json())\n\n # to view the status code\n print(response.status_code())\n\n # to view the raw response\n print(response.raw())\n```\nNote that the response from all REST calls made using this SDK will be [Request](http://docs.python-requests.org/en/master/user/quickstart/#response-content) object, which contains status code, response text, raw josn, and more information on the respnse.\n\n\n**Add credentials to your client object**\n\nUnlike `ping`, most methods in our REST V2 API requires you to be authenticated in order to associate those information provided by you with your account.\nTo find out if a method requires authentication, visit our [API Reference](https://developer.avalara.com/api-reference/avatax/rest/v2/methods/Transactions/) page.\nTo add credential on the current client object:\n```\n client = client.add_credentials('USERNAME/ACCOUNT_ID', 'PASSWORD/LICENSE_KEY')\n```\nThe `add_credential` method will hash your username/password, or account_id/license_key pair and attach to every call made by your client object, meaning you only have to add credential once to each client you prepare to use.\n\nTo verify that you have added a valid credential, simply call the `ping` method again, this time in the response text you should see `\"authenticated\": true`.\n\n\n**To create a transaction using your client object**\n\nNow our client object is authenticated, we can call the create_transaction method which calls the [CreateTransaction API](https://developer.avalara.com/api-reference/avatax/rest/v2/methods/Transactions/CreateTransaction/)\n```\n transaction_response = client.create_transaction(tax_document)\n print(transaction_response.text())\n\n tax_document = {\n 'addresses': {'SingleLocation': {'city': 'Irvine',\n 'country': 'US',\n 'line1': '123 Main Street',\n 'postalCode': '92615',\n 'region': 'CA'}},\n 'commit': False,\n 'companyCode': 'DEFAULT',\n 'currencyCode': 'USD',\n 'customerCode': 'ABC',\n 'date': '2017-04-12',\n 'description': 'Yarn',\n 'lines': [{'amount': 100,\n 'description': 'Yarn',\n 'itemCode': 'Y0001',\n 'number': '1',\n 'quantity': 1,\n 'taxCode': 'PS081282'}],\n 'purchaseOrderNo': '2017-04-12-001',\n 'type': 'SalesInvoice'}\n\n``` \nThe create_transaction method takes in a model, in python it's a dictionary type object. Which you will fill out to include all of your transaction information. In this case, we are using the [TransactionModel](https://developer.avalara.com/api-reference/avatax/rest/v2/models/TransactionModel/)\nFor information on other models use by AvaTax APIs, visit our information page [here](https://developer.avalara.com/api-reference/avatax/rest/v2/models)\n\n\n### Use other methods\n\nLike our SDKs in other languages, the Python SDK includes all methods offered by the AvaTax REST V2 API. To find a mehtod corresponding to a specific API endpoint, simply visit this [code page](https://github.com/avadev/AvaTax-REST-V2-Python-SDK/blob/master/src/client_methods.py)\nTo learn more about integrating our REST API into your system, visit our [developer guide](https://developer.avalara.com/avatax/dev-guide/getting-started-with-avatax/) that contains information on using the powerful features offered by our API.\n\n\n### Use transaction builder\n\nWe realize that having to format the TransactionModel can be complicated and time consuming, thus we created a tool called Transaction Builder to help you put together a transaction model, and create it!\nFirst import the transaction builder constructor into your name space:\n```from avalara.transaction_builder import TransactionBuilder```\n\nThen, let's create a transaction builder object:\n```\n tb = TransactionBuilder(client, \"DEFAULT\", \"SalesInvoice\", \"ABC\")\n```\nThe builder takes four required parameters, in sequence they are\n- The client object\n- Company name(created through AvaTax portal or by calling [CreateCompany API](https://developer.avalara.com/api-reference/avatax/rest/v2/methods/Companies/CreateCompanies/))\n- The type of transaction, a [full list](https://developer.avalara.com/api-reference/avatax/rest/v2/models/enums/DocumentType/) of options. \n- The customer code, an unique code identifying the customer that requested this transaction.\n\nNow you are free to add transaction details to this object, by using methods like `with_address`, `with_line`, `with_parameter`.\nFor a fulll list of transaction builder methods available and the parameters they take in, visit the [code page](https://github.com/avadev/AvaTax-REST-V2-Python-SDK/blob/master/src/transaction_builder_methods.py)\nIn the end, you may call the `create` method on your builder object, which will call the CreateTransaction API with the transaction model you have build so far, and return back the response.\n\n\n### Setup Test Credentials\n\nIf you wish to run the integration and unit testings, you must store a pair of credentials in the current enviroment.\nAdd the following to the ```activate``` file in your environment, and restart bash.\nOR simply ```export``` them directly:\n\n```\nexport SANDBOX_USERNAME='your_sandbox_username'\nexport SANDBOX_PASSWORD='your_sandbox_password'\n\n# OR\nSANDBOX_ACCOUNTID='your_sandbox_account_id'\nSANDBOX_LICENSEKEY='your_sandbox_license_key'\n```\nNote: Only *Sandbox credentials* should be used for testing, as the test case will commit/adjust/void dummy transactions on the account to verify functionalities. \n\n### Logging\n\nLogging is implemented using standard Python logging framework.\n\n1. All relevant methods from `AvataxClient` class are decorated with `ava_log` decorator.(This is achieved using another decorator at class level, `decorate_all_methods`)\n2. `ava_log` decorator collects relevant request data, response data useful for instrumentation and logs error data in case of exception.\n3. `AvataxClient` constructor is modified with optional parameter, `is_log_req_resp_allowed` (defaulted to False), to control if log entry should contain request and response objects.\n4. SDK Consumer code can also set logger property of `AvataxClient` to use already configured logger instance. e.g. \n```\nfrom logging import config \n\n# configure logging using file config or dictConfig \n# or by setting basicConfig (this is default in case no logger is set)\nconfig.fileConfig(\"logger_config.conf\")\n\nlogger = logging.getLogger()\n\n# set logger property\nclient.logger = logger\n```\n \n\n## Issue or suggestion\n\nUser feedbacks are highly valued here at Avalara, we want to ensure the best experience for every customer using our services. If you have any concern with this SDK or AvaTax in general, please post your queston/suggestion on our [Developer Relation Forum](https://community.avalara.com/avalara/category_sets/developers) as we will reply to you in a timely manner.\nIf you wish to contribute to this SDK, please fork the [repository](https://github.com/avadev/AvaTax-REST-V2-Python-SDK) and submit your pull request from the forked version. We are happy to review your contribution, and merge them if all checks has passed!\n\n\n## Original Contributors\n\n[Han Bao](https://www.linkedin.com/in/hbao2016)\n\n[Philip Werner](https://www.linkedin.com/in/philip-werner-421aa66a)\n\n[Robert Bronson](https://www.linkedin.com/in/robert-bronson)\n\n[Adrienne Karnoski](https://www.linkedin.com/in/adrienne-karnoski)\n",
"bugtrack_url": null,
"license": null,
"summary": "Avalara Tax Python SDK.",
"version": "24.10.0",
"project_urls": {
"Homepage": "https://github.com/avadev/AvaTax-REST-V2-Python-SDK"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4b89f0a5944456f610f39b96d1bf25bb3c5b21cb6afad7576e19fcca2b3b4a2a",
"md5": "ce6951ec762d0b0dab53d4f0be7ed3b1",
"sha256": "7090faf923d5b3fee56e917182c96c96abeb6afe8805dc99257e849ffebdee1f"
},
"downloads": -1,
"filename": "avalara-24.10.0.tar.gz",
"has_sig": false,
"md5_digest": "ce6951ec762d0b0dab53d4f0be7ed3b1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 86779,
"upload_time": "2024-10-10T16:31:05",
"upload_time_iso_8601": "2024-10-10T16:31:05.540789Z",
"url": "https://files.pythonhosted.org/packages/4b/89/f0a5944456f610f39b96d1bf25bb3c5b21cb6afad7576e19fcca2b3b4a2a/avalara-24.10.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-10 16:31:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "avadev",
"github_project": "AvaTax-REST-V2-Python-SDK",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "avalara"
}
JSON
