Overview:

The Zumzum Financials Sales Invoice API service provides the following capabilities

• Create a draft Sales Invoice with Sales Invoice Line Items
• Edit a draft Sales Invoice with Sales Invoice Line Items
• Asynchronously Post Sales Invoices with Sales Invoice Line Items to the general ledger
• Synchronously Post a Sales Invoice with Sales Invoice Line Items to the general ledger

Sales Invoice with Sales Invoice Line Items Description

The Sales Invoice object is an ideal integration point to create transactions from Zumzum Financials from Salesforce.  You should be aware of the following:

• Sales Invoices are created as “Draft” and will then need to be submitted via the asynchronous PostSalesInvoice method or synchronous PostInvoices method.
• Sales Invoices and Sales Credits are created in the Sales Invoice Object by setting the “Type” field on the record to be created.
• All Sales Invoice Line Item values will need to be provided as a positive number as negative amounts are not supported.  If you wish to insert a negative transaction to an Account, then please insert the records with the”Type” set as Sales Credit and positive numbers for the Sales Credit Line Items.
• The Sales Invoice will be automatically updated to Paid Y or N if the Total Paid Amount is equal to the Total Gross of the Sales Invoice/Credit.
• The Total Paid Amount is calculated from all the customer receipts or credit allocations to the Sales Invoice/Credit Line Items.

The SalesInvoicePost Service function will accept the list of ‘SalesInvoiceWrapper’ as an input parameter.  Below are the required fields when creating a draft Sales Invoice with Sales Invoice Line Items.

SalesInvoiceWrapper API Fields

The CreateSalesInvoice function will accept the list of ‘SalesInvoiceLineWrapper’ as an input parameter.  Below are the required fields when creating a Sales Invoice Line Item.

SalesInvoiceLineItemWrapper API Fields

The SalesInvoicePost Service function will accept the list of ‘APICustomFieldWrapper’ as an input parameter.  Once you have created your custom fields on this object, you would be able to pass those as variables to the API for creating and updating records.  Below are the required fields when creating adding custom fields to your API call.

APICustomFieldWrapper API Fields

Create a Draft Sales Invoice – CreateSalesInvoices Method

Below is information related on how to create a draft Sales Invoice with the Sales Invoice API service using Apex code.  Zumzum Financials includes a global class called SalesInvoicePostService which you may call from your own Apex code. The CreateSalesInvoices method is used to insert Sales Invoices with Sales Invoice Line Items and returns a list of draft sales invoices created.

Sample Code: Create A Draft Sales Invoice

This example is provided to help you begin creating your own custom code.  The code will create a Sales Invoice with a single Sales Invoice Line Item and return a list of the Sales Invoice created. The following steps will be performed:

1. Prepare the list collection “List<SalesInvoiceWrapper>” to supply as an input for the CreateSalesInvoice function.
2. Prepare the list collection “List<SalesInvoiceLineWrapper>” to insert Sales Invoice Line Items with their required fields.
3. Create the Sales Invoice and Sales Invoice Line Item Records
4. Return a list of the draft Sales Invoices created with Sales_Invoice__c

Sample Code :

/**************Start Create A Draft Sales Invoice Sample Script*****************************/ 

/* Prepare the list of Sales Invoice records to be created as draft Sales Invoices */ 

SalesInvoicePostService objInvoiceHandler = new SalesInvoicePostService(); 

List<SalesInvoicePostService.SalesInvoiceWrapper > lstNewSalesInvoiceData = new List<SalesInvoicePostService.SalesInvoiceWrapper >(); 

/* Gather the variables to be used for the required fields of the Sales Invoice header */ 

SalesInvoicePostService.SalesInvoiceWrapper SalesInvoice = new SalesInvoicePostService.SalesInvoiceWrapper( ); 

SalesInvoice.Customer = '001b000003n1k1I'; 

SalesInvoice.InvoiceDate = date.today(); 

SalesInvoice.TransactionCurrency = 'a0vb0000005EIAf'; 

/* Create the API Custom Field wrapper to contain the custom fields for the Sales Invoice */ 

salesInvoice.WrapperAPICustomFields = new List<APICustomFieldWrapper>(); 

salesInvoice.WrapperAPICustomFields.add(new APICustomFieldWrapper('Zumzum__Sales_Invoice__c','Zumzum__Event__c','a1S7E00000125zPUAQ')); 

/* Gather the required fields for the list of Sales Invoice Line Item records to be added to the draft Sales Invoice */ 

SalesInvoicePostService.SalesInvoiceLineWrapper SalesInvoiceLine = new SalesInvoicePostService.SalesInvoiceLineWrapper(); 

SalesInvoiceLine.Product = '01tb0000005MawT'; 

SalesInvoiceLine.NominalAccount = '02tb0000005MawT'; 

SalesInvoiceLine.Quantity = 2; 

SalesInvoiceLine.TaxRate = 'a03b000000CoYXo'; 

