This is a Java client adapter for Avalara AvaTax web services. This version has support for the tax and
address services.
The adapter was built using Apache Axis WSDL2Java to build the stubs which
were then enhanced to support a custom Profile SOAP header element and a WS-Security
UsernameToken SOAP header element.
A set of JUnit tests are provided as examples. You may wish to refer to .NET/COM
documentation for more details.
YOU MUST CONFIGURE avatax4j.properties before running tests or samples!
Use avatax4j.properties.sample as an example and insert your account and license.
Contents |
/doc/api |
Javadocs - API Documentation |
/lib |
All required jars |
/samples |
Sample applications
- AddressValidateSample
- TaxTransactionSample
- TestConnectionSample
|
/src |
Full source code |
/test |
TaxSvcTest JUnit test class to be used as an initial example. |
avatax4j.properties.sample |
Sample properties file for JUnit tests to configure url, account, license
This must be renamed to avatax4.properties and configured prior to running
the unit tests. |
build.xml |
Ant build script. Run "ant" for usage instructions |
Dependencies
All dependent jar files are included for build and running.
-
JDK 5.0 or later
- avatax4j should be compatible with J2SDK
1.4.2 , but we no longer provide support for this version. You will
need to use the cacert file from JDK 5.0.
- Apache Ant
1.6.x or later
Getting Started
- Look at the examples in the samples directory.
- Look at the unit tests for more examples.
- Read the Javadocs
- Configure avatax4j.properties.Use avatax4j.properties.sample as an example
and insert your account and license.
- Run the samples and unit tests. See build instructions below.
Build Instructions
A complete Ant build.xml script is provided in the root directory. Here is
a list of the main target Ant tasks.
- compile - compiles everything
- javadoc - builds the javadocs
- test - runs the junit tests
- clean - cleans up all generated files and directories
- jar - creates the avatax4j.jar file
- usage - provides help on using the build tool (default)
Deployment
Many applications will only need to deploy the avatax4j.jar and avatax4j.properties
file. The avatax4j.properties file can be eliminated by setting the server url,
username and password credentials in your code. Examples of this can be found
in any of the samples (e.g. TestConnectionSample).
Some applications may require deployment of additional jar files from the lib
folder. These are all standard Sun, Apache, or other open-source components.
The version is indicated in most of the jar file names, but avatax4j should
be generally compatible with later versions. The axis-ant.jar, junit.jar, wsdl4j.jar
are only used for building and testing avatax4j.
Important Notice
This year we will be releasing a High-Availability version of our
adapters designed to work with geographically distributed AvaTax servers.
This new version will eliminate the DocId property for most operations, including GetTax,
PostTax, CommitTax, and CancelTax. To simplify the transition, we highly
recommend using DocCode instead of DocId for these operations. DocId is
server specific and will change depending on which AvaTax server processes the
request. We will maintain support for clients using earlier adapters,
but they will not be able to take advantage of the new high-availability architecture.
Change History
5.3.1 - March 2009
Several properties were added and some behavioral changes were made for the
existing ones.
GetTaxRequest class
- ExchangeRate has been added.
ExchangeRate indicates the currency exchange rate from the transaction currency
(indicated by CurrencyCode) to the company base currency. This only needs
to be set if the transaction currency is different than the company base currency.
It defaults to 1.0.
- ExchangeRateEffDate has been
added. ExchangeRateEffDate indicates the effective date of the exchange rate.
It should be set in conjunction with ExchangeRate. It will default to the
DocDate if not set.
- PaymentDate has been added.
PaymentDate indicates the date when payment was received for the document.
It is only applicable for cash-basis accounting and does not need to be set
otherwise. It defaults to 1/1/1900 which indicates no payment. The new TaxSvc.ApplyPayment
method may be used to apply a payment to an existing invoice.
Note: The ReportingDate for a cash-basis invoice will be set to 12/31/9999.
GetTaxResult class
- TotalTaxCalculated has been
added. TotalTaxCalculated indicates the total tax calculated by AvaTax. This
is usually the same as the TotalTax, except when a tax override amount is
specified. This is for informational purposes. The TotalTax will still be
used for reporting.
- TaxSummary has been added.
TaxSummary is now returned when GetTaxRequest.DetailLevel == DetailLevel.Line
in addition to DetailLevel.Summary. It is not returned for DetailLevel.Document
or DetailLevel.TaxDetail.
TaxDetail class
- RateType has been added.
RateType indicates the tax rate type. These currently include:
- F = Food (US)
- G = General (US)
- S = Standard (VAT)
- R = Reduced (VAT)
- Q = Super Reduced (VAT)
- A = Reduced Rate 1 (VAT)
- B = Reduced Rate 2 (VAT)
- Z = Zero Rate
- TaxCalculated has been added.
TaxCalculated indicates the tax calculated by AvaTax. It will usually be the
same as the Tax property, unless it has been overridden by a TaxOverride.TaxAmount.
- TaxGroup has been added.
TaxGroup indicates the group code when special grouping is enabled for particular
client applications. For other clients, it will be empty. Line class
- TaxIncluded has been added.
TaxIncluded indicates the tax amount has already been included in the line
Amount. The tax will be reversed out and returned in the TaxLine.Tax property.
The TaxLine.Taxable property will indicate the calculated tax base amount.
TaxLine class
- TaxCalculated has been added.
TaxCalculated indicates the tax calculated by AvaTax. This will normally be
the same as the Tax property unless it has been overridden by a TaxOverride.TaxAmount.
- TaxIncluded has been added.
TaxIncluded indicates the tax has already been included in the line item prices.
When true, the Tax property will indicate reversed out tax amount and the
Taxable property will indicate the calculated tax base amount.
TaxSvc class
- ApplyPayment has been added.
ApplyPayment allows a payment to be applied to an invoice for companies using
cash-basis accounting. It will update the PaymentDate and ReportingDate for
that invoice. Until a payment is applied to cash-basis invoices, the ReportingDate
will be set to 12/31/9999 to prevent the invoice from being reported.
5.2.0.0 - August 2008
- AddressSvc.Validate: Added a Taxability flag to the ValidateRequest
to retrieve whether the address is a taxable address. This is indicated by
the ValidateResult.Taxable flag.
- TaxSvc.ApplyPayment: This is a new method for applying
payments to invoices. This only applies to companies that have CashBasisEnabled
and in US states or countries where the AccountingMethod is set to CashBasis
in the Nexus for that state or country. CashBasis invoices are not considered
reportable until payment has been applied. ApplyPayment will set the Line.ReportingDates
to the PaymentDate. Otherwise, it will be left at 9999-12-31 and won't show
on reports.
- TaxSvc.GetTax:
- A new TaxOveride element was added to the GetTaxRequest and
the Line. This allows specifying an overriding tax date and tax amount,
or overriding the exempt status.
- CurrencyCode was added. The default is USD, if not specified.
- PaymentDate was added to GetTaxRequest which allows applying a payment
to a cash basis transaction when calculating tax.
- ExchangeRate and ExchangeRateEffDate were added to GetTaxRequest to
indicate the rate of currency exchange relative to the company's base
currency. This defaults to 1. It should only be set if the transaction
currency is different than the company's base currency. The rate should
be TransactionCurrency * ExchangeRate = BaseCurrency.
- TotalTaxCalculated has been added to the GetTaxResult and TaxCalculated
has been added to TaxLine and TaxDetail. This indicates the tax that AvaTax
calculated in cases where a TaxOverride was used.
- TaxSummary was added to the GetTaxResult which contains a summary of
taxes by jurisdiction. This is only returned when the GetTaxRequest.DetailLevel
is Summary or Line.
- A new global JurisType of Country is now returned for foreign countries,
including Canada. Previously State and County were used for Canada and
Province jurisdictions. To prevent breaking existing clients, this same
behavior is retained unless the Profile.Name is set to "5.1.0"
or later. In general, the version of the avatax4j release should be used
in the Profile.Name. For this release, it should be Profile.Name = "5.2.0.0".
5.0.0.271 - June 2007
1 GetTaxRequest class
Commit
has been added. Setting this value to true
will straight away commit the document at the time of GetTax call. This
saves you separate PostTax and CommitTax call.
IsTotalTaxOverriden
has been added. IsTotalTaxOverriden
indicates to apply tax to this line that has already been calculated by
the seller instead of calculating the tax.
TotalTaxOverride
has been added. TotalTaxOverride is the tax
amount that has already been calculated by the seller that should be
applied to the line instead of the AvaTax calculate tax.
2 GetTaxResult class
Locked
has been added. Flag identifying the
Document has been locked by Avalara's MRS process..
AdjustmentReason
has
been added. Valid reason for adjusting document.
AdjustmentDescription
has
been added. Description for adjusting document.
Version
has
been added. This shows current version of document.
TaxDate
has
been added. It is the date used to calculate tax on the Document.
3 Line class
IsTaxOverriden
has been added. IsTaxOverriden indicates to
apply tax that has already been calculated by the seller instead of
calculating the tax.
TaxOverride
has been added. TaxOverride is the tax
amount that has already been calculated by the seller that should be
applied instead of the AvaTax calculate tax.
4 Address class
TaxRegionId
has been added. TaxRegionId provides the
ability to override the tax region assignment for an address.
5 AdjustTax call
AdjustTax
call has been added. This takes
AdjustTaxRequest as an input and returns AdjustTaxResult which inherits
GetTaxResult.
6 AdjustTaxRequest class
AdjustTaxRequest
has been added. It is made of
AdjustmentReason, AdjustmentDescription and GetTaxRequest object. It is
an input for AdjustTax call.
7 AdjustTaxRequest class
AdjustTaxResult
has been added. It is similar to
GetTaxResult object. It is returned from AdjustTax call.
8 PostTaxRequest class
Commit
has been added. Setting this value to true
will straight away commit the document at the time of PostTax call. This
saves you separate CommitTax call.
9 TaxLine class
ExemptCertId
has been added. This specifies ExemptCertId
applied to a particulat Line during GetTax call.
10 CancelCode enum
- Created new enum type called
AdjustmentCancelled
which cancels the adjustment made.
11 DocStatus enum
- Created new enum type called
Adjusted
which says document has been adjusted using AdjustTax call.
4.15.0 - June 2007
- Eliminated backward compatibility issue with AvaTax server API changes.
Previously if new elements were added to the server api, it was necessary
to either get a new adapter or make sure that the avatax4j.jar preceeded axis.jar
on the classpath. This was problematic or not possible in some environments.
We are handling this issue now and no longer depend on the classpath order.
Updating the adapter for server API changes is not necessary except when you
wish to use the new features. Backward compatibility will be maintained. We
highly recommend updgrading to this new adapter. No code changes should be
necessary. The interface has not been changed.
4.14.0 - May 2007
- Eliminated need for wss4j-1.1.0.jar, opensaml-1.0.1.jar, and xmlsec-1.2.1.jar
files. The SOAP security token is now directly built in BaseSvcSoapStub.setSecurity().
The only required code change is in the wsdd configuration. See the next change
for details.
- Eliminated the need for the avatax4j.wsdd file. You should simply call the
default AddressSvcLocator() or TaxSvcLocator() constructor instead of passing
a config file (new FileProvider("avatax4j.wsdd")). If you wish to
still use a wsdd config file, then you need to remove the <handler type="java:org.apache.ws.axis.security.WSDoAllSender"
> handler. This is because we no longer use wss4j. See any of the samples
or junit tests for code examples. The handler has been removed from the included
avataxj4.wsdd, but it isn't necessary if you just use the default locator
constructors.
- Included the activation.jar and mailapi.jar files to eliminate the annoying,
but inocuous "Unable to find required classes (javax.activation.DataHandler
and javax.mail.internet.MimeMultipart). Attachment support is disabled"
warning message.
Known Issues
- If you get a warning message regarding Xalan as follows:
Unable to patch xalan function table.
java.lang.NoSuchFieldException: m_functions
at java.lang.Class.getField(Unknown Source)
at org.apache.xml.security.Init.registerHereFunction(Init.java:429)
at org.apache.xml.security.Init.init(Init.java:124)… (and so on)
You need to copy the xalan-2.6.0.jar to your JAVA_HOME/lib/endorsed/ directory.
You may need to create the endorsed directory.
- Ant test target cannot find the junit task:
The easiest way to fix this is to copy the junit jar from the avatax4j/lib
directory to your ant/lib directory.
- Warning message: "Unable to find required classes (javax.activation.DataHandler
and javax.mail.internet.MimeMultipart). Attachment support is disabled"
occurs.
You need to include the activation.jar and mailapi.jar (included in releases
4.14.0 and later). Or you can download these at: http://java.sun.com/products/javabeans/jaf/downloads/index.html
and http://java.sun.com/products/javamail/downloads/index.html