Purchase Invoice API

Zumzum Financials Knowledge Base

    Overview:

    The Zumzum Financials Purchase Invoice API service provides the following capabilities

    • Create a Purchase Invoice with a Purchase Invoice Line Item
    • Edit a Purchase Invoice with a Purchase Invoice Line Item
    • Post a Purchase Invoice
    • Batch Post Purchase Invoices

    Purchase Invoice With Purchase Invoice Line Description

    Purchase Invoice records offer an ideal opportunity to create transactions to the Zumzum Financials general ledger.  You should be aware of the following:

    • Purchase Invoices are created with a default status of “Draft” and need to be submitted to the PostPurchaseInvoice method.
    • Only submit a list of draft Purchase Invoices to the Purchase Invoice Service in order to post them to the general ledger.
    • Only one Purchase Invoice record may be submitted to post at any one time.
    • Purchase Invoices and Purchase Credits are created in the Purchase Invoice Object by setting the “Type” field on the record to be created.
    • All Purchase Invoice Line Item values will need to be provided as a positive number as negative amounts are not supported.
    • The Purchase Invoice will be automatically updated to Paid Y or N if the total Paid Amount is equal to the Total Gross  of the Purchase Invoice.  The Total Paid Amount is calculated from all the supplier payments or purchase credit allocations to the Purchase Invoice Line Items.
    • Remove any field values by sending the text value “null” to any global variable, excluding required fields or date fields.
    • Create Purchase Invoices and Purchase Invoice line items including your own custom fields using the global list APICustomFieldWrapper

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

    PurchaseInvoiceWrapper API Fields

    Object Name Field Name API Name Data Type Required
    PurchaseInvoiceWrapper APICustomFieldWrapper APICustomFieldWrapper List (objectAPIName, fieldAPIName, fieldValue) No
    PurchaseInvoiceWrapper Contact Contact Lookup (Account) No
    PurchaseInvoiceWrapper External Reference ExternalReference String (255) No
    PurchaseInvoiceWrapper Invoice Date InvoiceDate Date Yes
    PurchaseInvoiceWrapper Invoice Due Date InvoiceDueDate Date No
    PurchaseInvoiceWrapper Purchase Invoice ID PurchaseInvoiceID Lookup (Zumzum_Purchase_Invoice__c) No
    PurchaseInvoiceWrapper Purchase Invoice Line Item PurchaseInvoiceLineItemWrapper List = Zumzum_Purchase_Invoice_Line_Item_c Yes
    PurchaseInvoiceWrapper Supplier Account SupplierAccount Lookup (Account) Yes
    PurchaseInvoiceWrapper Supplier Name SupplierName (DEPRECATED Lookup (Account) Yes
    PurchaseInvoiceWrapper Transaction Currency TransactionCurrency Lookup (Zumzum_Currency__c) Yes
    PurchaseInvoiceWrapper Type PurchaseInvoiceType String (255) No

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

    PurchaseInvoiceLineWrapper API Fields

    Object Name Field Name API Name Data Type Required
    PurchaseInvoiceLineWrapper APICustomFieldWrapper APICustomFieldWrapper List (objectAPIName, fieldAPIName, fieldValue) No
    PurchaseInvoiceLineWrapper N/A DeleteLine Boolean No
    PurchaseInvoiceLineWrapper Dimension 1 Dimension1 Lookup (Zumzum__Dimension__c) No
    PurchaseInvoiceLineWrapper Dimension 2 Dimension2 Lookup (Zumzum__Dimension__c) No
    PurchaseInvoiceLineWrapper Dimension 3 Dimension3 Lookup (Zumzum__Dimension__c) No
    PurchaseInvoiceLineWrapper Dimension 4 Dimension4 Lookup (Zumzum__Dimension__c) No
    PurchaseInvoiceLineWrapper Dimension 5 Dimension5 Lookup (Zumzum__Dimension__c) No
    PurchaseInvoiceLineWrapper Dimension 6 Dimension6 Lookup (Zumzum__Dimension__c) No
    PurchaseInvoiceLineWrapper Foreign Net Amount ForeignNetAmount Number (16,2) Yes
    PurchaseInvoiceLineWrapper Narrative Narrative String (255) No
    PurchaseInvoiceLineWrapper Nominal Account NominalAccount Lookup (Zumzum__Nominal_Account__c) Yes
    PurchaseInvoiceLineWrapper Purchase Invoice Line Id PurchaseInvoiceLineId ID No
    PurchaseInvoiceLineWrapper Quantity Quantity Number (15,3) Yes
    PurchaseInvoiceLineWrapper Tax Rate TaxRate Lookup (Zumzum_Tax_Rate__c Yes

    The PurchaseInvoicePost Service 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 Purchase Invoice – CreatePurchaseInvoices Method

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

    Global Class Name Method Input Output
    PurchaseInvoiceService CreatePurchaseInvoices List “PurchaseInvoiceWrapper” List of type object, e.g. “Purchase_Invoice__c”

    Sample Code: Create Purchase Invoice

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

    1. Prepare the list collection “List<PurchaseInvoiceWrapper>” to supply as an input for the CreatePurchaseInvoice function.
    2. Prepare the list collection “List<PurchaseInvoiceLineWrapper>” to insert Purchase Invoice Line Items with their required fields.
    3. Create the Purchase Invoice and Purchase Invoice Line Item Records
    4. Return a list of the draft Purchase Invoices created with Purchase_Invoice__c

    Sample Code :

    zumzum.PurchaseInvoiceService objInvoiceHandler = new zumzum.PurchaseInvoiceService();
    
    List<zumzum.PurchaseInvoiceService.PurchaseInvoiceWrapper > lstInvoiceData = new List<zumzum.PurchaseInvoiceService.PurchaseInvoiceWrapper >();
    
    zumzum.PurchaseInvoiceService.PurchaseInvoiceWrapper purchaseInvoice = new zumzum.PurchaseInvoiceService.PurchaseInvoiceWrapper( );
    
    purchaseInvoice.SupplierAccount = '0013H000003sPCoQAM'; //provide the account id here.
    
    purchaseInvoice.InvoiceDate = date.today();
    
    //purchaseInvoice.TransactionCurrency = 'a1T3H0000004Cc8UAE'; //provide the transaction currency id here
    
    zumzum.PurchaseInvoiceService.PurchaseInvoiceLineWrapper purchaseInvoiceLine = new zumzum.PurchaseInvoiceService.PurchaseInvoiceLineWrapper();
    
    purchaseInvoiceLine.NominalAccount = 'a0i3H00000000NZQAY';
    
    purchaseInvoiceLine.Narrative = 'line--1';
    
    purchaseInvoiceLine.Quantity = 2;
    
    purchaseInvoiceLine.TaxRate = 'a173H0000008OciQAE'; //provide tax rate id
    
    purchaseInvoiceLine.ForeignNetAmount = 30;
    
    purchaseInvoice.LineItems = new List<zumzum.PurchaseInvoiceService.PurchaseInvoiceLineWrapper>();
    
    purchaseInvoice.LineItems.add(purchaseInvoiceLine);
    
    purchaseInvoiceLine = new zumzum.PurchaseInvoiceService.PurchaseInvoiceLineWrapper();
    
    purchaseInvoiceLine.NominalAccount = 'a0i3H00000000NZQAY';
    
    purchaseInvoiceLine.Narrative = 'line--2';
    
    purchaseInvoiceLine.Quantity = 3;
    
    purchaseInvoiceLine.TaxRate = 'a173H0000008OciQAE'; //provide tax rate id
    
    purchaseInvoiceLine.ForeignNetAmount = 50;
    
    purchaseInvoice.LineItems.add(purchaseInvoiceLine);
    
    lstInvoiceData.add(purchaseInvoice);
    
    zumzum.PurchaseInvoiceService.Response objResponse = objInvoiceHandler.CreatePurchaseInvoices(lstInvoiceData);
    
    system.debug('Message>>' + objResponse.ResponseMessage);
    
    system.debug('purchaseInvoices>>' + objResponse.purchaseInvoices);

    Edit a Draft Purchase Invoice – UpdatePurchaseInvoices Method

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

    Global Class Name Method Input Output
    PurchaseInvoiceService UpdatePurchaseInvoices List “PurchaseInvoiceWrapper” List “Purchase_Invoice__c”

    Sample Code: Update Purchase Invoice

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

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

    Sample Code :

    zumzum.PurchaseInvoiceService objInvoiceHandler = new zumzum.PurchaseInvoiceService();
    
    List<zumzum.PurchaseInvoiceService.PurchaseInvoiceWrapper > lstInvoiceData = new List<zumzum.PurchaseInvoiceService.PurchaseInvoiceWrapper >();
    
    zumzum.PurchaseInvoiceService.PurchaseInvoiceWrapper purchaseInvoice = new zumzum.PurchaseInvoiceService.PurchaseInvoiceWrapper( );
    
    PurchaseInvoice.PurchaseInvoiceId = 'a0n3H0000004pXwQAI';
    
    purchaseInvoice.SupplierAccount = '0013H000003sPCoQAM'; //provide the account id here.
    
    purchaseInvoice.InvoiceDate = date.today().addDays(-20);
    
    PurchaseInvoice.InvoiceDueDate = date.today().addDays(1);
    
    PurchaseInvoice.ExternalReference = 'Edit PI - External reference change';
    
    //purchaseInvoice.TransactionCurrency = 'a1T3H0000004Cc8UAE'; //provide the transaction currency id here
    
    zumzum.PurchaseInvoiceService.PurchaseInvoiceLineWrapper purchaseInvoiceLine = new zumzum.PurchaseInvoiceService.PurchaseInvoiceLineWrapper();
    
    PurchaseInvoiceLine.PurchaseInvoiceLineId = 'a0m3H000000sHeMQAU';
    
    purchaseInvoiceLine.NominalAccount = 'a0i3H00000000NZQAY';
    
    purchaseInvoiceLine.Narrative = 'lineedit--1';
    
    purchaseInvoiceLine.Quantity = 2;
    
    purchaseInvoiceLine.TaxRate = 'a173H0000008OciQAE'; //provide tax rate id
    
    purchaseInvoiceLine.ForeignNetAmount = 35;
    
    purchaseInvoice.LineItems = new List<zumzum.PurchaseInvoiceService.PurchaseInvoiceLineWrapper>();
    
    purchaseInvoice.LineItems.add(purchaseInvoiceLine);
    
    purchaseInvoiceLine = new zumzum.PurchaseInvoiceService.PurchaseInvoiceLineWrapper();
    
    purchaseInvoiceLine.NominalAccount = 'a0i3H00000000NZQAY';
    
    purchaseInvoiceLine.Narrative = 'lineedit--2';
    
    purchaseInvoiceLine.Quantity = 1;
    
    purchaseInvoiceLine.TaxRate = 'a173H0000008OciQAE'; //provide tax rate id
    
    purchaseInvoiceLine.ForeignNetAmount = 45;
    
    purchaseInvoice.LineItems.add(purchaseInvoiceLine);
    
    lstInvoiceData.add(purchaseInvoice);
    
    zumzum.PurchaseInvoiceService.Response objResponse = objInvoiceHandler.UpdatePurchaseInvoices(lstInvoiceData);
    
    system.debug('Message>>' + objResponse.ResponseMessage);
    
    system.debug('purchaseInvoices>>' + objResponse.purchaseInvoices);
    
    

    Post A Purchase Invoice – PostPurchaseInvoice Method

    Below is information related on how to Post a draft Purchase Invoice with the Purchase Invoice API service using Apex code.  Zumzum Financials includes a global class called PurchaseInvoicePostService which you may call from your own Apex code. The PostPurchaseInvoices method is used to change the status of a draft Purchase Invoice and create general ledger records to update your financial reports in Zumzum Financials.

    Global Class Name Method Input Output
    PurchaseInvoicePostService PostPurchaseInvoices List “Purchase_Invoice__c” void

    Sample Code: Post A Purchase Invoice

    Please follow the below steps to post multiple invoices.

    1. Prepare the list collection ‘List<Purchase_Invoice__c>’ to supply as an input for the PostPurchaseInvoice function. For this, you can execute a SOQL command to fetch all the purchase invoices which should be posted or you can use the output of the function ‘CreatePurchaseinvoices’ as explained above in the documentation..

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

    Sample Code:

    /* Gather the list of draft Purchase Invoices with a query */
    
    List<Zumzum__Purchase_Invoice__c> lstDraftPurchaseInvoices = [Select id from Zumzum__Purchase_Invoice__c where Zumzum__Status__c = 'Draft' order by createddate desc limit 20];
    
    Set<Id> setOfPurchaseInvoiceIds = new Set<Id>();
    
    for(Zumzum__Purchase_Invoice__c PI : lstDraftPurchaseInvoices){
    
    setOfPurchaseInvoiceIds.add(PI.id);
    
    }
    
    zumzum.PurchaseInvoiceService objInvoiceHandler = new zumzum.PurchaseInvoiceService();
    
    /* Pass the list of Purchase Invoices to be posted to the PostPurchaseInvoice method */
    
    objInvoiceHandler.PostPurchaseInvoice(setOfPurchaseInvoiceIds,true);

    Batch Post Purchase Invoices

    The Zumzum Financials Purchase Invoice Service “PostPurchaseInvoice” method will accept a “Set” of Purchase Invoice IDs and create general ledger records to update your financial reports.

    You may write your own batch class to pass a set of Purchase Invoice IDs to the PostPurchaseInvoice method or execute this method as a batch within the API.

    To process the set of Purchase Invoice IDs as an internal batch within the Purchase Invoice API set the parameter “executeInBatchProcessing” as true or false. For example, if you wish to pass a set of Purchase Invoice IDs and have the API process those in batches, set the boolean “executeInBatchProcessing” as true.

    Custom Metadata Type – Batch Settings

    By default, the PostPurchaseInvoice batch processing, will process Purchase Invoices contained in the set of Purchase Invoice IDs in batches of 20.

    You may change this setting to optimise the performance in your own org to accomodate any custom workflows and code you may have running, to minimise 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 Purchase 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. 10
    8. Select Save.

    Below is information related to how to batch Post-draft Purchase Invoices as a standard process or batch process.

    Global Class Name Method Input Output
    PurchaseInvoiceService PostPurchaseInvoices Set setOfPurchaseInvoiceIds, boolean executeInBatchProcessing List of Purchase Invoice IDs.

    Sample Code: Batch Post Purchase Invoices

    Please follow the below steps to post multiple invoices.

    1. Prepare the collection ‘Set<setOfPurchaseInvoiceIds>’ to supply as an input for the PostPurchaseInvoice method. For this, you can execute a SOQL command to fetch all the purchase invoices which should be posted.

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

    Sample Code:

    //***************************Start Sample Post Purchase Invoice Code ************************//
    
    zumzum.PurchaseInvoiceService objPurchaseInvoice = new zumzum.PurchaseInvoiceService();
    
    // Populate the Set of Purchase Invoice IDs 
    
    Set<Id> setOfPurchaseInvoiceIds = new Set<Id>{'a0q8E000006jNM7','a0q8E000006jNMC'};
    
    //Pass the parameter “executeInBatchProcessing” as true if you wish to execute post invoice processing in batches
    
    zumzum.PurchaseInvoiceService.Response objResponse = objPurchaseInvoice.PostPurchaseInvoice(setOfPurchaseInvoiceIds,false); 
    
    system.debug('Message>>' + objResponse.ResponseMessage);
    
    system.debug('purchaseInvoices>>' + objResponse.purchaseInvoices);
    
    //*********************End Sample Post Purchase Invoice Code***************************************************//
    
    

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

    Supported Error Codes – Purchase Invoice Service (API)

    Error Message Reason Resolution
    Provide Supplier Name
    Creating a Purchase Invoice for a Supplier Account value which is empty. Provide an account ID for a SupplierName value
    Provide Invoice Date Creating a Purchase Invoice without providing the Invoice Date. Provide an InvoiceDate value with your Purchase Invoice Wrapper data.
    No Line Item in Purchase Invoice, Please Enter Line Items Create a Purchase Invoice without providing Purchase Invoice Line item data. Provide the required fields for the PurchaseInvoiceLineWrapper when creating your Purchase Invoice.
    Line 1 – Provide NominalAccount Create or edit a Purchase Invoice Line item without providing a Nominal Account. Provide the NominalAccount value in your PurchaseInvoiceLineWrapper data.
    Line 1 – Provide Quantity Create or edit a Purchase Invoice Line item without providing a Quantity. Provide the Quantity value in your PurchaseInvoiceLineWrapper data.
    Line 2 – Provide Tax Rate Create or edit a Purchase Invoice Line item without providing a Tax Rate. Provide the TaxRate value in your PurchaseInvoiceLineWrapper data.
    Line 2 – Provide ForeignNetAmount Create or edit a Purchase Invoice Line item without providing a Foreign Net Amount. Provide the ForeignNetAmount value in your PurchaseInvoiceLineWrapper data.
    “Exception occurred – Upsert failed. First exception on row 0; first error: FIELD_CUSTOM_VALIDATION_EXCEPTION, Please make sure that the Dimension is "Active" and "Type" Dimension 2.: [Zumzum__Dimension_2__c] at line 124” Send an ID of Dimension record which is either inactivate or that has a Dimension Type set other than the Dimension filed you are populating. Confirm your Dimension is set to Active and is of the Type which matches the field you are populating on the Purchase Invoice Line.
    in Purchase Invoice API Tags: APIAutomationIntegrationPurchase Invoice

    Related Articles