Handling accounting documents using the SDK
 
This topic explains how to handle accounting documents (available in the Purchase object, the Sales object, the Finan object and the Sndry object) using the SDK. It will give you details about how to insert, update or delete a complete document and how to consult, insert, update or delete accounting details, analytical details (option 'Analytical'), Intrastat details (option 'Intrastat' and only for purchase and sales documents) and payment info (option 'Payments' and only for purchase documents).
 
In the SDK several methods are available for handling the accounting documents of your Venice installation.
 
Import
What?
These methods allow you to insert a complete document, without or with user interface (using the import dialog). It cannot be used for updating or deleting documents.
How?
Document type Method without user interface Method with user interface (using the import dialog of Venice)
Purchase Import ImportDialog
Sales Import ImportDialog
Financial Import ImportDialog
Sundry Import ImportDialog
 
Insert
What?
This method allows you to insert a complete document, but only via the user interface (using the document dialog of Venice).
How?
Document type Method (using the document dialog of Venice, eInsertMode = imDialog)
Purchase Insert
Sales Insert
Financial Insert
Sundry Insert
 
Update
What?
This method allows you to update a complete document, but only via the user interface (using the document dialog of Venice). Using this method to update a document without user interface is also possible but the changes will be limited to the data of the header and to fields which can be modified in the grid of the corresponding Venice module only.
How?
Document type Method without (eUpdateMode != umDialog) or with user interface (using the document dialog of Venice, eUpdateMode = umDialog)
Purchase Update
Sales Update
Financial Update
Sundry Update
 
Delete
What?
This method allows you to delete a complete document, but without user interface. You can also use this method to test if a document can be deleted without actually deleting it.
How?
Document type Method (for testing only, set eDeleteMode to dmTestOnly)
Purchase Delete
Sales Delete
Financial Delete
Sundry Delete
 
PrepareDocument
What?
This method allows you to completely handle (insert, update, delete and consult) all parts of a document: header, details, analytical details, Intrastat details and payment info (for purchase documents only), without user interface.
How?
If you want to securely handle accounting documents, make sure to follow these steps:
 
Preparing the object
In this step, you prepare the object for inserting a new document, duplicating, updating or consulting an existing one by calling the PrepareDocument (e.g. for the Sales object) method, by stating the appropriate 'ePrepareAction'.
It will load the necessary data of all related records in accordance with the action you requested:
Header data Detail data
paInsert Data of the current document (overridden by the Init method, e.g. for the Sales object) None
paDuplicate Data of the document you want to duplicate Detail data of the document you want to duplicate
paUpdate Data of the document you want to update Detail data of the document you want to update
paView Data of the document you want to consult Detail data of the document you want to consult
After calling the PrepareDocument (e.g. for the Sales object), most of the properties, that are read-only in a normal situation, are no longer read-only and can be set. After calling the WriteDocument (e.g. for the Sales object) or the CancelDocument (e.g. for the Sales object) method is called (see 'Write or cancel'), these properties are read-only again.
After the necessary data is loaded, you must provide all new header data.
Make sure that that data is correctly provided (using the properties of your object, e.g. for the Sales object) before you proceed with the next steps.
For more information about which fields need to be supplied for inserting a new document, you can consult the help of your Venice installation concerning the import option.
If you are updating an existing document, this method will lock the document until the WriteDocument (e.g. for the Sales object) or the CancelDocument (e.g. for the Sales object) method is called (see 'Write or cancel').
During the period of time between calling the PrepareDocument method (e.g. for the Sales object) and the WriteDocument method (e.g. for the Sales object) or the CancelDocument (e.g. for the Sales object) method (see 'Write or cancel'), your application will use up 1 Import-user, except when the PrepareDocument method was called using the value 'paView' for the parameter ePrepareAction.
Therefore, the option 'Import' must be installed in order to manipulate (create, duplicate or change) documents in the SDK.
If you provide the correct book (property pBook of e.g. the Sales object properties) and make sure that the document number (property pDocNum of e.g. the Sales object properties) is 0, your document will automatically be numbered.
This is NOT the case for financial documents, there you must always provide a document number.
Not all of the header fields you updated will be written to disk and will stay unchanged, e.g. when the document is ticked or transferred.
 
