Skip to main content
Avalara Help Center

AvaTax for Communications SaaS Pro (SOAP and REST) migration guide

Introduction

The AFC SaaS Pro Web Service was designed to fully leverage the industry leading accuracy, product support and extensive tax types available through the licensed version of the AFC engine. Clients migrating from the licensed AFC product to the AFC SaaS Pro Web Service will find there is very little difference in the type of transactional data required as input and no difference in the resulting tax data calculated.

The migration document is intended to assist in the transition by providing a breakdown of Architecture, API equivalence, Configuration and Reporting.

This document is not intended to show features of the AFC SaaS Pro Web Service that are not available to licensed users, and should be used in combination with AFC SaaS Pro documentation which contains overviews of the latest features available for the web service.

AFC SaaS Pro REST Interface

Our premium AFC SaaS Pro service is part of the Amazon Web Service (AWS) using Elastic Compute Cloud (EC2).

Amazon leads the industry in uptime, security and flexibility with AWS. The EC2 interface provides flexibility and web scalability, allowing our AFC SaaS Pro REST service to quickly scale capacity to meet the needs of our users. Real time monitoring, alarms and trending metrics enable us to keep our services running smoothly.

The following link provides a listing of available RESTful API functionality as well as supports real time testing of the service through JSON request/response transactions.

https://communications.avalara.net/API/AFCSaaSProTax

Please see the Avalara for Communications REST v2 Developer Guide for more information on how to utilize the REST v2 API.

Submit a support case for more information on setting up an account or for access to the viewer and reporting web portal.

Architecture

AFC License

The licensed implementation of the AFC Engine is built around the creation and usage of a Tax Session.

image

Session Inputs – used to modify session behavior

  • Configuration File – configuration for session
  • Override File – used to override of tax rates and logic
  • Exclusion File – used to exclude countries and states
  • Bundle File – used to bundle transactions together
  • Nexus File – (SAU) used to apply nexus
  • Taxation Data – base tax rates and logic for engine

Taxation Log – contains results of tax calculations

  • Used for generating reports
  • Archived monthly
  • One log per session

Session Reports – reports produced or updated at session exit

  • Status File – information specific to session startup and processing
  • NTL Report – report of transactions that generated no taxes
  • TSR/RTR Report – Revenue report by jurisdiction (Country/State)
  • Transaction Count – Report of transaction counts by market / product

Clients can have one or more tax sessions. Multiple tax sessions can be configured differently to support everything from tax quotes to different legal entities. Reporting occurs at the session level.

AFC SaaS Pro

The AFC SaaS Pro Web Service is built around the creation and usage of an Account. An account can be compared to a Session in that each account has configuration options and associated reports. If a given account requires multiple configurations, sub-accounts must be created for each different configuration. While a session log has a distinct set of output files to differentiate it from other sessions, an account has distinct credentials to differentiate it from other accounts. For reporting purposes, each account also has an assigned Company Identifier that can be used to differentiate between test transactions or quotes and billable transactions.

Comparisons

Supporting multiple legal entities

  • AFC License users can create multiple tax sessions for different configuration and reporting
  • AFC SaaS Pro users can create multiple sub accounts for different configuration and reporting

Supporting quotes or test transactions

  • AFC License users can create a no log session for quotes and test transactions
  • AFC SaaS Pro users can leave the Company Identifier blank or use a test Company Identifier for quotes and test transactions

Reporting

AFC License Reporting

  • Reporting for the licensed implementation of the AFC tax engine is based upon the tax session.
  • TSR, RTR, NTL and transactional audit reports are generated at session close and can be accumulated over the billing cycle.
  • All other reports are generated from utilities applied to the transaction log, which is also accumulated over the billing cycle.
  • The client must manage generating, archiving reports.
  • If multiple sessions need to be consolidated, client must manage combining reports / logs.
  • Detailed log report is not available in the licensed implementation

