Billing Central Apex API Developer Reference

ffbc.AvalaraTaxService

global with sharing class AvalaraTaxService

This class provides the functionality required to connect to Avalara. Salesforce determines the maximum number of callouts that you can make to an external service such as Avalara. See the Salesforce documentation for more information.

Enums

MessageSeverity

an enum representing the severities of messages returned by avalara.

Value Description
Info An information message.
Warning A warning message.
Error An error message.

Methods

getSettings

global static ffbc.AvalaraTaxService.Settings getSettings()

Retrieves the Billing Central tax calculation settings for the org.

Return Value

The wrapper containing the settings.

saveSettings

global static void saveSettings(ffbc.AvalaraTaxService.Settings settings)

Saves settings.

Input Parameters

Name Type Description
settings ffbc.AvalaraTaxService.Settings The wrapper containing the settings to be saved.

Exceptions Thrown

Value Description
BillingCentralException An exception is thrown if the settings are invalid.

getTax

global static List<ffbc.AvalaraTaxService.TaxResponse> getTax(List<ffbc.AvalaraTaxService.TaxDocument> documents)

Sends a request to Avalara to calculate tax for the documents provided and returns the response. To calculate tax, the connection details on the Tax Calculation Settings tab must be valid.

Input Parameters

Name Type Description
documents List<ffbc.AvalaraTaxService.TaxDocument> List of documents for which to calculate tax.

Exceptions Thrown

Value Description
BillingCentralException An exception is thrown if:
- The external tax calculation settings on the Tax Calculation Settings tab are not enabled
- The Summary Tax Code set in the FFBC Tax Calculation Settings tab is invalid
- A document is null
- A document is not associated with a company
- A document is not associated with an account
- A document has no line items
- A document is associated with a company that does not have an address
- A document has no addresses
- A document has a shipping address with no account name
- A document has no account names
- A document has no currency ISO code
- The number of documents exceeds the maximum number of calls that can be made to Avalara.

Return Value

The response to the tax calculation request for each document. Responses are provided in the same order in which the documents were supplied.

validateDocuments

global static List<ffbc.AvalaraTaxService.DocumentValidationError> validateDocuments(Set<Id> billingDocumentIds)

Validates that a document can be taxed.

Input Parameters

Name Type Description
billingDocumentIds Set<Id> The Ids of the billing documents to be validated.

Return Value

A list of validation errors. If this list is empty, the billing documents are valid.

calculate

global static List<ffbc.AvalaraTaxService.TaxResponse> calculate(Set<Id> billingDocumentIds)

Sends a request to calculate tax for the given documents to Avalara, provided that no errors are encountered, then sets the tax rates and values on the document line items according to the response. If the process encounters an error, it stops and throws an exception. To calculate tax, the connection details on the Tax Calculation Settings tab must be valid.

Input Parameters

Name Type Description
billingDocumentIds Set<Id> List of billing documents for which to calculate tax.

Exceptions Thrown

Value Description
BillingCentralException An exception is thrown if:
- The external tax calculation settings on the Tax Calculation Settings tab are not enabled
- The status of the document is "Complete"
- The document is not associated with a company
- The document is not associated with an account
- The Summary Tax Code set in the FFBC Tax Calculation Settings tab is invalid
- The document has no line items
- A document has no addresses
- A document has a shipping address with no account name
- A document has no account names
- The number of billing document IDs in the request exceeds the maximum number of calls that can be made to Avalara

Return Value

The response to the tax calculation request for each document.

calculate

global static List<ffbc.AvalaraTaxService.TaxResponse> calculate(ffbc.AvalaraTaxService.TaxRequest request)

Sends a request to calculate tax for the given documents to Avalara, then sets the tax rates and values on the document line items according to the response.
When the ThrowExceptionForInvalidBillingDocument request parameter is set to true and a billing document isn't valid, the process stops and throws an exception. When the ThrowExceptionForInvalidBillingDocument request parameter is set to false and a billing document isn't valid, the process continues and returns an error in the response.
To calculate tax, the connection details on the Tax Calculation Settings tab must be valid.

Input Parameters

