Foundations Apex API Developer Reference

fferpcore.BillingDocumentService

global with sharing class BillingDocumentService

Services for Billing Documents.

Properties

Name Type Description
MESSAGE_TYPE_COMPLETION_PROCESS String Message type developer name for Completion Process request messages.
MESSAGE_TYPE_COMPLETION_RESPONSE String Message type developer name for Completion Process response messages.
MESSAGE_TYPE_COMPLETION_COMPLETE String Message type developer name for Document Complete messages.
MESSAGE_TYPE_TAXED String Message type developer name for Document Taxed messages.

Enums

Type

An enum that represents the valid options for the billing document type.

Value Description
Invoice Option that shows the object represented is an Invoice.
CreditNote Option that shows the object represented is a Credit Note.

ProcessState

State of a completion process.

Value Description
FAILED The process has failed.
PENDING The process is pending asynchronous results.
COMPLETE The process is complete.

Methods

completeDocuments

global static Map<Id, fferpcore.BillingDocumentService.ProcessResult> completeDocuments(Set<Id> billingDocumentIds)

Complete billing documents. The documents must be in draft state, have a least one line and not have a completion in progress. Applications may add further validation.

Input Parameters

Name Type Description
billingDocumentIds Set<Id> Set of IDs of billing documents to complete.

Return Value

Map of completion process results keyed on billing document Id.

verifyPermissionsForCalculateTax

global static fferpcore.BillingDocumentService.CalculateTaxPermissionResponse verifyPermissionsForCalculateTax()

Verifies that the current user has sufficient permissions to calculate tax. The same check is used by calculateTax. We recommend that you call this before attempting to call calculateTax. For example, if you have a screen which calculates tax, you can call verifyPermissionsForCalculateTax when the user arrives on the screen to check that they have the correct permissions to use it.

Return Value

The results of the verification. See BillingDocumentService.CalculateTaxPermissionResponse for details.

verifyAsyncPermissionsForCalculateTax

global static fferpcore.BillingDocumentService.CalculateTaxAsyncPermissionResponse verifyAsyncPermissionsForCalculateTax()

Verifies that the current user has sufficient permissions to calculate tax asynchronously. The same check is used by calculateTaxAsync. We recommend that you call this before attempting to call calculateTaxAsync. For example, if you have a screen which calculates tax asynchronously, you can call verifyAsyncPermissionsForCalculateTax when the user arrives on the screen to check that they have the correct permissions to use it.

Return Value

The results of the verification. See BillingDocumentService.CalculateTaxAsyncPermissionResponse for details.

validateForCalculateTax

global static fferpcore.BillingDocumentService.CalculateTaxValidationResponse validateForCalculateTax(fferpcore.BillingDocumentService.CalculateTaxValidationDocument request)

Verifies that a billing document is valid for calculating tax. The same check is used by calculateTax and calculateTaxAsync. If the check fails then the calculate process does not work. We recommend that you call this before attempting to calculate tax. For example, if you have a process which attempts to calculate tax automatically, you can use validateForCalculateTax to filter out invalid documents upfront.

Input Parameters

Name Type Description
request fferpcore.BillingDocumentService.CalculateTaxValidationDocument Tax fields from the billing document that are required for validation.

Exceptions Thrown

Value Description
Exceptions.InvalidArgumentException An exception is thrown if the request is null.

Return Value

The results of the validation. See BillingDocumentService.CalculateTaxValidationResponse for details.

calculateTax

global static fferpcore.BillingDocumentService.CalculateTaxResponse calculateTax(fferpcore.BillingDocumentService.CalculateTaxRequest request)

Calculates tax on selected billing documents. Existing tax codes, rates, and values for the billing document line items are cleared and then populated with the calculated values.

Input Parameters

Name Type Description
request fferpcore.BillingDocumentService.CalculateTaxRequest The billing document IDs for calculating tax.

Exceptions Thrown

