Get Started with SaaS Pro - REST v2
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.
|
To prevent the possibility of accidentally committing test data to your Production account, Avalara requires that your Production account and your Sandbox account use different different API keys for credentials. To ensure that the API keys are different, you must use separate email addresses in Production and Sandbox when creating your API credentials. |
- 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 customer profile to REST v2. You may also be able to manage profiles and customizations directly from the customer profile.
|
Avalara recommends testing all customizations in your sandbox account before applying the customizations to your production account. Once you've added the customizations to your production account, make sure to test them before completing any bill runs. |
- 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:
Configuration setting | Options | Description |
---|---|---|
Return Non-Billable |
|
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). |
Submit a support case 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
Run a sample transaction in Swagger
|
If you're managing customizations in the customer portal, use the tax determination calculator to test your customizations before completing a bill run. |
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
- Select the Authorize button.
- Enter your Customer Portal username in email address.
- Enter your Customer Portal password in password.
- Select Authorize.
- Select Close to close the dialog box.
- Select and expand an endpoint. For example, expand Healthcheck > /api/v2/Healthcheck.
- Enter into edit mode for the endpoint by clicking Try it out.
- Update the request body if the selected endpoint is a POST request
- Learn about customizing transactions in the Communications Rest v2 Developer Guide
- 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
Refer to the AvaTax for Communications REST v2 Developer Guide for installation and configuration instructions.
Integrate with Communications REST v2
It's time to integrate your systems with Communications REST v2!
- You have access to two environments:
- Sandbox: Used for testing
- Production: Used for live transactions and bill runs
- The Communications REST v2 Developer Guide provides sample code, object reference information, endpoints, and other useful information
- SDK packages are available on GitHub. All SDK packages generated using the open source api tools from openapi-generator.csharp
- Sample code is available in the Avalara/Communications-Developer-Content repo on GitHub
- Follow Steps 1-3 in Download the REST Demo Application to clone the Avalara/Communications-Developer-Content repo from GitHub
- Navigate to ..\Communications-Developer-Content-master\afc_saaspro_tax\afc_rest_apis. Sample code is available for the following languages:
- C#
- Java
- Javascript
- JSON
- 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