Name Type Description
request ffbc.AvalaraTaxService.TaxRequest Contains the information needed to calculate tax with Avalara for the billing documents.

Exceptions Thrown

Value Description
BillingCentralException An exception is thrown if the ThrowExceptionForInvalidBillingDocument request parameter is set to true and one of the following is true:
- The external tax calculation settings on the Tax Calculation Settings tab are not enabled
- The status of the document is "Complete"
- The document is not associated with a company
- The document is not associated with an account
- The Summary Tax Code set in the FFBC Tax Calculation Settings tab is invalid
- The document has no line items
- A document has no addresses
- A document has a shipping address with no account name
- A document has no account names
- The number of billing document IDs in the request exceeds the maximum number of calls that can be made to Avalara

Return Value

The response to the tax calculation request for each document.

Sample Code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
//Note: This sample code is for demonstration purposes only. It is not intended for
//use in a production environment, is not guaranteed against defects or errors, and
//is in no way optimized or streamlined.
 
/**
 * Example of using calculate() method of AvalaraTaxService API
 * Variables marked by asterisks need to be queried from your organisation's data.
 */
 
//Set of billing documents for which tax will be calculated with Avalara, identified by ID.
Set<Id> setOfBillingDocumentIds = New Set<Id> {*billingDocumentIds*};
 
ffbc.AvalaraTaxService.TaxRequest request = New ffbc.AvalaraTaxService.TaxRequest();
 
request.BillingDocumentIds = setOfBillingDocumentIds;
request.ThrowExceptionForInvalidBillingDocument = false;
 
List<ffbc.AvalaraTaxService.TaxResponse> responses = ffbc.AvalaraTaxService.calculate(request);

calculateAsync

global static ffbc.AvalaraTaxService.TaxAsyncResponse calculateAsync(Set<Id> billingDocumentIds)

Sends requests to calculate tax for the given documents to Avalara using a background process. As each response is received from Avalara, sets the tax rates and values on the corresponding billing document line items according to the response.
To calculate tax, the connection details on the Tax Calculation Settings tab must be valid.

Input Parameters

Name Type Description
billingDocumentIds Set<Id> List of billing documents for which to calculate tax.

Return Value

A response containing the background process ID and the background process job ID.

Sample Code

1
2
3
4
5
6
7
8
9
10
11
12
13
//Note: This sample code is for demonstration purposes only. It is not intended for
//use in a production environment, is not guaranteed against defects or errors, and
//is in no way optimized or streamlined.
 
/**
 * Example of using calculateAsync() method of AvalaraTaxService API
 * Variables marked by asterisks need to be queried from your organisation's data.
 */
 
//Set of billing documents for which tax will be calculated with Avalara, identified by ID.
Set<Id> setOfBillingDocumentIds = New Set<Id> {*billingDocumentIds*};
 
ffbc.AvalaraTaxService.TaxAsyncResponse response = ffbc.AvalaraTaxService.calculateAsync(setOfBillingDocumentIds);

commitTax

global static List<ffbc.AvalaraTaxService.TaxResponse> commitTax(ffbc.AvalaraTaxService.TaxRequest request)

Sends a request to calculate and commit tax for the given documents to Avalara, then sets the tax rates and values on the document line items according to the response.
When the ThrowExceptionForInvalidBillingDocument request parameter is set to true and a billing document isn't valid, the process stops and throws an exception. If the process throws an exception, users should check what documents have been committed to Avalara to ensure all values are correct. When the ThrowExceptionForInvalidBillingDocument request parameter is set to false and a billing document isn't valid, the process continues and returns an error in the response.
To commit tax, the connection details on the Tax Calculation Settings tab must be valid.

Input Parameters

Name Type Description
request ffbc.AvalaraTaxService.TaxRequest Contains the information needed to commit tax with Avalara for the billing documents.

Exceptions Thrown

Value Description
BillingCentralException An exception is thrown if the ThrowExceptionForInvalidBillingDocument
- The external tax calculation settings on the Tax Calculation Settings tab are not enabled
- The Disable Commit checkbox is checked on the Tax Calculation Settings tab.
- The status of the document is "Complete"
- The document is not associated with a company
- The document is not associated with an account
- The Summary Tax Code set in the FFBC Tax Calculation Settings tab is invalid
- The document has no line items
- A document has no addresses
- A document has a shipping address with no account name
- A document has no account names
- The number of billing document IDs in the request exceeds the maximum number of calls that can be made to Avalara