AFC SaaS Pro

  • Reporting for AFC SaaS Pro is based upon the account and, as applicable, any associated sub-accounts.
  • Reporting options exist for automated reporting and for pulling reports from the web portal
  1. Scheduled Reports

    A schedule can be setup by account for monthly generation of the following reports

    • Compliance Reports (ssf, nba, nca)
    • TSR, RTR and NTL Reports
    • Detailed Log Report
  2. Web Portal

    The reporting web portal supports requests for reports. It allows customization and scheduling of the reports.

API Equivalence

Note: There is no concept of a J Code in the AFC SaaS Pro Web Services; therefore, J Code related API’s from the engine have been excluded.

Standard Tax and Adjustment Calculations

C Library

.NET Library

Java Library

SaaS Pro – SOAP

SaaS Pro - REST v1

SaaS Pro - REST v2

EZTaxPCodeEx

CalculateTaxes

calculateTaxes

CalcTaxesWithPCode

CalculateTaxes

CalcTaxes

EZTaxNPANEx

CalcTaxesWithNpaNxx

EZTaxZipEx

CalcTaxesWithZipAddress

EZTaxAdjPCodeEx

CalculateAdjustments

calculateAdjustments

CalcAdjWithPCode

CalculateAdjustments

EZTaxAdjNPANEx

CalcAdjWithNpaNxx

EZTaxAdjZipEx

CalcAdjWithZipAddress

EZTaxTaxInclusivePCode

CalculateTaxInclusiveTaxes

calculateTaxInclusiveTaxes

CalcTaxInclusiveTaxesWithPCode

CalculateTaxInclusive/Taxes

EZTaxTaxInclusiveNPAN

CalcTaxInclusiveTaxesWithNpaNxx

EZTaxTaxInclusiveZip

CalcTaxInclusiveTaxesWithZipAddress

EZTaxAdjTaxInclusivePCode

CalculateTaxInclusiveAdjustments

calculateTaxInclusiveAdjustments

CalcTaxInclusiveAdjWithPCode

CalculateTaxInclusive/Adjustments

EZTaxAdjTaxInclusiveNPAN

CalcTaxInclusiveAdjWithNpaNxx

EZTaxAdjTaxInclusiveZip

CalcTaxInclusiveAdjWithZipAddress

Prepaid / Debit Tax and Adjustment Calculations

(All interfaces other than C Library use Debit flag to indicate a Prepaid / Debit transaction)

C Library

.NET Library

Java Library

SaaS Pro – SOAP

SaaS Pro - REST v1

SaaS Pro - REST v2

EZTaxDebitPEx

CalculateTaxes

calculateTaxes

CalcTaxesWithPCode

CalculateTaxes

CalcTaxes

EZTaxDebitNEx

CalcTaxesWithNpaNxx

EZTaxDebitZEx

CalcTaxesWithZipAddress

EZTaxAdjDebitPEx

CalculateAdjustments

calculateAdjustments

CalcAdjWithPCode

CalculateAdjustments

EZTaxAdjDebitNEx

CalcAdjWithNpaNxx

EZTaxAdjDebitZEx

CalcAdjWithZipAddress

EZTaxDebitTaxInclusivePCode

CalculateTaxInclusiveTaxes

calculateTaxInclusiveTaxes

CalcTaxInclusiveTaxesWithPCode

CalculateTaxInclusive/Taxes

EZTaxDebitTaxInclusiveNPAN

CalcTaxInclusiveTaxesWithNpaNxx

EZTaxDebitTaxInclusiveZip

CalcTaxInclusiveTaxesWithZipAddress

EZTaxAdjDebitTaxInclusivePCode

CalculateTaxInclusiveAdjustments

calculateTaxInclusiveAdjustments

CalcTaxInclusiveAdjWithPCode

CalculateTaxInclusive/Adjustments

EZTaxAdjDebitTaxInclusiveNPAN

CalcTaxInclusiveAdjWithNpaNxx

EZTaxAdjDebitTaxInclusiveZip

CalcTaxInclusiveAdjWithZipAddress

Pro-rated Tax and Adjustment Calculations

C Library

.NET Library

Java Library

SaaS Pro – SOAP

SaaS Pro - REST v1

SaaS Pro - REST v2

EZTaxProRatePCodeEx

CalculateProRatedTaxes

calculateProRatedTaxes

CalcProRatedTaxes

