Follow the steps below to get started with Avalara for Communications REST v2.
Activate your Communications Customer Portal account
A Customer Portal account is created in both the Sandbox and Production environments.
- Request a Customer Portal account from your Customer Account Manager if you don't already have one.
- After your Customer Portal account is created, the AvaTax for Communications (AFC) Portal Account Activation email is sent.
- Click the Click here to activate link within the Activation email to activate your account
- Follow the on-screen instructions to set your password. Be mindful of the environment you are working in because your Sandbox and Production account passwords can be different.
Create a Client Profile
The AFC Tax Engine is customizable to fit your needs by creating and applying a Client Profile to REST v2.
- Determine if you need one or more of the following customization files:
- Bundle file to accurately calculate taxes on bundles transaction
- Exclusion file to indicate countries or states where no tax should be applied
- Override file to modify tax rates or tax logic
- Exemption file to indicate the jurisdictions, tax types, and tax levels where taxes should be exempted
- Nexus file to identify the jurisdictions that require you to calculate Sales and Use taxes
- Identify AFC Tax Engine Configuration Options:
||Non-billable items are compliance-only taxes or fees that are used for filing and are not passed on to the user. This option allows you to specify whether non-billable items should be included in the tax table returned by the tax calculation API functions in AFC or not.|
|Safe Harbor TAM Override(s)||
||Safe Harbor TAM Override configuration settings allow traffic study values to be applied for a given session or account.
The results of percentages from a traffic study can be applied by administering traffic study TAM overrides. The TAM values for Cellular, VoIP and Paging are adjusted to reflect the percentages in the traffic study. While all all three types of TAM overrides can be set, it is possible to set only one or two of the options (Cellular, VoIP, or Paging).
Contact CommunicationSupport@avalara.com to request a new client profile for your account. A client_profile_id is provided once the customizations are applied to your account.
- Request the configuration option updates required and any overrides, exclusions, exemptions, or bundles needed. Attach any existing customization files to the email.
- Include instructions as to whether the client profile should be applied to Sandbox for testing purposes, Production, or both environments
- Include the client_profile_id to be updated if changes are needed to an existing client profile
- The account could take up to 24 hours to refresh with the new changes
Determine your api_key and run a sample transaction in Swagger
You now have the necessary items to run a test transaction in Swagger:
- Customer Portal username
- Customer Portal password
- One or more client_profile_ids (if applicable)
- Navigate to the Communications Customer Portal.
- Log in to the Customer Portal with your Customer Portal username and password.
- Go to Apps > Developer Content to open the Swagger page.
- Verify the following:
- Version is v2.
- client_id is set to your expected Client ID. Select the appropriate client name from the Client drop down in the upper right corner of the page if the client_id is not set properly.
- Enter the client_profile_id in profile_id.
- Enter 0 or leave blank if not using a client profile
- Enter your Customer Portal username in email address
- Enter your Customer Portal password in password
- Click Generate api_key
- The api_key is now populated in api_key. Copy and save for later use.
- The api_key is the generated by encoding Customer Portal "username:Password" to Base64. For example, if your username is email@example.com and your password is secretpassword!, your api_key is Zmlyc3QubGFzdEBhdmFsYXJhLmNvbTpzZWNyZXRwYXNzd29yZCE=.
- Select and expand an endpoint. For example, expand Healthcheck > /api/v2/Healthcheck.
- Enter into edit mode for the endpoint by clicking Try it out.
- Click Execute when ready to submit the request
- The response is returned in the Responses section. Important items to notice:
Download the REST Demo Application
Download the C# REST Demo Application to see how to integrate with and call the REST API.
- Navigate to the Avalara/Communications-Developer-Content repo on GitHub
- Clone the master branch of the Avalara/Communications-Developer-Content repository locally
- Extract the ZIP file contents and open the destination location
- Navigate to ..\Communications-Developer-Content-master\afc_saaspro_tax\afc_rest_apis\AfcRestDemoApp in the extracted folder
- Launch RestDemoApplication.exe
- Run sample transactions
- In Username, enter your Customer Portal username
- In Password, enter your Customer Portal password
- In Client ID, enter your client id
- In Profile ID, enter:
- client_profile_id to use an existing client profile (if applicable)
- 0 to use the default profile
- Modify the Request or simply use the transaction provided. Sample requests are found in the Communications Rest v2 Developer Guide.
- Click Process to run the transaction
- Run performance tests
- Navigate to the Performance tab
- Set Max Threads and Max Run Time
- Click Start to start a performance test
- The results of the test are displayed within the Performance tab
- Review the C# Avalara for Communications REST Demo Application source code to prepare for integration
- Open the Communications-Developer-Content-master folder
- Navigate to ..\Communications-Developer-Content-master\afc_saaspro_tax\afc_rest_apis\AfcRestDemoSource
- Open RestDemoApplication.sln in Microsoft Visual Studio
Integrate with Communications REST v2
It's time to integrate your systems with Communications REST v2!
- You have access to two environments:
- The Communications REST v2 Developer Guide provides sample code, object reference information, endpoints, and other useful information
- Sample code is available in the Avalara/Communications-Developer-Content repo on GitHub
- Before you complete your integration, see Best Practices.
I'm in - now what?
You've made it through establishing client profiles, determining your api_key, running test transactions, and integrating Communications REST v2 with your systems. Let's dive more into the details:
- Jurisdiction Determination
- Utilize the Communications REST v2 lookups
- Customize your transactions
- Using Commit and Uncommit
- Specifying Exemptions
- Passing an Adjustment
- Creating Reports