Value Description
Exceptions.InvalidArgumentException An exception is thrown if the request is null.
Exceptions.PermissionException An exception is thrown if the user does not have access to the objects and fields that are necessary to calculate tax. You can use BillingDocumentService.verifyPermissionsForCalculateTax to check, before calling this service, whether a user has the necessary permissions. The permission set 'FDN Common Concepts - Billing Documents - Calculate Tax' contains permissions needed to calculate tax. The user will also need access to the Account and Product2 objects.
System.DmlException An exception is thrown if the database operation to update billing document line items fails.

Return Value

The results of calculating tax, showing which billing documents have been successful.

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.

/**
 * This example shows a simple controller class which allows a user to calculate tax for several billing documents selected from a list view.
 * It checks first whether a user has access to the required objects. If they do not then it shows any errors and does not proceed.
 * When the user tries to calculate tax it checks whether any documents are invalid, and removes them from the request. All valid documents
 * are sent to have tax calculated. Any errors encountered are shown on the screen.
 * Note that this is only appropriate for dealing with a small number of billing documents which do not have many lines, because all the documents will
 * be updated in a single transaction and so may run into Salesforce platform limits on the amount of work that can be performed. For larger
 * documents calculateTaxAsync is appropriate instead, and the permission check would be replaced with a call to verifyAsyncPermissionsForCalculateTax.
 */

public class CalculateTaxController
{
    private List<fferpcore__BillingDocument__c> billingDocuments;
    private Boolean hasPermission;

    public CalculateTaxController(ApexPages.StandardSetController stdController)
    {
        //The selected billing documents
        billingDocuments = (List<fferpcore__BillingDocument__c>)stdController.getSelected();

        //Checks that the running user has the permissions necessary to calculate tax
        fferpcore.BillingDocumentService.CalculateTaxPermissionResponse permission = fferpcore.BillingDocumentService.verifyPermissionsForCalculateTax();
        if (permission.Errors.isEmpty())
        {
            hasPermission = true;
        }
        else
        {
            ApexPages.addMessage(new ApexPages.Message(ApexPages.Severity.ERROR, permission.Errors[0]));
            hasPermission = false;
        }
    }

    public void calculateTax()
    {
        if (!hasPermission)
        {
            return;
        }

        fferpcore.BillingDocumentService.CalculateTaxRequest calculateRequest = new fferpcore.BillingDocumentService.CalculateTaxRequest();

        //Finds which documents are valid upfront, and only tries to calculate tax for the valid ones
        for (fferpcore__BillingDocument__c document : billingDocuments)
        {
            fferpcore.BillingDocumentService.CalculateTaxValidationDocument validationRequest = new fferpcore.BillingDocumentService.CalculateTaxValidationDocument();
            validationRequest.AccountId = document.fferpcore__Account__c;
            validationRequest.CompanyId = document.fferpcore__Company__c;
            validationRequest.CompanyTaxInformationId = document.fferpcore__Company__r.fferpcore__TaxInformation__c;
            validationRequest.DocumentDate = document.fferpcore__DocumentDate__c;
            validationRequest.Status = document.fferpcore__DocumentStatus__c;

            fferpcore.BillingDocumentService.CalculateTaxValidationResponse validateResponse = fferpcore.BillingDocumentService.validateForCalculateTax(validationRequest);
            if (validateResponse.Errors.isEmpty())
            {
                //Success! We know this document will be valid for tax calculation.
                calculateRequest.BillingDocumentIds.add(document.Id);
            }
            else
            {
                //Shows the problems we encountered for particular documents.
                for (String error : validateResponse.Errors)
                {
                    ApexPages.addMessage(new ApexPages.Message(ApexPages.Severity.ERROR, 'Error for document ' + document.Id + ': ' + error));
                }
            }
        }

        //Calculates tax and updates the documents
        fferpcore.BillingDocumentService.CalculateTaxResponse calculateResponse = fferpcore.BillingDocumentService.calculateTax(calculateRequest);

        //Certain errors, such as an invalid set of tax rates, will only surface after calculating tax, so it's important to check whether this has been successful.
        for (fferpcore.BillingDocumentService.CalculateTaxResult result : calculateResponse.Results)
        {
            if (result.Errors.isEmpty())
            {
                //Tax calculated successfully!
                ApexPages.addMessage(new ApexPages.Message(ApexPages.Severity.CONFIRM, 'Tax calculated for ' + result.DocumentId));
            }
            else
            {
                for (String error : result.Errors)
                {
                    ApexPages.addMessage(new ApexPages.Message(ApexPages.Severity.ERROR, 'Error for document ' + result.DocumentId + ': ' + error));
                }
            }
        }
    }
}

