Venice
Handling invoicing documents using the SDK
 
This topic explains how to handle invoicing documents using the SDK. There are several methods available for doing this task. You have to decide whether or not to have user interface and if you want Venice to do most of the work or completely handle the data yourself (currently only possible for the SOrder, the SDeliv and the SInvce object).
Details will be given about how to insert, update or delete a complete document and how to consult, insert, update or delete details, distributions (option 'Stock Management' and/or option 'Serial Numbers'), and Intrastat details (option 'Intrastat').
 
In the SDK several methods are available for handling the invoicing 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 offer (option 'Purchase Management') Import ImportDialog
Purchase order (option 'Purchase Management') Import ImportDialog
Purchase delivery (option 'Purchase Management') Import ImportDialog
Purchase invoice (option 'Purchase Management') Import ImportDialog
Sales offer Import ImportDialog
Sales order (option 'Sales Management') Import ImportDialog
Sales delivery (option 'Sales Management') Import ImportDialog
Sales invoice 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 offer (option 'Purchase Management') Insert
Purchase order (option 'Purchase Management') Insert
Purchase delivery (option 'Purchase Management') Insert
Purchase invoice (option 'Purchase Management') Insert
Sales offer Insert
Sales order (option 'Sales Management') Insert
Sales delivery (option 'Sales Management') Insert
Sales invoice 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 offer (option 'Purchase Management') Update
Purchase order (option 'Purchase Management') Update
Purchase delivery (option 'Purchase Management') Update
Purchase invoice (option 'Purchase Management') Update
Sales offer Update
Sales order (option 'Sales Management') Update
Sales delivery (option 'Sales Management') Update
Sales invoice 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 offer (option 'Purchase Management') Delete
Purchase order (option 'Purchase Management') Delete
Purchase delivery (option 'Purchase Management') Delete
Purchase invoice (option 'Purchase Management') Delete
Sales offer Delete
Sales order (option 'Sales Management') Delete
Sales delivery (option 'Sales Management') Delete
Sales invoice Delete
 
PrepareDocument
What?
This method allows you to completely handle (insert, update, delete and consult) all parts of a document: header, details, distributions and if available Intrastat details, without user interface.
How?
If you want to securely handle invoicing 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 SInvce 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 SInvce 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 SInvce 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 SInvce object) or the CancelDocument (e.g. for the SInvce 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 SInvce 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 SInvce object) or the CancelDocument (e.g. for the SInvce object) method is called (see 'Write or cancel').
During the period of time between calling the PrepareDocument method (e.g. for the SInvce object) and the WriteDocument method (e.g. for the Sales object) or the CancelDocument (e.g. for the SInvce 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 SInvce object properties) and make sure that the document number (property pDocNum of e.g. the SInvce object properties) is 0, your document will automatically be numbered.
Not all of the header fields you updated will be written to disk and will stay unchanged, e.g. when the document is protected 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 Delete existing detail Consult existing detail Number of details Insert invoicing proposal
Sales order
Details
Distributions
InsertDetailSel
InsertStkDetail
UpdateDetailSel
UpdateStkDetail
DeleteDetail
DeleteStkDetail
GetDetail
GetStkDetail
GetNumDetails
GetNumStkDetails
InsertInvProp
-
Sales delivery
Details
Distributions
InsertDetailSel
InsertStkDetail
UpdateDetailSel
UpdateStkDetail
DeleteDetail
DeleteStkDetail
GetDetail
GetStkDetail
GetNumDetails
GetNumStkDetails
InsertInvProp
-
Sales invoice
Details
Extended details
Distributions
Intrastat details
InsertDetailSel
InsertDetailSel2
InsertStkDetail
InsertItrDetail
UpdateDetailSel
UpdateDetailSel2
UpdateStkDetail
UpdateItrDetail
DeleteDetail
DeleteDetail
DeleteStkDetail
DeleteItrDetail
GetDetail
GetDetail2
GetStkDetail
GetItrDetail
GetNumDetails
GetNumDetails
GetNumStkDetails
GetNumItrDetails
InsertInvProp
-
-
-

Remarks
If you do not provide a TSM number (property pTsmNumber of e.g. the SInvce object properties), one will be automatically created (if necessary) when saving the document using the WriteDocument method (e.g. for the Sales object.
It is not possible to tick other invoicing documents nor detail lines of other invoicing documents.
It is, on the other hand, possible to consult the ticking info of a detail (vTickSysNum, vTickYear, vTickDocType) by using the GetDetail method (e.g. for the SInvce object).
The default (English) prefixes for the article numbers, available in Venice, are also provided for use in the detail lines.
Valid prefixes are 'n:' (number), 'a:' (alias), 'b:' (bar code), 'd:' (description) and, if applicable, 's:' (serial number).
For more information on the use of these prefixes, you should consult the help of your Venice installation.
 
Write or cancel
The final step is to save the provided data to disk using the WriteDocument (e.g. for the SInvce object) method or cancel the preparations using the CancelDocument (e.g. for the SInvce object) method.

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