SalesInvoiceLine.ForeignNetAmount = 150; 

SalesInvoiceLine.Dimension1 = a03b000011CoYXo; 

/* Create the API Custom Field wrapper to contain the custom fields for the Sales Invoice Line Item*/ 

salesInvoiceLine.WrapperAPICustomFields = new List<APICustomFieldWrapper>(); 

salesInvoiceLine.WrapperAPICustomFields.add(new APICustomFieldWrapper('Zumzum__Sales_Invoice_Line_Item__c','Zumzum__Event__c','a1S7E00000125zPUAQ')); 

SalesInvoice.LineItems = new List<SalesInvoicePostService.SalesInvoiceLineWrapper>(); 

SalesInvoice.LineItems.add(SalesInvoiceLine); 

/* Create the draft Sales Invoice and Sales Invoice Line Item in the system */ 

lstNewSalesInvoiceData.add(SalesInvoice); 

/* Return a list of the draft Sales Invoice record created in the system */ 

List<Sales_Invoice__c> lstNewSalesInvoices = objInvoiceHandler.CreateSalesInvoices(lstNewSalesInvoiceData); 

/* System Debug information */ 

system.debug('lstNewSalesInvoices::' + lstNewSalesInvoices); 

/**************End Create A Draft Sales Invoice Sample Script*****************************/

Edit A Draft Sales Invoice – UpdateSalesInvoices Method

Below is information related on how to edit a draft Sales Invoice with the Sales API service using Apex code.   The UpdateSalesInvoices method is used to edit Sales Invoices and Sales Invoice  Line Items and returns a list of draft Sales Invoices edited.

Sample Code: Update A Draft Sales Invoice

This example code us used to edit an existing Sales Invoice record, to help you begin creating your own custom code.  The code will edit the Sales Invoice Item of an existing Sales Invoice. The following steps will be performed:

1. Prepare the list collection “List<SalesInvoiceWrapper>” to include the “Sales InvoiceID” to supply as an input for the UpdateSalesInvoices function.
2. Prepare the list collection “List<SalesInvoiceLineWrapper>” to edit Sales Invoice Line Items with their changed fields.
3. Edit the Sales Invoice Line Item records
4. Return a list of the draft Sales Invoices edited with the list “Sales_Invoice__c”

Sample Code :

/**************Start Update Sales Invoice Script*****************************/

/* Prepare the list of Sales Invoice records to be edited */ 

SalesInvoicePostService objInvoiceHandler = new SalesInvoicePostService(); 

/* Create the Sales Invoice Wrapper to provide the ID of the draft Sales Invoices */ 

List<SalesInvoicePostService.SalesInvoiceWrapper > lstInvoiceData = new List<SalesInvoicePostService.SalesInvoiceWrapper >(); 

SalesInvoicePostService.SalesInvoiceWrapper salesInvoice = new SalesInvoicePostService.SalesInvoiceWrapper( ); 

/* Provide the list of variables for the Sales Invoice to be edited including the ID */ 

salesInvoice.SalesInvoiceId = 'a167E000001U9d6QAC'; 

SalesInvoice.Comments = 'Updated via API script'; 

/* Create the API Custom Field wrapper to contain the custom fields for the Sales Invoice */ 

salesInvoice.WrapperAPICustomFields = new List<APICustomFieldWrapper>(); 

salesInvoice.WrapperAPICustomFields.add(new APICustomFieldWrapper('Zumzum__Sales_Invoice__c','Zumzum__Event__c','a1S7E00000125zPUAQ')); 

/* Create the Sales Invoice Line Wrapper to provide the ID of the  Sales Invoice Line Item */ 

salesInvoice.LineItems = new List<SalesInvoicePostService.SalesInvoiceLineWrapper>(); 

SalesInvoicePostService.SalesInvoiceLineWrapper salesInvoiceLine; 

/* Details of the first line item in to be updated */ 

salesInvoiceLine = new SalesInvoicePostService.SalesInvoiceLineWrapper(); 

salesInvoiceLine.SalesInvoiceLineId = 'a127E0000031hSaQAI'; 

salesInvoiceLine.Quantity = 2; 

salesInvoiceLine.Dimension1 = 'null'; 

salesInvoiceLine.Dimension3 = 'a0P26000004bbGA'; 

/* Create the API Custom Field wrapper to contain the custom fields for the Sales Invoice Line Item*/ 

salesInvoiceLine.WrapperAPICustomFields = new List<APICustomFieldWrapper>(); 

salesInvoiceLine.WrapperAPICustomFields.add(new APICustomFieldWrapper('Zumzum__Sales_Invoice_Line_Item__c','Zumzum__Event__c','a1S7E00000125zPUAQ')); 

salesInvoice.LineItems.add(salesInvoiceLine); 

lstInvoiceData.add(salesInvoice); 

/* Execute the method to update the draft Sales Invoices */ 