calculateTaxAsync

global static fferpcore.BillingDocumentService.CalculateTaxAsyncResponse calculateTaxAsync(fferpcore.BillingDocumentService.CalculateTaxAsyncRequest request)

Calculates tax on billing documents by running an asynchronous process. Existing tax codes, rates, and values for the billing document line items are cleared and then populated with the calculated values.

Input Parameters

Name Type Description
request fferpcore.BillingDocumentService.CalculateTaxAsyncRequest The billing document IDs for calculating tax.

Exceptions Thrown

Value Description
Exceptions.InvalidArgumentException An exception is thrown if the request is null.
Exceptions.PermissionException An exception is thrown if the user does not have access to the objects and fields that are necessary to calculate tax. You can use BillingDocumentService.verifyAsyncPermissionsForCalculateTax to check whether a user has the necessary permissions before calling this service. The permission set 'FDN Common Concepts - Billing Documents - Calculate Tax' contains permissions needed to calculate tax. The user will also need access to the Account and Product2 objects.

Return Value

The results of the asynchronous process creation. Results for calculating tax are not returned in this response, but are created as fferpcore__ScheduledJobLog__c records against the fferpcore__ScheduledJobRun__c record created here.

getTax

global static fferpcore.BillingDocumentService.GetTaxResponse getTax(fferpcore.BillingDocumentService.GetTaxRequest request)

Calculates tax for the documents provided and returns the calculated tax data. You can use this service for calculating tax on unsaved documents before saving them. The documents provided represent the data that is available on a billing document, but they do not relate to a record on the database. This service does not perform DML.

Input Parameters

Name Type Description
request fferpcore.BillingDocumentService.GetTaxRequest The documents for which to calculate tax.

Exceptions Thrown

Value Description
Exceptions.InvalidArgumentException An exception is thrown if the request contains invalid data.
Exceptions.PermissionException An exception is thrown if the user does not have access to the objects and fields necessary to calculate tax.

Return Value

Results of calculating tax for each document.

deriveDueDate

global static List<fferpcore.BillingDocumentService.DeriveDueDateResponse> deriveDueDate(List<fferpcore.BillingDocumentService.DeriveDueDateRequest> requests)

Derives the document due date for a list of billing documents.

Input Parameters

Name Type Description
requests List<fferpcore.BillingDocumentService.DeriveDueDateRequest> The information required to derive the document due date for a list of billing documents.

Return Value

The result of deriving the document due date for a list of billing documents. The list of responses is returned in the same order as the list of requests.

fferpcore.BillingDocumentService.ProcessResult

global inherited sharing class ProcessResult

The result of a completion process.

Properties

Name Type Description
DocumentId Id The Billing Document Id.
State fferpcore.BillingDocumentService.ProcessState The state of the completion process.
Messages List<String> Any messages generated by the process.

Methods

ProcessResult

global ProcessResult(Id documentId, fferpcore.BillingDocumentService.ProcessState state, List<String> messages)

Constructs a ProcessResult.

Input Parameters

Name Type Description
documentId Id The blling document Id.
state fferpcore.BillingDocumentService.ProcessState The state of the process.
messages List<String> Any messages generated by the process.

fferpcore.BillingDocumentService.AbstractCalculateTaxPermissionResponse

global inherited sharing abstract class AbstractCalculateTaxPermissionResponse