Return Value

The response of the tax commit request for each document.

Sample Code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
//Note: This sample code is for demonstration purposes only. It is not intended for
//use in a production environment, is not guaranteed against defects or errors, and
//is in no way optimized or streamlined.
 
/**
 * Example of using commitTax() method of AvalaraTaxService API
 * Variables marked by asterisks need to be queried from your organisation's data.
 */
 
//Set of billing documents for which tax will be calculated and committed with Avalara, identified by ID.
Set<Id> setOfBillingDocumentIds = New Set<Id> {*billingDocumentIds*};
 
ffbc.AvalaraTaxService.TaxRequest request = New ffbc.AvalaraTaxService.TaxRequest();
 
request.BillingDocumentIds = setOfBillingDocumentIds;
request.ThrowExceptionForInvalidBillingDocument = false;
 
List<ffbc.AvalaraTaxService.TaxResponse> responses = ffbc.AvalaraTaxService.commitTax(request);

commitTaxAsync

global static ffbc.AvalaraTaxService.TaxAsyncResponse commitTaxAsync(Set<Id> billingDocumentIds)

Sends requests to commit tax for the given documents to Avalara using a background process. As each response is received from Avalara, sets the tax rates and values on the corresponding billing document line items according to the response.
To commit tax, the connection details on the Tax Calculation Settings tab must be valid.

Input Parameters

Name Type Description
billingDocumentIds Set<Id> List of billing documents for which to commit tax.

Return Value

A response containing the background process ID and the background process job ID.

Sample Code

1
2
3
4
5
6
7
8
9
10
11
12
13
//Note: This sample code is for demonstration purposes only. It is not intended for
//use in a production environment, is not guaranteed against defects or errors, and
//is in no way optimized or streamlined.
 
/**
 * Example of using commitTaxAsync() method of AvalaraTaxService API
 * Variables marked by asterisks need to be queried from your organisation's data.
 */
 
//Set of billing documents for which tax will be committed with Avalara, identified by ID.
Set<Id> setOfBillingDocumentIds = New Set<Id> {*billingDocumentIds*};
 
ffbc.AvalaraTaxService.TaxAsyncResponse response = ffbc.AvalaraTaxService.commitTaxAsync(setOfBillingDocumentIds);

voidTax

global static List<ffbc.AvalaraTaxService.TaxResponse> voidTax(ffbc.AvalaraTaxService.TaxRequest request)

Sends a request to void tax for the given documents to Avalara.
When the ThrowExceptionForInvalidBillingDocument request parameter is set to true and a billing document isn't valid, the process stops and throws an exception. If the process throws an exception, users should check what documents have been committed to Avalara to ensure all values are correct. When the ThrowExceptionForInvalidBillingDocument request parameter is set to false and a billing document isn't valid, the process continues and returns an error in the response.
To void tax, the connection details on the Tax Calculation Settings tab must be valid.

Input Parameters

Name Type Description
request ffbc.AvalaraTaxService.TaxRequest Contains the information needed to void tax with Avalara for the billing documents.

Exceptions Thrown

Value Description
BillingCentralException An exception is thrown if the ThrowExceptionForInvalidBillingDocument is set to true and:
- The external tax calculation settings on the Tax Calculation Settings tab are not enabled
- The Summary Tax Code set in the FFBC Tax Calculation Settings tab is invalid
- The number of billing document IDs in the request exceeds the maximum number of calls that can be made to Avalara

Return Value

The response of the tax void request for each document.

Sample Code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
//Note: This sample code is for demonstration purposes only. It is not intended for
//use in a production environment, is not guaranteed against defects or errors, and
//is in no way optimized or streamlined.
 
/**
 * Example of using voidTax() method of AvalaraTaxService API
 * Variables marked by asterisks need to be queried from your organisation's data.
 */
 
