Sales Invoice API

Zumzum Financials Knowledge Base

    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.

    in Sales Invoice API Tags: APEXAPIInvoiceSales Invoice

    Related Articles