SalesInvoicePostService.Response objResponse = objInvoiceHandler.UpdateSalesInvoices(lstInvoiceData); 

/* System Debug Information with success or error */

system.debug('Message>>' + objResponse.ResponseMessage); 

/* Response from the system of the updated Sales Invoice IDs */ 

system.debug('SalesInvoices>>' + objResponse.salesInvoices); 

/*********************END Update Sales Invoice Script **************************************/

Asynchronously Post Sales Invoices – PostSalesInvoices Method

Below is information related on how to Post draft Sales Invoices with the Sales Invoice API service using Apex code.  Zumzum Financials includes a global class called SalesInvoicePostService which you may call from your own Apex code. The PostSalesInvoices method is used to change the status of a draft Sales Invoice and create general ledger records to update your financial reports in Zumzum Financials.  This method will only ever run in batch mode to minimise the risk of running into Salesforce governor limits.   See the information below related to the custom metadata type to configure the size of the batch in your org.

Sample Code: Asynchronously Post A Sales Invoice

Please follow the below steps to post multiple invoices.

1. Prepare the list collection ‘List<Sales_Invoice__c>’ to supply as an input for the PostSalesInvoice function. For this, you can execute a SOQL command to fetch all the sales invoices which should be posted or you can use the output of the function ‘CreateSalesinvoices’ as explained above in the documentation.
2. Do not execute this inside of a batch processing routine, since this function will take care of the batch processing internally.

This example is provided to help you begin creating your own custom code.  The code will post a Sales Invoice to the general ledger.

Sample Code:

/*********************Start Sample Post Sales Invoice Script **************************************/ 

/* Query the system to gather the list of draft Sales Invoices with a query */ 

List<Sales_Invoice__c> lstDraftSalesInvoices = [Select id from Sales_Invoice__c where Status__c = 'Draft' order by createddate desc limit 20];

SalesInvoicePostService objInvoiceHandler = new SalesInvoicePostService(); 

/* Pass the list of Sales Invoices to be posted to the PostSalesInvoice method */

objInvoiceHandler.PostSalesInvoices(lstDraftSalesInvoices); 

/*********************End Sample Post Sales Invoice Script **************************************/

Synchronously Post Sales Invoices – PostInvoices Method

The PostInvoices method provides a boolean parameter “executeInBatchProcessing” that when set to false, will post the sales invoices in synchronous mode. This would be used when you wish to gain a near real time response from the Sales Invoice API rather than wait for a batch Apex job to complete.   The PostInvoices method will also post in batch mode, as the default setting for “executeInBatchProcessing” is true.  The PostInvoices method is used to change the status of a draft Sales Invoice and create general ledger records to update your financial reports in Zumzum Financials.

Sample Code: Synchronously Post A Sales Invoice

Please follow the below steps to synchronously/asynchronously post invoices.

1. Prepare the list collection ‘List<Sales_Invoice__c>’ to supply as an input for the PostInvoices method. For this, you can execute a SOQL command to fetch all the sales invoices which should be posted or you can use the output of the function ‘CreateSalesinvoices’ as explained above in the documentation.
2. Call the PostInvoices method with the parameter for “executeInBatchProcessing” set as false to post in synchronous mode, without using batch apex.

This example is provided to help you begin creating your own custom code.  The code will post a Sales Invoice to the general ledger.

Sample Code:

/**************Start Sample Synchronously Post Sales Invoice Script*****************************/

// Create a new instance of the Sales Invoice Post Service object
SalesInvoicePostService objInvoiceHandler = new SalesInvoicePostService();

// Create a Set of Sales Invoice IDs to pass to the PostInvoices method
set<Id> invoiceIds = new Set<Id>{'a168E000002rPOGQA2','a168E000002rPOLQA2'};

// Call the PostInvoices method with the executeInBatchProcessing set as false
SalesInvoicePostService.Response objResponse = objInvoiceHandler.PostInvoices(invoiceIds,false);

// Receive the response from the PostInvoices in the objResponse as success/failure. 
system.debug('Response--> ' + objResponse);

/**************End Sample Synchronously Post Sales Invoice Script*****************************/

Custom Metadata Type – Batch Settings

By default, the SalesInvoicePostService will process Sales Invoices contained in the list of Sales Invoice IDs in batches of 5.

You may change this setting to optimise the performance in your own org to accommodate any custom workflows and code you may have running, to minimize the impact on your orgs’ Salesforce governor limits.

To configure the Custom Metadata Setting “Batch Settings” please follow these steps:

1. Go to Setup in Salesforce
2. Search for Custom Metadata Settings 
3. Find the Batch Job Settings metadata record
4. Click the ManageRecords link in the Action column
5. Scroll to the item named Post Sales Invoice and click the lael to view the record
6. Select Edit to modify the record
7. Enter a value in Batch Size, e.g. 5
8. Select Save.

Below are a list of error codes that are returned by the Sales Invoice Post Service.

Supported Error Codes – Sales Invoice Service (API)