//Set of billing documents for which tax will be voided in Avalara, identified by ID.
Set<Id> setOfBillingDocumentIds = New Set<Id> {*billingDocumentIds*};
 
ffbc.AvalaraTaxService.TaxRequest request = New ffbc.AvalaraTaxService.TaxRequest();
 
request.BillingDocumentIds = setOfBillingDocumentIds;
request.ThrowExceptionForInvalidBillingDocument = false;
 
List<ffbc.AvalaraTaxService.TaxResponse> responses = ffbc.AvalaraTaxService.voidTax(request);

voidTaxAsync

global static ffbc.AvalaraTaxService.TaxAsyncResponse voidTaxAsync(Set<Id> billingDocumentIds)

Sends requests to void tax for the given documents to Avalara using a background process.
To void tax, the connection details on the Tax Calculation Settings tab must be valid.

Input Parameters

Name Type Description
billingDocumentIds Set<Id> List of billing documents for which to void tax.

Return Value

A response containing the background process ID and the background process job ID.

Sample Code

1
2
3
4
5
6
7
8
9
10
11
12
13
//Note: This sample code is for demonstration purposes only. It is not intended for
//use in a production environment, is not guaranteed against defects or errors, and
//is in no way optimized or streamlined.
 
/**
 * Example of using voidTaxAsync() method of AvalaraTaxService API
 * Variables marked by asterisks need to be queried from your organisation's data.
 */
 
//Set of billing documents for which tax will be voided in Avalara, identified by ID.
Set<Id> setOfBillingDocumentIds = New Set<Id> {*billingDocumentIds*};
 
ffbc.AvalaraTaxService.TaxAsyncResponse response = ffbc.AvalaraTaxService.voidTaxAsync(setOfBillingDocumentIds);

ffbc.AvalaraTaxService.DocumentValidationError

global with sharing class DocumentValidationError

this class wraps an error identified when validating a billing document.

Properties

Name Type Description
DocumentId Id Read only. The Id of the document that was validated.
Message String Read only. The message associated with the validation error.

ffbc.AvalaraTaxService.Message

global with sharing class Message

this class wraps a message associated with a response to an external tax calculation request.

Properties

Name Type Description
Severity ffbc.AvalaraTaxService.MessageSeverity Read only. The severity of the message. Messages returned by Avalara requests have a severity of Info, Warning or Error.
Summary String Read only. The summary of the message.

ffbc.AvalaraTaxService.Settings

global with sharing class Settings

this class wraps the tax calculation settings for an organization.

Properties

Name Type Description
SummaryTaxCode Id Tax code that represents summarized tax on a billing document line item. A valid tax code record with the same ID must exist in the Tax Codes object. The tax rates are generated by Avalara.
DisableTaxDetailCreate Boolean If true, tax breakdown records are not automatically created when calculating tax on billing documents.

Methods

Settings

global Settings()

The default constructor for this object.

ffbc.AvalaraTaxService.TaxDocument

global with sharing class TaxDocument

An object representing a document for which tax can be calculated using Avalara.

Properties

Name Type Description
DocumentDate Date the document date.
Name String the name of the document.
CurrencyIsoCode String The currency ISO code of the document. The default value is the default currency of your Salesforce organization.
CompanyId Id the id of the company associated with the document.
AccountId Id the id of the account associated with the document.
BillingAccountName String the name of the document billing account.
BillingStreet String the street of the document billing address.
BillingCity String the city of the document billing address.
BillingState String the state of the document billing address.
BillingPostalCode String the postal code of the document billing address.
BillingCountry String the country of the document billing address.
ShippingAccountName String the name of the document shipping account.
ShippingStreet String the street of the document shipping address.
ShippingCity String the city of the document shipping address.
ShippingState String the state of the document shipping address.
ShippingPostalCode String the postal code of the document shipping address.
ShippingCountry String the country of the document shipping address.
CustomerUsageType String the identifier for the tax exemption reason on the account associated with the document.
LineItems List<ffbc.AvalaraTaxService.TaxDocumentLineItem> the line items associated with the document.

Methods

TaxDocument

global TaxDocument()

The default constructor for this object.

ffbc.AvalaraTaxService.TaxDocumentLineItem