Abstract base class for responses containing the results of checking permission to calculate tax.

Properties

Name Type Description
Errors List<String> The errors related to insufficient permissions.

fferpcore.BillingDocumentService.CalculateTaxPermissionResponse

global inherited sharing class CalculateTaxPermissionResponse extends AbstractCalculateTaxPermissionResponse

Response containing the results of checking permission to calculate tax.

This class extends fferpcore.BillingDocumentService.AbstractCalculateTaxPermissionResponse

fferpcore.BillingDocumentService.CalculateTaxAsyncPermissionResponse

global inherited sharing class CalculateTaxAsyncPermissionResponse extends AbstractCalculateTaxPermissionResponse

Response containing the results of checking permission to calculate tax asynchronously.

This class extends fferpcore.BillingDocumentService.AbstractCalculateTaxPermissionResponse

fferpcore.BillingDocumentService.CalculateTaxValidationDocument

global inherited sharing class CalculateTaxValidationDocument

Represents a billing document to be validated for calculating tax. You should set all fields from the document to be validated. This is used by BillingDocumentsService.validateForCalculateTax to validate a document for tax calculation.

Properties

Name Type Description
AccountId Id The ID of the account which the document charges or credits.
CompanyId Id The ID of the company to which the document belongs.
CompanyTaxInformationId Id The ID of the company tax information record assigned to the company to which the document belongs.
DocumentDate Date The date of taxation.
Status String The document status.

Methods

CalculateTaxValidationDocument

global CalculateTaxValidationDocument()

Constructs a new empty document.

fferpcore.BillingDocumentService.CalculateTaxValidationResponse

global inherited sharing class CalculateTaxValidationResponse

Response containing the results of validation performed on a billing document for calculating tax. If there are no errors then the document can have tax calculated for it.

Properties

Name Type Description
Errors List<String> Read only. The errors associated with the validated document. Resolve any errors before calculating tax for the document.

fferpcore.BillingDocumentService.AbstractCalculateTaxRequest

global inherited sharing abstract class AbstractCalculateTaxRequest

Abstract base class for requests to calculate tax.

Properties

Name Type Description
BillingDocumentIds Set<Id> The IDs of the billing documents for which to calculate tax.

fferpcore.BillingDocumentService.CalculateTaxRequest

global inherited sharing class CalculateTaxRequest extends AbstractCalculateTaxRequest

A request to calculate tax synchronously for selected billing documents.

This class extends fferpcore.BillingDocumentService.AbstractCalculateTaxRequest

Methods

CalculateTaxRequest

global CalculateTaxRequest()

Constructs a new empty request and sets BillingDocumentIds to be a new Set<Id>.

fferpcore.BillingDocumentService.CalculateTaxResponse

global inherited sharing class CalculateTaxResponse

The results of calculating tax. There is one result for each document processed, successful or not.

Properties

Name Type Description
Results List<fferpcore.BillingDocumentService.CalculateTaxResult> Read only. The results of calculating tax for each billing document.

fferpcore.BillingDocumentService.CalculateTaxResult

global inherited sharing class CalculateTaxResult

The results of calculating tax on a single billing document. A billing document was processed successfully if no errors occur.

Properties

Name Type Description
DocumentId Id Read only. The ID of the billing document that was processed.
Errors List<String> Read only. The error messages associated with the billing document. Is empty if the billing document was processed successfully.

fferpcore.BillingDocumentService.GetTaxRequest

global inherited sharing class GetTaxRequest

Contains the parameters required for calculating tax on multiple unsaved documents.

Properties

Name Type Description
Documents List<fferpcore.BillingDocumentService.TaxDocument> Required. The list of documents that are to have tax calculated.

Methods

GetTaxRequest

global GetTaxRequest()

Constructs a new empty request and sets Documents to be a new List<TaxDocument>.

fferpcore.BillingDocumentService.TaxDocument

global inherited sharing class TaxDocument

An unsaved document for which you can calculate tax.

