Sales - Functional description of fields sales invoices XML

Modified on Thu, 08 Jun 2023 at 11:04 AM

This article describes the functional development in the software of a number of fields in the sales invoices XML. This must be submitted via the Sales - ProcessSalesInvoices(sessionID, administrationId, xmlDoc) web service method.

ATTENTION!

It is recommended to examine the XML scheme below, this information is most complete and described in English.

Web address of the XML scheme of the sales invoices

http://www.yukiworks.nl/schemas/SalesInvoices.xsd

Example of XML scheme

<Subject>Testfactuur - 1</Subject>

<PaymentMethod>ElectronicTransfer</PaymentMethod>

<EmailToCustomer>false</EmailToCustomer>

<FullName>Apple Sales International</FullName>

<City>Rotterdam</City>

<AddressLine_1>Bergweg 25</AddressLine_1>

<AddressLine_2 />

<ContactType>Company</ContactType>

</Contact>

<FirstName>Steve</FirstName>

<EmailAddress>steve@apple.com</EmailAddress>

</ContactPerson>

<Description>Regel 1</Description>

<Description>Product 1</Description>

</Product>

</InvoiceLine>

</InvoiceLines>

</SalesInvoice>

</SalesInvoices>

Description of fields

Below you will find a description of the fields. The XML scheme itself also contains a description of the fields and which values and data types are expected.

SalesInvoice: Reference

In this field you can enter the invoice number.

Invoice will be handled, printed and/or sent from outside Yuki. Thus, the invoice was given an invoice number from outside Yuki.
The 'Reference' field contains the invoice number and the 'Process' field must contain the value 'true' so Yuki knows that the invoice with the submitted data can be processed immediately.

Invoice still has to be processed, printed and/or sent manually within Yuki, The invoice will be given an invoice number by Yuki.
The 'Reference' field has to be omitted and the 'Process' field must contain the value 'false'.

SalesInvoice: PaymentMethod

The payment method of the invoice. Possible options:

Unspecified (in Yuki the 'Electronic transfer' payment method will be filled in)
ElectronicTransfer (transfer)
DirectCollection ('Direct debit' payment method first needs to be activated in the invoice settings)
CreditCard
DebitCard (payment with debit card)
Cash
iDeal
Online.

SalesInvoice: Process

In this field you have to indicate whether or not the invoice has to be processed immediately. If you choose to process the invoice then you also have to enter the correct invoice number in the 'Reference' field.

When the value is 'true' the invoice is processed in Yuki and sent (if specified). Is the value 'false' then the invoice will be made ready in 'To be sent' and still has to be processed.

If the TAG Process is missing Yuki will assume that the value is 'false'.

SalesInvoice: EmailToCustomer

If you choose to process an invoice then you can indicate in this field whether or not the invoice has to be mailed immediately via Yuki to the customer. This functionality first needs to be activated in the invoice settings.

If you don't want the invoice to be sent then you can omit it or enter the value 'false'.

SalesInvoice: Lay-out

In this field you can indicate the desired invoice layout. When you leave this field blank Yuki will use the default layout.

SalesInvoice: Date

The invoice date.

SalesInvoice: DueDate

The due date.

SalesInvoice: PriceList

In this field you can enter the desired price list. When you leave this field blank Yuki will use the default price list.

If you offer a combination of VAT inclusive and exclusive prices it is useful that you give a VAT inclusive or exclusive price list. Suppose it is a VAT inclusive price then it will be stated correctly on the invoice. However, is the sales item saved in a VAT exclusive price list and you create an invoice with the same sales item in the Yuki sales module then the price will be treated as VAT exclusive and will be stated as such on the invoice.

ATTENTION!

The prices, VAT codes and revenue accounts that are given in the invoice are leading.

SalesInvoice: Currency

The currency of the sales invoice. If the field is not completed then the default value is 'EUR'.

If there is no price list specified then Yuki will look at the default price list. If this is not in foreign currency then the 'The pricelist's currency "EUR" does not match with the invoice's' notification will be displayed.

If the Currency deviates from the foreign curreny in the price list then the 'The pricelist's currency "USD" does not match with the invoice's' notificaton will be displayed.

If the 'Currency' field is not completed and the 'Pricelist' field is and this field is in foreign currency then the 'The pricelist's currency "USD" does not match with the invoice's' notification will be displayed.

SalesInvoice: ProjectID

The ID of the project to which you want to link the document. If this parameter is given then the 'ProjectCode' parameter is redundant.

A user with the 'Management' role must have chosen the Medium, Large or Unlimited bundle via the Yuki Store in the domain.

SalesInvoice: ProjectCode

The code of the project to which you to link the document. This parameter is only used when the 'ProjectID' parameter is not given.

A user with the 'Management' role must have chosen the Medium, Large or Unlimited bundle via the Yuki Store in the domain.

Salesinvoice: Remarks

The entered information will not be shown on the invoice but will be saved as a remark with the sales invoice.

Contact: Contact

In the Contact element the contact/customer of the invoice is entered. First there will be searched for an existing contact in the address book of Yuki. There wil be searched:

If a contact code is given: by contact code via the 'ContactCode' field
If not found or no contact code given: by full name via the 'FullName' field

If no existing contact is found a new contact will be created.

Contact: found with ContactCode = contact code on the contact card

If a contact code is used the address details of an existing contact will always be overwritten with the current value in the XML source file.
In order to not overwrite a field the element can be omitted completely from the XML source file.
In order to empty a field the element must be included as an empty node (for example <CocNumber />).