Execute the actual action
Now, you must provide all the necessary data for the several types of details, depending on the action you want to execute:
Document type Insert new detail Update existing detail (Selectively) Delete existing detail Consult existing detail Number of details Insert entry proposal
Purchase
Details
Analytical details
Intrastat details
Payment info
InsertDetail
InsertAnaDetail
InsertItrDetail
SetPayInfo
UpdateDetail / UpdateDetailSel
UpdateAnaDetail
UpdateItrDetail
-
DeleteDetail
DeleteAnaDetail
DeleteItrDetail
-
GetDetail
GetAnaDetail
GetItrDetail
GetPayInfo
GetNumDetails
GetNumAnaDetails
GetNumItrDetails
-
InsertEntProp
-
-
-
Sales
Details
Analytical details
Intrastat details
InsertDetail
InsertAnaDetail
InsertItrDetail
UpdateDetail / UpdateDetailSel
UpdateAnaDetail
UpdateItrDetail
DeleteDetail
DeleteAnaDetail
DeleteItrDetail
GetDetail
GetAnaDetail
GetItrDetail
GetNumDetails
GetNumAnaDetails
GetNumItrDetails
InsertEntProp
-
-
Financial
Details
Analytical details
InsertDetail
InsertAnaDetail
UpdateDetail / UpdateDetailSel
UpdateAnaDetail
DeleteDetail
DeleteAnaDetail
GetDetail
GetAnaDetail
GetNumDetails
GetNumAnaDetails
InsertEntProp
-
Sundry
Details
Analytical details
InsertDetail
InsertAnaDetail
UpdateDetail / UpdateDetailSel
UpdateAnaDetail
DeleteDetail
DeleteAnaDetail
GetDetail
GetAnaDetail
GetNumDetails
GetNumAnaDetails
InsertEntProp
-

Remarks
Make sure that the property pAutoPay of the Purch object is set to true before using the SetPayInfo method otherwise the changes will not be written to disk.
You can use the GetManualIndex method (of e.g. the Sales object) to retrieve the index of the first counterpart entry. If none exists, this method will return -1.
In purchase, in sales and in financial documents there always must be a header entry (= entry on a supplier account, a customer account and a financial book account respectively). If you do not provide the data for this detail line, it will be automatically generated by the SDK using data from the header.
If you need to provide it yourself, e.g. if you want to specify the remark, a free value or analytical details, it is recommended that the shortcut "H" (header) is used to avoid errors against the formatting rules of the account number (parameter bsAccount, see InsertDetail method of e.g. the Sales object).
Providing an amount (parameter dAmountDocC, see InsertDetail method of e.g. the Sales object) for this detail is obsolete because it is always overwritten by the SDK, based on the data in the header. For the corresponding analytical details on the other hand, you must provide the correct amount (parameter dAmountDocC, see InsertAnaDetail method of e.g. the Sales object) yourself, it is not provided by the SDK.
In purchase and in sales documents the header entry must be followed by entries on VAT accounts, in order of VAT group. If you do not provide the data for this lines, they will be automatically generated by the SDK using data from the header.
If you need to provide them yourself, e.g. if you want to specify the remark, a free value or analytical details, it is recommended that a series of shortcuts starting with 'V' (VAT account) are used to avoid errors against the formatting rules of the account number (parameter bsAccount, see InsertDetail method of e.g. the Sales object):
Type   Shortcuts
Purchase   "V20" (VAT group 20), "V22" (VAT group 22), "V23" (VAT group 23), "V24" (VAT group 24), "V26" (VAT group 26), "V28" (VAT group 28)
Sales   "V10" (VAT group 10), "V12" (VAT group 12)
The corresponding account number for these shortcuts can be found on the tab 'VAT accounts' of the general parameters of the option 'Accounting'.
Providing an amount (parameter dAmountDocC, see InsertDetail method of e.g. the Sales object) for this detail is obsolete because it is always overwritten by the SDK, based on the data in the header. For the corresponding analytical details on the other hand, you must provide the correct amount (parameter dAmountDocC, see InsertAnaDetail method of e.g. the Sales object) yourself, it is not provided by the SDK.
If an analytical entry proposal exists for the given account number (parameter bsAccount, see InsertDetail method of e.g. the Sales object)), analytical distribution for this detail will be automatically provided by the SDK for the given amount (parameter dAmountDocC, see InsertDetail method of e.g. the Sales object). This automatic distribution will also be done when updating the existing account number (parameter bsAccount, see UpdateDetail method of e.g. the Sales object).
Therefore, it is important that the correct amount (parameter dAmountDocC) is provided when adding header and/or VAT entries yourself, even if this amount is automatically calculated by the SDK based on the header data when inserting/updating the document.
The default (English) prefixes for the accounts, available in Venice, are also provided for use in counterpart entries. It is recommended that they are used to avoid errors against the formatting rules of the account number (parameter bsAccount, see InsertDetail method of e.g. the Sales object).
Valid prefixes are a(ccount), c(ustomer), s(upplier), d(eposits), b(anks), p(ostal cheques) and (Cas)h.
For more information on the use of prefixes, you should consult the help of your Venice installation.
Deleting details (DeleteDetail of e.g. the Sales object) is only allowed when the detail is not ticked nor transferred.
 
Write or cancel
The final step is to save the provided data to disk using the WriteDocument (e.g. for the Sales object) method or cancel the preparations using the CancelDocument (e.g. for the Sales object) method.

Remarks
Make sure that this step is always executed, especially in situations where an exception is thrown, by providing accurate error handling!