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

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

//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

//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);

getSettings

global static ffbc.AvalaraTaxService.Settings getSettings()

Retrieves the Billing Central tax calculation settings for the org.

Return Value

The wrapper containing the settings.

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.

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.

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.

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.

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.
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.

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.
© Copyright 2009–2020 FinancialForce.com, inc. Confidential – all rights reserved. Various trademarks held by their respective owners.