CalculateProRated/Taxes

CalcTaxes

EZTaxProRateNPANEx

EZTaxProRateZipEx

EZTaxAdjProRatePCodeEx

CalculateProRatedAdjustments

calculateProRatedAdjustments

CalcProRatedAdj

CalculateProRated/Adjustments

EZTaxAdjProRateNPANEx

EZTaxAdjProRateZipEx

Bridge Conference Tax and Adjustment Calculations

C Library

.NET Library

Java Library

SaaS Pro – SOAP

SaaS Pro - REST v1

SaaS Pro - REST v2

EZTaxBridgeConference

CalculateTaxes

Not available

CalcBridgeConferenceTaxes

Not available

Not available

(flag setting for adjustments)

(flag setting for adjustments)

Not available

CalcAdjBridgeConferenceTaxes

Not available

Not available

Invoice / Customer Mode Handling

General difference

AFC License

  • Has invoice mode on or off for session
  • When on, all tax calculations apply to the current invoice mode session
  • When complete, invoice mode must be turned off or new invoice mode session automatically will start

AFC SaaS Pro

  • Request is mode for invoice mode batch id
  • Tax calculations for that batch must pass in the batch id
  • When complete, batch id is automatically disabled and cannot be used again
  • Client has option to pass all transactions in single batch request

Invoking

C Library

.NET Library

Java Library

SaaS Pro – SOAP

SaaS Pro - REST v1

SaaS Pro - REST v2

EZTaxSetCustModeEx(1)

(Turns mode on)

CustomerModeOn = true

(Turns mode on)

setCustomerMode(true)

(Turns mode on)

BeginCustomerBatch

(Returns batch id)

CustMode/BeginBatch

(Returns batch id)

CalcTaxes

(Returns summarized tax results)

Calculating Taxes and/or Adjustments

C Library

.NET Library

Java Library

SaaS Pro – SOAP

SaaS Pro - REST v1

SaaS Pro - REST v2

(Any)

(Any)

(Any)

CalcCustTaxes

CustMode/CalcTaxes

CalcTaxes

CalcCustAdj

CustMode/CalcAdjustments

Getting Customer Totals

C Library

.NET Library

Java Library

SaaS Pro – SOAP

SaaS Pro - REST v1

SaaS Pro - REST v2

EZTaxNextCustomerEx

GetCustomerTotals

getCustomerTotals

ProcessCustomerBatch

CustMode/ProcessBatch

CalcTaxes

Disabling

C Library

.NET Library

Java Library

SaaS Pro – SOAP

SaaS Pro - REST v1

SaaS Pro - REST v2

EZTaxSetCustModeEx(0)

CustomerModeOn = false

setCustomerMode(false)

n/a

n/a

n/a

Single Batch

C Library

.NET Library

Java Library

SaaS Pro – SOAP

SaaS Pro - REST v1

SaaS Pro - REST v2

n/a

n/a

n/a

CalcTaxesInCustMode

CustMode/CalcTaxesInCustMode

CalcTaxes

API Level Exclusions

General difference

AFC License – C Interface

  • Has API to set exclusions which apply to all transactions going forward
  • Exclusions set are in combination with existing exclusions (last setting applies)
  • To clear the exclusions, the values set must be reversed or cleared
  • .NET interface also has option to add exclusions to transaction

AFC SaaS Pro

  • API exclusions are included in the transaction and apply only to that transaction
  • File based exclusions are rolled out when exclusions are applied and rolled back in after the calculation is complete

Setting Exclusions via API

C Library

.NET Library

Java Library

SaaS Pro – SOAP

SaaS Pro - REST v1

SaaS Pro - REST v2

EZTaxSetStateExclusion

SetStateExclusion

setStateExclusion

(Added to transaction)

(Added to transaction)

(Added to transaction)

Clearing Exclusions via API

 

C Library

.NET Library

Java Library

SaaS Pro – SOAP

SaaS Pro - REST v1

SaaS Pro - REST v2

EZTaxSetStateExclusion

ClearExclusions

clearExclusions

n/a

n/a

n/a

API Level Overrides

General difference