global with sharing class TaxDocumentLineItem

An object representing a line item of a document for which tax can be calculated using Avalara.

Properties

Name Type Description
LineNo String a name which uniquely identifies the line on the document to which it relates. This value corresponds to the LineNo field on a TaxResponseLine object.
Description String a description of the line item.
ProductId Id the id of the product associated with the line item.
Quantity Decimal the quantity of the line item.
NetValue Decimal the net value of the line item.
ShippingStreet String the street of the line item shipping address.
ShippingCity String the city of the line item shipping address.
ShippingState String the state of the line item shipping address.
ShippingPostalCode String the postal code of the line item shipping address.
ShippingCountry String the country of the line item shipping address.
CustomerUsageType String the identifier for the tax exemption reason on the shipping account associated with the line item.
TaxCode String tax identifier for the product.
CompanyStreet String the street of the line item company site address.
CompanyCity String the city of the line item company site address.
CompanyState String the state of the line item company site address.
CompanyPostalCode String the postal code of the line item company site address.
CompanyCountry String the country of the line item company site address.

Methods

TaxDocumentLineItem

global TaxDocumentLineItem()

The default constructor for this object.

ffbc.AvalaraTaxService.TaxRequest

global with sharing class TaxRequest

This class provides the information required to calculate tax with Avalara for the billing documents.

Properties

Name Type Description
BillingDocumentIds Set<Id> Set of billing documents to calculate taxes, identified by ID.
ThrowExceptionForInvalidBillingDocument Boolean When set to true and a billing document from the request isn't valid, the process stops and throws an exception. When set to false and a billing document from the request isn't valid, the process continues and returns an error in the response.

ffbc.AvalaraTaxService.TaxResponse

global with sharing class TaxResponse

this class wraps a response to a tax calculation request.

Properties

Name Type Description
Success Boolean Read only. The success status of the request returned by Avalara.
Messages List<ffbc.AvalaraTaxService.Message> Read only. The list of messages associated with the response.
TaxLines List<ffbc.AvalaraTaxService.TaxResponseLine> Read only. The list of response lines corresponding to the document line items.
DocumentId Id Read only. The ID of the document to which the response relates.
SummaryTaxCodeId Id Read only. The ID of the summary tax code for external tax calculation.

ffbc.AvalaraTaxService.TaxAsyncResponse

global with sharing class TaxAsyncResponse extends Response

this class wraps a response to an async tax calculation request.

This class extends ffbc.Response

Properties

Name Type Description
BackgroundProcessId Id Read only. The ID of the background process record.
RunId Id Read only. The ID of the background process job running on the billing documents.

ffbc.AvalaraTaxService.TaxResponseLine

global with sharing class TaxResponseLine

this class wraps a line of a response to a tax calculation request.

Properties

Name Type Description
LineNo String Read only. The name of the document line item to which the response line relates.
Tax Decimal Read only. The tax value of the line item calculated by the external tax calculation service.
Rate Decimal Read only. The tax rate of the line item calculated by the external tax calculation service, as a fraction.
CalculatedRate Decimal Read only. The tax rate of the line item as a percentage. This is calculated from the response given by the external tax calculation service.
TaxDetails List<ffbc.AvalaraTaxService.TaxResponseDetail> Tax breakdown details by jurisdiction.

ffbc.AvalaraTaxService.TaxResponseDetail

global with sharing class TaxResponseDetail

Tax breakdown details by jurisdiction, provided by Avalara.

Properties

Name Type Description
Country String Country of the tax jurisdiction.
JurisdictionName String Name of the tax jurisdiction.
JurisdictionType String Type of the tax jurisdiction.
JurisdictionCode String Code of the tax jurisdiction.
Rate Decimal Tax rate for the tax jurisdiction.
Region String Region of the tax jurisdiction.
Tax Decimal Tax amount for the jurisdiction.
TaxName String Name of the tax.
Taxable Decimal The amount that is taxable.

Methods

TaxResponseDetail

global TaxResponseDetail()

Constructor for the TaxResponseDetail.

© Copyright 2009–2021 FinancialForce.com, inc. All rights reserved. Various trademarks held by their respective owners.