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

Object Name	Field Name	API Name	Data Type	Required
SalesInvoiceWrapper	APICustomFieldWrapper	APICustomFieldWrapper	List (objectAPIName, fieldAPIName, fieldValue)	No
SalesInvoiceWrapper	Case	CaseID	Lookup (Case)	No
SalesInvoiceWrapper	Comments	Comments	String (255)	No
SalesInvoiceWrapper	Customer Account	Customer	Lookup (Account)	Yes
SalesInvoiceWrapper	Invoice Date	InvoiceDate	Date	Yes
SalesInvoiceWrapper	Opportunity	Opportunity	Lookup (Opportunity)	No
SalesInvoiceWrapper	Sales Invoice ID	SalesInvoiceId	ID	No
SalesInvoiceWrapper	Sales Invoice Line Item	SalesInvoiceLineItemWrapper	List = Zumzum_Sales_Invoice_Line_Item_c	Yes
SalesInvoiceWrapper	Transaction Currency	TransactionCurrency	Lookup (Zumzum_Currency__c)	Yes

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

Object Name	Field Name	API Name	Data Type	Required
SalesInvoiceLineWrapper	APICustomFieldWrapper	APICustomFieldWrapper	List (objectAPIName, fieldAPIName, fieldValue)	No
SalesInvoiceLineWrapper	Case	CaseID	Lookup (Case)	No
SalesInvoiceLineWrapper	Delete Line	DeleteLine	Boolean	No
SalesInvoiceLineWrapper	Dimension 1	Dimension1	Lookup (Zumzum__Dimension__c)	No
SalesInvoiceLineWrapper	Dimension 2	Dimension2	Lookup (Zumzum__Dimension__c)	No
SalesInvoiceLineWrapper	Dimension 3	Dimension3	Lookup (Zumzum__Dimension__c)	No
SalesInvoiceLineWrapper	Dimension 4	Dimension4	Lookup (Zumzum__Dimension__c)	No
SalesInvoiceLineWrapper	Dimension 5	Dimension5	Lookup (Zumzum__Dimension__c)	No
SalesInvoiceLineWrapper	Dimension 6	Dimension6	Lookup (Zumzum__Dimension__c)	No
SalesInvoiceLineWrapper	Foreign Net Amount	ForeignNetAmount	Number (16,2)	Yes
SalesInvoiceLineWrapper	Nominal Account	NominalAccount	Lookup (Zumzum__Nominal_Account__c)	Yes
SalesInvoiceLineWrapper	Opportunity Line Items	OpportunityLineId	Lookup (OpportunityLineItem)	No
SalesInvoiceLineWrapper	Product	Product	Lookup (Product)	Yes
SalesInvoiceLineWrapper	Quantity	Quantity	Number (15,3)	Yes
SalesInvoiceLineWrapper	Sales Invoice Line ID	SalesInvoiceLineId	ID Field	No
SalesInvoiceLineWrapper	Tax Rate	TaxRate	Lookup (Zumzum_Tax_Rate__c	Yes

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

Object Name	Field Name	API Name	Data Type	Required
APICustomFieldWrapper	Object API Name	objectAPIName	String	Yes
APICustomFieldWrapper	Field API Name	fieldAPIName	String	Yes
APICustomFieldWrapper	Field Value	fieldValue	String	Yes

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.

Global Class Name	Method	Input	Output
SalesInvoicePostService	CreateSalesInvoices	List “SalesInvoiceWrapper”	List of type object, e.g. “Sales_Invoice__c”

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.

Global Class Name	Method	Input	Output
SalesInvoiceService	UpdateSalesInvoices	List “SalesInvoiceWrapper”	List “Sales_Invoice__c”

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.

Global Class Name	Method	Input	Output
SalesInvoicePostService	PostSalesInvoices	List “Sales_Invoice__c”	void

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.

Global Class Name	Method	Input	Output
SalesInvoicePostService	PostInvoices	List “Sales_Invoice__c”	objResponse (Success/Error)

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)