Properties

Name Type Description
Account fferpcore.BillingDocumentService.TaxAccount Required. The Account which the document charges or credits.
Company fferpcore.BillingDocumentService.TaxCompany Required. The Company to which the document belongs.
Lines List<fferpcore.BillingDocumentService.TaxDocumentLine> Required. The lines of the billing document for which tax will be calculated.
TaxType String The tax rules to apply to this document. The system can calculate tax using "VAT", "GST", or "SUT" rules. If none of the above, tax fields of the returned document are cleared.
DocumentDate Date Required. The date of taxation.

Methods

TaxDocument

global TaxDocument()

Constructs a new empty document and sets Lines to be a new List<TaxDocumentLine>.

fferpcore.BillingDocumentService.TaxAccount

global inherited sharing class TaxAccount

An account that can be charged or credited by a TaxDocument. Used for determining the tax to be applied to the document. You should set all fields from the account for the document to have tax calculated.

Properties

Name Type Description
VatStatus fferpcore.AccountVatStatus.Status The VAT/GST tax status for this account.
VatRegistrationNumber String Identifying number used for VAT purposes.
TaxCountryCode String Code for the European Union country in which this account operates. This should be a member of the Tax Country Code global value set.
OutputTaxCodeId Id The ID for the fferpcore__TaxCode__c to be used when calculating tax in a VAT or GST company.
SalesTaxStatus fferpcore.AccountSalesTaxStatus.Status The SUT tax status for this account.
TaxCode1Id Id The first fferpcore__TaxCode__c for this account, to be used for SUT tax calculation.
TaxCode2Id Id The second fferpcore__TaxCode__c for this account, to be used for SUT tax calculation.
TaxCode3Id Id The third fferpcore__TaxCode__c for this account, to be used for SUT tax calculation.

Methods

TaxAccount

global TaxAccount()

Constructs a new empty TaxAccount.

fferpcore.BillingDocumentService.TaxCompany

global inherited sharing class TaxCompany

A company which owns TaxDocuments. Used for determining the tax to be applied to the document. You should set all fields from the company for the document to have tax calculated.

Properties

Name Type Description
VatGstGroup Boolean Required. Indicates whether this company is part of a VAT/GST group.
VatRegistrationNumber String Identifying number used for VAT purposes.
TaxCountryCode String Code for the European Union country in which the company operates. This should be a member of the Tax Country Code global value set.
OutputTaxCodeId Id The ID for the fferpcore__TaxCode__c to be used when calculating tax in a VAT or GST company.

Methods

TaxCompany

global TaxCompany()

Constructs a new empty TaxCompany.

fferpcore.BillingDocumentService.TaxDocumentLine

global inherited sharing class TaxDocumentLine

A line on a document for which tax can be calculated.

Properties

Name Type Description
LineNo String An identifier for the line on the document. This identifies the response for this line.
Product fferpcore.BillingDocumentService.TaxProduct Required. The product for this document line.
NetValue Decimal Required. The net value of this line.
TaxValue1DecimalPrecision Integer Required. Specifies the decimal precision of the first tax value response.
TaxValue2DecimalPrecision Integer Required. Specifies the decimal precision of the second tax value response.
TaxValue3DecimalPrecision Integer Required. Specifies the decimal precision of the third tax value response.

Methods

TaxDocumentLine

global TaxDocumentLine()

Constructs a new empty TaxDocumentLine.

fferpcore.BillingDocumentService.TaxProduct

global inherited sharing class TaxProduct

A product on a document line for which tax can be calculated. You should set all fields from the product for the billing document line to have tax calculated.

Properties

Name Type Description
OutputTaxCodeId Id The ID for the fferpcore__TaxCode__c to be used when calculating tax in a VAT or GST company.
SalesTaxStatus fferpcore.ProductSalesTaxStatus.Status The tax status for this product for SUT companies.

Methods

TaxProduct

global TaxProduct()

Constructs a new empty TaxProduct.