Contact: found with FullName = name or company name on the contact card

If a contact with the same name is found then only the incomplete fields (blank fields) of that contact will be supplemented with data from the XML source file.
Also for address details, data is only supplemented if the existing data is identical.
For example the address 'Dorpstraat 40, Ons Dorp' will be supplemented to 'Dorpstraat 40, 1234 XX, Ons Dorp' if the address and city are identical in the XML and the postal code is also given.

Contact: EmailAddress

It is possible to give one email address. This address is saved on the contact card of the customer and will be of the 'Invoice' type. If this address changes in time then you can send this via the web service for a new invoice. the 'old' email address will be of the 'Other' type and the new email address will be of the 'Invoice' type.

Contact: BankAccount

If a bank account is given then this bank account will be saved for this contact. The bank account will also be used as bank account number for this invoice. Thus it is possible to save multiple bank accounts for the same customer.

Contact: BIC

If a BIC is given then this BIC will be saved with the bank account for this contact. The bank account number with the BIC wilL also be used as bank account number for this invoice.

ATTENTION!

It is thus possible to also create foreign bank accounts.

InvoiceLine: Description

The description of the invoice line. If this field is incomplete or doesn't exist then the description from 'Product Description' will be used.

InvoiceLine: Remarks

This is an extra description that you can give per invoice line. The text will be placed on a new line below the current line.

ATTENTION!

You have to indicate a newline with the code 

InvoiceLine: ProductQuantity

The quantity of the sales item in the invoice line.

InvoiceLine: LineAmount

Here an amount of a line can be given. When this amount is given the calculation of the amount of a line based on the number of products (ProductQuantity) and the price (/Product/SalesPrice) will be skipped. When /Product/VATIncluded is equal to 'true' then this amount is VAT inclusive, otherwise the amount is VAT exclusive.

ATTENTION!

It is not advisable to use this field. This namely deviates from the Yuki calculation methods!

InvoiceLine: LineVATAmount

Here a VAT amount of a line can be given. When this amount is given the calculation of the VAT amount of a line based on the amount per line and the used VAT rate will be skipped.

ATTENTION!

Ii is not advisable to use this field. This namely deviates from the Yuki calculation methods.

Product: Description

The description of the sales item with a maximum lengh of 60 characters. Longer descriptions will be shortened. This must be unique.

If the sales item doesn't exist in Yuki then it will be created based on the data that is included in the XML.

If the 'InvoiceLine: Description' is empty then the Product: Description will be printed on the invoice.

Product: Reference

The reference of the sales item with a maximum length of 40 characters. Longer references will be shortened. This must be unique.

Product: Category

In the future this field can be used for the assignment of categories. At the moment only the 'NULL' and '13' (13 = sales items category) are allowed. This field cannot be empty.

Product: SalesPrice

The sales price of the sales item. This field can be blank or can be given with a 0-value if the sales item has already been created and can be found based on the description/reference.

Only if the 'Salesprice', 'VATType' and 'VATPercentage' fields are completed Yuki will use the data from the XML and otherwise it wlll use the information from the price list.
If one of the three elements is missing then the sales item must have already been created in the price list because then Yuki cannot create the sales item in the price list. That ofcourse is necessary in order to create the invoice because Yuki will use the data of the sales item in the price list.

Product: VATPercentage

The VAT rate (percentage) of the sales item. This field is used in combination with the 'VATType' field in order to retrieve the VAT code. If there is no VAT code with this combination then the invoice will be cancelled.

Product: VATIncluded

Ths field indicates whether the sales price is VAT inclusive or not. This field is used in combination with the 'SalesPrice' and 'VATType' fields in order to calculate the VAT amount and the sales price.

By default the value 'false' will be used when this field is given empty in combination with a sales price.

Value 'false' = sales price is VAT exclusive, value 'true' = sales price is VAT inclusive.

Product: VATType

This field indicates the VAT type of the sales item. This field is used in combination with the 'SalesPrice' and 'VATPercentage' fields in order to calculate the VAT amount and the sales price. Possible combinations of VAT percentage and VAT code are:

VATtype Percentage Description

0	0%	Exempt from VAT
1	Variable	High VAT rate
2	Variable	Low VAT rate
4	0%	Btw 0%
6	0%	Export outside the EU
7	0%	Export within the EU
8	Country-specific	Installation/distance sales within the EU
17	0%	VAT reverse charge
19	0%	Export goods EU (leveringen 2010)
20	0%	Export services EU (diensten 2010)
40	Variable	OSS

VATDescription: Remarks

This field can be used in combination with VATType '8', this is not required. You will find the VATDescription in the VAT rate settings of the domain.

Product: GLAccountCode

The code of the GL account in Yuki.

If the sales item has not yet been created in Yuki and this field is blank or it contains an invalid value (a GL account that is not activated is also invalid) then the GL account with code '80000 Revenue item group 1' will be used.
If the sales item has been created and this field is blank then the GL account number that is linked to the sales item in Yuki will be used.
If the sales item has been created and this field contains a valid value then the content of GLAccountCode will be used. For that matter, the GL account number of the existing sales item will then not be changed.

Product: Remarks

This remark will be added to the sales item in Yuki and therefore will not be visible on the invoice.

InvoiceLine: AccrualDate

Startdate of the accrual of the revenue of the sales invoice.

InvoiceLIne: AccrualPeriods

The number of periods over which the revenue of the sales invoice should be accrued for example 12 periods.

InvoiceLine: AccrualInterval

The duration of a period expressed in months.