Error Message	Reason	Resolution
The account is not a valid customer account to create a Sales Invoice.	Creating a Sales Invoice for an Account which is not set to Zumzum Accounting Customer Field or Zumzum Accounting Customer Value in the Zumzum custom Account metadata setting	Ensure your Account Type field is set to “Customer” If you have edited the Custom Metadata record in order to set a custom “Zumzum Accounting Customer” field or values, this error is informing you that the account in the script does not have the correct value in the correct field.
FIELD_FILTER_VALIDATION_EXCEPTION, The product you have selected is not "active" in the system. Please contact your System Administrator: [Zumzum__Product__c]”	Creating a Sales Invoice Line item for a product which is inactive	Edit your product and ensure “Active” is set to TRUE (checked)
FIELD_CUSTOM_VALIDATION_EXCEPTION, Please make sure that the Dimension is "Active" and "Type" Dimension 1.: [Zumzum__Dimension_1__c]”	Creating a Sales Invoice Line item with a dimension which is inactive or set for a type of different dimension (e.g. entering Dimension 2 into Dimension 1 field)	Check that your Dimension is “Active” and/or that you are passing the correct Dimension “Type” to the correct Dimension field.
‘Insufficient access, Please contact your administrator to check your user profile.	Editing or Creating a Sales Invoice without the correct permissions associated with the Salesforce user account.	Add Edit acccess for Sales Invoice and Sales Invoice Line Item or assign new permission set.
Please provide the Sales Invoice Id (SalesInvoiceID) variable to edit your Sales Invoice	Editing a Sales Invoice without providing Sales Invoice ID.	Add “salesInvoice.SalesInvoiceId = ‘a167E000001OpoxQAC’;” to the running script and replace the ID with the Sales Invoice you wish to edit.
‘Sales Invoice Status is : Posted This Sales Invoice is locked as it is “Posted” to the ledger.’	Editing a Sales Invoice that is Posted	Raise a Creit Note against Inoice and then create a new Invoice.
Please provide a valid “Invoice Date”.	Creating a Sales Invoice without providing Invoice Date	Add “SalesInvoice.InvoiceDate = ” to the running script adding the required date.
‘Please provide a valid Customer Name (Customer)	Creating a Sales Invoice without Customer Account	Add “SalesInvoice.Customer = ” to the running script and add the ID of the Customer Account.
‘No Line Item in Sales Invoice, Please Provide A List of Sales Invoice Line Items (SalesInvoiceLineWrapper) Variable	Editing a Sales Invoice without having any Sales Invoice Line Items refrenced.	Add “SalesInvoiceLine.SalesInvoiceLineId.SalesInvoiceLineId = ” into the running script Add any relevavant fields wrappers, into the running script, below this to apply to the line item.
Please provide a valid Tax Rate ID (RaxRate) variable	Creating or Editing a Sales Invoice Line Item without providing	Add “salesInvoiceLine. TaxRate = ” to the running script. And add the ID of the tax rate you want to be applied to the line item.
Please provide a valid Quantity (Quantity) variable	Creating or Editing a Sales Invoice Line Item with a Foreigin Amount less than 1.	“salesInvoiceLine.Quantity = ” to the running script and provide a value higer than 0.
Please enter a Starting Document Number & Current Document Number for Sales Invoices in General Setup>SI record.	Missing a Sales Invoice Starting Document Number or a Current Document Number.	Visit the Zumzum Setup > Document Numbers > SI and ensure the values for Starting Document Number and Current Document Number are entered correctly to set your next Sales Invoice Number.
Insufficient access, Please contact your administrator to request permissions to update the Zumzum General Setup object.	User does not have the correct permissions to create a Sales Invoice	Assign the user a Zumzum Permission set or a permission to edit the Zumzum General Setup object.