fferpcore.BillingDocumentService.GetTaxResponse

global inherited sharing class GetTaxResponse

The results of calculating tax on unsaved documents.

Properties

Name Type Description
Results List<fferpcore.BillingDocumentService.GetTaxResult> Read only. A list of tax calculation results for each document that had tax calculated. The results for each document are returned in the same order that they were supplied in the GetTaxRequest.

fferpcore.BillingDocumentService.GetTaxResult

global inherited sharing class GetTaxResult

A result from the tax calculation process for an unsaved document. This contains either the taxed lines or the errors encountered calculating tax for this document. The tax calculation was successful only if there are no errors.

Properties

Name Type Description
Lines List<fferpcore.BillingDocumentService.GetTaxLineResult> Read only. A list of tax results for each line in the document. If tax calculation fails, no lines are returned.
Errors List<String> Read only. A list of errors generated while attempting to calculate tax for each of the document lines.

fferpcore.BillingDocumentService.GetTaxLineResult

global inherited sharing class GetTaxLineResult

Contains the calculated tax codes, rates, and values for a document line. Some values may be null depending on the configuration of your tax request.

Properties

Name Type Description
LineNo String Read only. An identifer for the line on the document. This corresponds to the identifier specified in the request.
TaxCode1Id Id Read only. The ID for the first fferpcore__TaxCode__c derived for the document line.
TaxRate1 Decimal Read only. The first tax rate that was calculated for the document line.
TaxValue1 Decimal Read only. The first tax value that was calculated for the document line.
TaxCode2Id Id Read only. The ID for the second fferpcore__TaxCode__c derived for the document line.
TaxRate2 Decimal Read only. The second tax rate that was calculated for the document line.
TaxValue2 Decimal Read only. The second tax value that was calculated for the document line.
TaxCode3Id Id Read only. The ID for the third fferpcore__TaxCode__c derived for the document line.
TaxRate3 Decimal Read only. The third tax rate that was calculated for the document line.
TaxValue3 Decimal Read only. The third tax value that was calculated for the document line.

fferpcore.BillingDocumentService.CalculateTaxAsyncRequest

global inherited sharing class CalculateTaxAsyncRequest extends AbstractCalculateTaxRequest

A request to calculate tax asynchronously for selected billing documents.

This class extends fferpcore.BillingDocumentService.AbstractCalculateTaxRequest

Methods

CalculateTaxAsyncRequest

global CalculateTaxAsyncRequest()

Constructs a new empty request and sets BillingDocumentIds to be a new Set<Id>.

fferpcore.BillingDocumentService.CalculateTaxAsyncResponse

global inherited sharing class CalculateTaxAsyncResponse

The results of creating an asynchronous tax calculation job.

Properties

Name Type Description
BatchControlId Id Read only. The ID of the fferpcore__ScheduledJobRun__c record associated with the tax calculation job. The job is finished when the field fferpcore__ScheduledJobRun__c.fferpcore__Status__c on this record is not "Processing".

fferpcore.BillingDocumentService.DeriveDueDateRequest

global inherited sharing class DeriveDueDateRequest

A request to derive the document due date of a billing document.

Properties

Name Type Description
DocumentDate Date Required. The document date of the billing document.
AccountId Id The ID of the account associated with the billing document.
CompanyId Id The ID of the company associated with the billing document.
DocumentType fferpcore.BillingDocumentService.Type The type of billing document.

Methods

DeriveDueDateRequest

global DeriveDueDateRequest()

fferpcore.BillingDocumentService.DeriveDueDateResponse

global inherited sharing class DeriveDueDateResponse

The result of deriving the due date of a billing document.

Properties

Name Type Description
DueDate Date Read only. The due date of the billing document.
IsSuccessful Boolean Read only. True when the due date was derived successfully.

Methods

DeriveDueDateResponse

global DeriveDueDateResponse()

© Copyright 2009–2022 FinancialForce.com, inc. Confidential – all rights reserved. Various trademarks held by their respective owners.