AFC License – C Interface

  • Override(s) must be set via API and is combined with any existing overrides in place (last setting applies)
  • Override(s) must be cleared via API and clears all overrides, including file based overrides
  • Override(s) may be rate or logic overrides. .NET and Java wrappers support rate based overrides only.

AFC SaaS Pro

  • API overrides are included in the transaction and apply only to that transaction
  • File based overrides and API based overrides are not compatible and will produce an exception. One or the other but not both are supported.
  • Only supports rate based API overrides

Setting Rate Based Overrides via API

C Library

.NET Library

Java Library

SaaS Pro – SOAP

SaaS Pro - REST v1

SaaS Pro - REST v2

EZTaxOvrPCodeEx

AddOverrideByPCode

addOverrideByPCode

n/a

n/a

n/a

EZTaxOvrNPANEx

AddOverrideByNpaNxx

addOverrideByNpaNxx

EZTaxOvrZipEx

AddOverrideByAddress

addOverrideByAddress

Setting Logic Based Overrides via API

C Library

.NET Library

Java Library

SaaS Pro – SOAP

SaaS Pro - REST v1

SaaS Pro - REST v2

EZTaxLogicOvrJCodeEx

n/a

n/a

n/a

n/a

n/a

Calculating Taxes and/or Adjustments

C Library

.NET Library

Java Library

SaaS Pro – SOAP

SaaS Pro - REST v1

SaaS Pro - REST v2

(Any)

(Any)

(Any)

CalcTaxesWithOverrides

CalculateWithOverrides/Taxes

CalcTaxes

CalcAdjWithOverrides

CalculateWithOverrides/Adjustments

Clearing Overrides

C Library

.NET Library

Java Library

SaaS Pro – SOAP

SaaS Pro - REST v1

SaaS Pro - REST v2

EZTaxRestoreEx

ClearOverrides

clearOverrides

n/a

n/a

n/a

Cross-Reference and Lookup API’s

C Library

.NET Library

Java Library

SaaS Pro – SOAP

SaaS Pro - REST v1

SaaS Pro - REST v2

EZTaxFtoPCodeEx

FipsToPCode

fipsToPCode

FipsToPCode

n/a

/api/v2/afc/PCode

 

EZTaxNtoJCodeEx

NpaNxxToJCode

npaNxxToJCode

NpaNxxToPCode

n/a

EZTaxZtoPCodeEx

ZipToPCode

zipToPCode

ZipToPCode

ZipLookup

Location/PCode

EZTaxPtoFipsEx

PCodeToFips

pCodeToFips

PCodeToFips

Location/PCodeToFips/{pCode}

n/a

EZTaxCountryToPCode

CountryToPCode

countryIsoToPCode

ZipToPCode

ZipLookup

Location/PCode

/api/v2/afc/PCode

 

EZTaxGetAddressEx

EZTaxNextAddressEx

GetAddress

getAddress

GetAddress

Location/Address/{pCode}

EZTaxGetTaxCatV98

GetTaxCategory

getTaxCategory

GetTaxCategory

TaxLookup/Category/{taxType}

/api/v2/afc/taxtype/{taxType}

EZTaxGetTaxDescription

GetTaxDescription

getTaxDescription

GetTaxDescription

TaxLookup/Description/{taxType}

EZTaxGetRates

GetTaxRates

getTaxRates

GetTaxRates

TaxLookup/TaxRates/{pCode}

n/a

EZTaxDllVersion

DllVersion

getDllVersion

GetEZTaxVersion

Application/AFCEngineVersion

/api/v2/afc/serviceinfo

EZTaxDbVersion

GetDatabaseVersion

getDatabaseVersion

GetEZTaxDbVersion

Application/AFCDatabaseEngineVersion

Configuration

AFC SaaS Pro supports all standard optional configuration files.

  • Override File
  • Exclusion File
  • Bundle File
  • Nexus File

The files can be migrated from the AFC License implementation to AFC SaaS Pro by sending the file(s) via a support case. with a request that the file(s) be applied to your AFC SaaS Pro account. If a specific date/time is desired, that can be coordinated with support personnel.

  • Was this article helpful?