Web service sales invoice technical description

1. MADE AMENDMENTS:

5.1.2023

· Updated factoring options.

10.9.2021

· Addition of posting proposal element (PROPOSED_PURCHASE_ACCOUNT) to interface and technical description.

17.8.2021

· Removal of the default message (DEFAULT_MESSAGE) -element from the technical description. Text in the element won’t be forwarded to Talenom’s system.

15.1.2021

· Increased the maximum length of PAYER / NAME from string35 to string45

· Increased the maximum length of PRODUCT_NUMBER from 13 to 30

· Request size increased from 4 MB to 8MB

16.9.2020

· Invoicing in different currencies (ORIGINAL_CURRENCY, CUSTOM_EXCHANGE_RATE_TO_EUR)

13.6.2019

· Addition of send method for e-mail invoices (EMAIL_SEND_METHOD) 0 = link (default), 1 = attachment

2.5.2019

· Increased the maximum character limit to 6 on SALES_ACCOUNT_NUMBER and ACCOUNTS_RECEIVABLE

7.2.2019

· Addition of customer type (CUSTOMER_TYPE)

· 0 = Business, 1 = Consumer

5.12.2018

· Discount percentage (DISCOUNT_PERCENTAGE) can no longer be negative

3.9.2018

· Addition of new factoring options: Ropo, Lähirahoitus, Aktia ja AREX

· Addition of Customs export code (CN_CODE)

· Outlook of the document

· List of made amendments

· Addition of e-mail ship mode of invoice

· (SHIPMODE, USE_EMAILBILLING, EMAILBILLING_ADDRESS)

2. GENERAL

With Web Service technology we are able to integrate customers and our (Talenom) systems to communicate automatically. With this service customers are still able to continue using their own software and reduce the amount of time needed to spend in invoicing/Talenom Online.

3. SALES INVOICING

The address of InvoiceService is

https://verkkopalvelu3.talenom.fi:4445/InvoiceService.asmx

The API for the SOAP request can be found in the address below (both SOAP 1.1 and SOAP 1.2 are supported):

https://verkkopalvelu3.talenom.fi:4445/InvoiceService.asmx?op=NewInvoice

https://verkkopalvelu3.talenom.fi:4445/InvoiceService.asmx?op=NewInvoiceFile

4. METHODS

InvoiceService includes the following web methods:

NewInvoice

NewInvoiceFile

NewCustomer

NewInvoice

Inserts a new invoice. The invoice information is delivered via XML file.

<userName>string</userName> 
<userPw>string</userPw> 
<xmlInvoice>xml</xmlInvoice>

userName: Talenom Online Service username
userPW: Talenom Online Service password encrypted with MD5 algorithm
xmlInvoice: Invoice information as an XML file

Maximum size of a NewInvoice -request is 8 MB.

NewInvoiceFile

Inserts a new invoice and a PDF attachment for the invoice.

<userName>string</userName> 
<userPw>string</userPw> 
<byteData>base64Binary</byteData>

Invoice information is delivered via an XML file named “NewInvoice.xml”. The XML file and PDF attachment are zipped so that the PDF file is located in a sub directory named “Attachments”. The name of the PDF file can be anything, and the name is defined in the element PDF_FILE_NAME of the XML file.

Structure of the zip file:

NewInvoice.xml

Attachments

InvoiceAttachment.pdf

The zip file is delivered to the NewInvoiceFile method as a byte array.

Requirements for the PDF file:

- Number of pages is unlimited, but average size of one page should not exceed 2000 kB. Size of the attached PDF file can’t exceed 5 MB. Maximum size of the NewInvoiceFile -request is 8 MB.

NewCustomer

Inserts a new customer / customers. Customer information is given in XML file.

<userName>string</userName> 
<userPw>string</userPw> 
<xmlCustomer>xml</xmlCustomer>

userName: Talenom Online Service username

userPW: Talenom Online Service password encrypted with MD5 algorithm

xmlCustomer: Customer information as an XML file

5. STRUCTURE OF THE XML FILE

The XML schema (NewInvoice.xsd) is explained in the table below. The same XML schema is used both in NewInvoice and NewInvoiceFile method.

NOTE: the elements must be exactly in the same order as below.

Element	Type	Length	Mandatory	Comment
INVOICE			X	The outer element , inside which all the elements listed below are located. This element has no value. The element demads an empty namespace definition: <INVOICE xmlns=””>.
PDF_FILE_NAME	string			Name of the attachment (PDF) file. This element is mandatory in NewInvoiceFile method, but is not needed in NewInvoice method.
CLIENT_ID	int		X	Customer id of the seller
INVOICE_DATE	date YYYY-MM-DD		X	Invoice date. NOTE: invoices dated for the previous month cannot be delivered after interception date.
INVOICE_NUMBER	int	max 8		Invoice number. If invoice number is not delivered in XML and SHIPMODE is 1 or 2, web service generates the invoice number automatically. If invoice number is delivered in XML, SHIPMODE must be <> 0.
PAYMENT_REFERENCE	string	max 20		Reference number. If reference number is delivered, also invoice number must be delivered and SHIPMODE must be <> 0. If SHIPMODE is 3 (Talenom won’t send the invoice forward), payment reference must be provided for the invoice.
DUE_DATE	date YYYY-MM-DD		X	Due date
DELIVERY_DATE	date YYYY-MM-DD			Delivery date
ORDER_NUMBER	string	max 35		Order number
ORDER_DATE	date YYYY-MM-DD			Order date
OUR_REFERENCE	string	max 35		Our reference
YOUR_REFERENCE	string	max 35		Your reference
DNET	short		X	Payment term (days net)
CASHDISDDATE	date YYYY-MM-DD			Cash discount date
CASHDISPERC	decimal(5,2)			Cash discount %
OVERDUEINTEREST	decimal(5,2)			Overdue interest %
REMARKTIME	unsignedByte		X	Remark time
INVOICE_MESSAGE	string	max 1500		Invoice message
CLIENT_MESSAGE	string	max 1500		Client message
SHIPMODE	Int		X	Ship mode. Allowed values: 0 (= Printing) 1 (= Mailing service e- invoice) 2 (= Mailing service paper invoice) 3 (=Printing, state is sent) 4 (=E-mail) If ship mode is 0, the invoice is not approved yet and the invoice number and reference number are set to 0. In this case the invoice must be manually approved in the Online Service. If ship mode is 1 or 2, the invoice is approved at once and the invoice number and reference number are generated if they are not given. The invoice will be sent to Itella, which will send it as an e-invoice or paper invoice. If ship mode is 3, the invoice is approved at once and the invoice number and reference number are generated if they are not given. The invoice will not be sent to Itella, and the state is set to ‘sent’. If ship mode is 4, the invoice is approved at once and sent via e-mail. Note: also USE_EMAILBILLING <> 1 and EMAILBILLING_ADDRESS must be included.
CUSTOMER_TYPE	unsignedByte			Customer type 0 = Business (default) 1 = Consumer
PAYMENT_INSTRUCTION_IDENTIFIER	string	max 35		Invoice subject for e-invoice (consumers)
COMMENT	string			Comment
FACTORING	factoring_type			Factoring company. The Allowed values are: 1=Nordea 2=Pohjola 3=Danske 4=Handelsbanken 5=Ropo Finance 6=Noja Rahoitus 7=Aktia 8=Svea 9=Alisa Bank If FACTORING element is missing, a normal invoice is inserted. If FACTORING element exists, a factoring company invoice is inserted. Factoring feature is not active automatically, client must have the agreement with the factoring company first. For more information, contact the Talenom Sales Invoices team.
PAYMENT_REMINDER_BLOCK	int			1 = Payment reminder blocking is yes 0 = Payment reminder blocking no Default 0
PAYMENT_COLLECT_BLOCK	int			1 = Payment collection blocked is yes 0 = Payment collection blocked no Default 0
ORIGINAL_INVOICE_NUMBER	string	max 8		Used in Credit invoice for pointing to previous invoice which is being credited
PAYER			X	Mandatory information of the end customer (payer). The customer information will be updated to the Online Service every time. If customer with the given number does not exist in the system, a new customer will be generated with the given information.
NUMBER	int	max 10	X	Customer number of the end customer. To insert new customer, give 0 or some other non-existing customer number.
NAME	string	max 45	X	Name of the end customer
NAME_EXT	string	max 60		Name extension of the end customer
ACCOUNTS_RECEIVABLE	int	max 6	X	The end customer’s accounts receivable number. The account number must exist in the Online Service. Default accounts receivable number is 1701.
DELIVERY_ADDRESS				Delivery address.
STREET_ADDRESS	string	max 100 (35)		Delivery address: street address. Length max 35 if also STREET_ADDRESS2 is used.
STREET_ADDRESS2	string	max 35		Delivery address: street address 2
POSTAL_CODE	string	max 50		Delivery address: postal code
POST_OFFICE	string	max 30		Delivery address: post office
COUNTRY	string	max 2		Delivery country as ISO 3166-1 alpha-2 country code (FI/GB/SE etc.)
DELIVERY_LOCATION	string	max 100		Delivery location
INVOICE_ADDRESS			X	Invoice address
STREET_ADDRESS	string	max 100 (35)	X	Invoice address: street address. Length max 35 if also STREET_ADDRESS2 is used.
STREET_ADDRESS2	string	max 35		Invoice address: street address2
POSTAL_CODE	string	max 50	X	Invoice address: postal code
POST_OFFICE	string	max 30	X	Invoice address: post office
COUNTRY	string	max 2	X	Invoice country as ISO 3166-1 alpha-2 country code (FI/GB/SE etc.)
USE_EMAILBILLING	string			1 = Invoice is sent via e-mail (NOTE: Also SHIPMODE= 4 and EMAILBILLING_ADDRESS must be included)
EMAILBILLING_ADDRESS	string	max 100		The e-mail address of the payer
EMAIL_SEND_METHOD	string			Send method for e-mail invoices 0 = link (default) 1 = attachment
VAT_ID	string	max 20		VAT id of the end customer
BUSINESS_ID	string	max 20		Business id of the end customer
PHONE	string	max 15		Phone number of the end customer
MOBILE	string	max 15		Mobile number of the end customer
TELEFAX	string	max 15		Telefax number of the end customer
EMAIL	string	max 50		Email of the end customer
EINVOICEID	string	max 35		EInvoice id of the end customer. NOTE: if SHIPMODE = 1, this element cannot be empty.
INTERMEDIATOR	string	max 35		Intermediator is the number of the e-invoice operator.
INVOICE_LANGUAGE	language_type		X	Invoice language. Allowed values: fi-FI sv-SE en-GB de-DE
CUSTOMER_MESSAGE	string	max 200		Customer message
VAT_INCLUDED	decimal(19,4)			Invoice amount including VAT
VAT_EXCLUDED	decimal(19,4)			Invoice amount excluding VAT
ORIGINAL_CURRENCY	string	max 3		Original currency of the invoice according to ISO 4217 code list. (NOTE: EXCHANGE_RATE_TO_ EUR must also be included)
EXCHANGE_RATE_TO_EUR	decimal(19,4)			Exchange rate used to convert the total amount of invoice from original currency to euros for accounting (Calculation: sum of the invoice divided by exchange rate = sum of the invoice in euros). Value can’t be ≤ 0, has to be ≠ 1 (NOTE: ORIGINAL_CURRENCY must also be included)
ROWS				Invoice rows. Atleast one (ROW) per invoice
PRODUCT_NUMBER	string	max 30	X	Product number
PRODUCT_NAME	string	max 45	X	Product name
PRODUCT_INFO	string	max 1024	X	Product info Element PRODUCT_INFO is mandatory, but it can be empty, if ROW_TYPE=0. If ROW_TYPE=1, it must include the info text.
CN_CODE	string	max 20		Customs export code
QUANTITY	decimal(8,4)		X	Quantity
UNIT	string	max 15		Unit (example: st, kg, km, h, etc..)
PRICEPERUNIT	decimal(19,4)		X	Price per unit
DISCOUNT_PERCENTAGE	decimal(5,2)		X	Discount %
VAT_RATE	decimal(5,2)		X	VAT %
ROW_TYPE	row_type		X	Row type. Allowed values: 0 (=Product) 1 (=Info)
SALES_ACCOUNT_NUMBER	int	max 6	X	Sales account number The account number must exist in the Online Service.
PROPOSED_PURCHASE_ACCOUNT	string	max 4		Posting proposal. Bookkeeping account to which the receiver can post the invoice row in their own system. If more than 4 characters are used, the element is ignored.
VAT_INCLUDED	decimal(19,4)			Row amount including VAT
VAT_EXCLUDED	decimal(19,4)			Row amount excluding VAT
COST_CENTER_CODE	string	max 8		Cost center code. If the code does not exist in Online Service, new cost center will be inserted to the system.
COST_CENTER_INFO	string	max 50		Cost center name
COST_TYPE_CODE	string	max 8		Cost type code. If the code does not exist in Online Service, new cost type will be inserted to the system.
COST_TYPE_INFO	string	max 50		Cost type name
PROJECT_CODE	string	max 8		Project code. If the code does not exist in Online Service, new project will be inserted to the system.
PROJECT_INFO	string	max 50		Project name
PROJECT_TYPE_CODE	string	max 6		Project type code. If the code does not exist in Online Service, new cost center will be inserted to the system.
PROJECT_TYPE_INFO	string	max 50		Project type name

Return value of the NewInvoice ja NewInvoiceFile methods

The method returns the invoice information in XML format. The INVOICE element will include STATUS attribute, return status of the invoice insert operation. If the invoice was added successfully, the XML will include the elements listed below (in addition to the elements listed above).

NOTE: type of the return value is string, but it can be converted to a XML file.

INVOICE_NR	Invoice number (NOTE: if SHIPMODE = 0, invoice number = 0)
REFERENCE_NR	Reference number (NOTE: if SHIPMODE = 0, reference number = 0)
AMOUNT_TOTAL_VAT_INCLUDED	Total amount of the invoice, VAT included
AMOUNT_TOTAL_VAT_EXCLUDED	Total amount of the invoice, VAT excluded
AMOUNT_VAT	VAT amount
INVOICE_ACCEPTED	Date of acception (Note: if SHIPMODE = 0, acception date is empty)
PAYER/NUMBER	Customer number of a new end customer, if the customer was added. Otherwise the original customer number delivered in the XML.
ROW/TOTAL_SUM_VAT_INCLUDED	Total sum of the row, VAT included
ROW/TOTAL_SUM_VAT_EXCLUDED	Total sum of the row, VAT excluded
ROW/TOTAL_VAT	Total VAT of the row

The INVOICE element has attribute Status and ReturnMessage, which include status information of the success of the invoice insertion.

OK Invoice was successfully added

Error Invoice insertion failed. The error message is included in ReturnMessage attribute.

If an error occurred, the ReturnMessage attribute includes a description of the error. Below are listed examples of possible error messages. All error messages beginning with “XML validation error” are produced by an XML validator and are caused by the fact that the delivered XML file does not correspond to the XML schema (some mandatory element is missing / some value is wrong type / the elements are in wrong order).

Error: Invalid username or password	Username or password is invalid
Error: Invalid CLIENT_ID - user does not have “eSales Invoice” rights for the client	The user does not have ”eSales Invoice” rights for the client
Error: Invalid value in INVOICE_ADDRESS/COUNTRY	Invoice country is invalid (must be ISO 3166-1 alpha-2-country code)
Error: Invalid value in DELIVERY_ADDRESS/COUNTRY	Delivery country is invalid (must be ISO 3166-1 alpha-2-country code)
Error: ROW/PRODUCT_INFO cannot be empty when ROW_TYPE = 1	Info row (ROW_TYPE=1) is missing a value in the PRODUCT_INFO element
Error: PAYER/EINVOICEID cannot be empty when SHIPMODE = 1	EINVOICEID must be non-empty if SHIPMODE = 1
XML validation error: The 'DUE_DATE' element is invalid - The value '' is invalid according to its datatype 'http://www.w3.org/2001/XMLSchema:date' - The string '' is not a valid XsdDateTime value	An example of a XML validator error message: due date cannot be empty
XML validation error: The element 'INVOICE' has invalid child element 'DELIVERY_DATE'. List of Allowed elements expected: 'DUE_DATE'.	An example of a XML validator error message:
	Mandatory element DUE_DATE is missing

NewCustomer XML-file structure

The XML schema (NewCustomer.xsd) is explained in the table below.

NOTE: the elements must be exactly in the same order as below.

Elementti	Tyyppi	Pituus	Pakollinen	Kommentti
CUSTOMER			X	The outer element , inside which all the elements listed below are located. This element has no value. The element demads an empty namespace definition: <CUSTOMER xmlns=””>.
CLIENT_ID	int		X	Customer id of the seller
ROWS				Customer information rows. Minimum one (ROW) per customer.
NUMBER	int		X	Customer number of the end customer. To insert new customer, give 0 or some other non-existing customer number.
NAME	string	max 35	X	Name of the end customer
NAME_EXT	string	max 60		Name extension of the end customer
STREET_ADDRESS	string	max 100	X	Invoice address: street address
POSTAL_CODE	string	max 50	X	Invoice address: postal code
POST_OFFICE	string	max 30	X	Invoice address: post office
COUNTRY	string	max 2	X	Invoice country as ISO 3166-1 alpha-2 country code (FI/GB/SE etc.)
DELIVERY_ADDRESS				Delivery address.
STREET_ADDRESS	string	max 100		Delivery address: street address
POSTAL_CODE	string	max 50		Delivery address: postal code
POST_OFFICE	string	max 30		Delivery address: post office
COUNTRY	string	max 2		Delivery country as ISO 3166-1 alpha-2 country code (FI/GB/SE etc.)
DELIVERY_LOCATION	string	max 100		Delivery location
VAT_ID	string	max 20		VAT id of the end customer
BUSINESS_ID	string	max 20		Business id of the end customer
PHONE	string	max 15		Phone number of the end customer
MOBILE	string	max 15		Mobile number of the end customer
TELEFAX	string	max 15		Telefax number of the end customer
EMAIL	string	max 50		Email of the end customer
EINVOICEID	string	max 35		EInvoice id of the end customer.
				NOTE: if SHIPMODE = 1, this element cannot be empty.
INVOICE_LANGUAGE	language_type		X	Invoice language. Allowed values:
				fi-FI
				sv-SE
				en-GB
				de-DE
ACCOUNTS_RECEIVABLE	int	max 6		The end customer’s accounts receivable number. The account number must exist in the Online Service. Default accounts receivable number is 1701.

Return value of NewCustomer -method

The method returns the invoice information in XML format and adds to CUSTOMER-element the status-attribute, return status of the invoice insert operation. If the operation was successful, the XML will include the elements listed below (in addition to the elements listed above).

NOTE: type of the return value is string, but it can be converted to a XML file.

The CUSTOMER element has attribute Status and ReturnMessage, which include status information of the success of the customer insertion.

OK Invoice was successfully added

Error Invoice insertion failed. The error message is included in ReturnMessage attribute.

Element	Type	Length	Mandatory	Comment
INVOICE			X	The outer element , inside which all the elements listed below are located. This element has no value. The element demads an empty namespace definition: <INVOICE xmlns=””>.
PDF_FILE_NAME	string			Name of the attachment (PDF) file. This element is mandatory in NewInvoiceFile method, but is not needed in NewInvoice method.
CLIENT_ID	int		X	Customer id of the seller
INVOICE_DATE	date		X	Invoice date. NOTE: invoices dated for the previous month cannot be delivered after interception date.
	YYYY-MM-DD
INVOICE_NUMBER	int	max 8		Invoice number. If invoice number is not delivered in XML and SHIPMODE is 1 or 2, web service generates the invoice number automatically. If invoice number is delivered in XML, SHIPMODE must be <> 0.
PAYMENT_REFERENCE	string	max 20		Reference number. If reference number is delivered, also invoice number must be delivered and SHIPMODE must be <> 0. If SHIPMODE is 3 (Talenom won’t send the invoice forward), payment reference must be provided for the invoice.
DUE_DATE	date		X	Due date
	YYYY-MM-DD
DELIVERY_DATE	date			Delivery date
	YYYY-MM-DD
ORDER_NUMBER	string	max 35		Order number
ORDER_DATE	date YYYY-MM-DD			Order date
OUR_REFERENCE	string	max 35		Our reference
YOUR_REFERENCE	string	max 35		Your reference
DNET	short		X	Payment term (days net)
CASHDISDDATE	date			Cash discount date
	YYYY-MM-DD
CASHDISPERC	decimal(5,2)			Cash discount %
OVERDUEINTEREST	decimal(5,2)			Overdue interest %
REMARKTIME	unsignedByte		X	Remark time
INVOICE_MESSAGE	string	max 1500		Invoice message
CLIENT_MESSAGE	string	max 1500		Client message
SHIPMODE	Int		X	Ship mode. Allowed values:
				0 (= Printing)
				1 (= Mailing service e- invoice)
				2 (= Mailing service paper invoice)
				3 (=Printing, state is sent)
				4 (=E-mail)
				If ship mode is 0, the invoice is not approved yet and the invoice number and reference number are set to 0. In this case the invoice must be manually approved in the Online Service.
				If ship mode is 1 or 2, the invoice is approved at once and the invoice number and reference number are generated if they are not given. The invoice will be sent to Itella, which will send it as an e-invoice or paper invoice.
				If ship mode is 3, the invoice is approved at once and the invoice number and reference number are generated if they are not given. The invoice will not be sent to Itella, and the state is set to ‘sent’.
				If ship mode is 4, the invoice is approved at once and sent via e-mail. Note: also USE_EMAILBILLING <> 1 and EMAILBILLING_ADDRESS must be included.
CUSTOMER_TYPE	unsignedByte			Customer type
				0 = Business (default)
				1 = Consumer
PAYMENT_INSTRUCTION_IDENTIFIER	string	max 35		Invoice subject for e-invoice (consumers)
COMMENT	string			Comment
FACTORING	factoring_type			Factoring company. The Allowed values are:
				1=Nordea
				2=Pohjola
				3=Sampo
				If FACTORING element is missing, a normal invoice is inserted. If FACTORING element exists, a factoring company invoice is inserted.
PAYMENT_REMINDER_BLOCK	int			1 = Payment reminder blocking is yes
				0 = Payment reminder blocking no
				Default 0
PAYMENT_COLLECT_BLOCK	int			1 = Payment collection blocked is yes
				0 = Payment collection blocked no
				Default 0
ORIGINAL_INVOICE_NUMBER	string	max 8		Used in Credit invoice for pointing to previous invoice which is being credited
PAYER			X	Mandatory information of the end customer (payer). The customer information will be updated to the Online Service every time. If customer with the given number does not exist in the system, a new customer will be generated with the given information.
NUMBER	int	max 10	X	Customer number of the end customer. To insert new customer, give 0 or some other non-existing customer number.
NAME	string	max 45	X	Name of the end customer
NAME_EXT	string	max 60		Name extension of the end customer
ACCOUNTS_RECEIVABLE	int	max 6	X	The end customer’s accounts receivable number. The account number must exist in the Online Service. Default accounts receivable number is 1701.
DELIVERY_ADDRESS				Delivery address.
STREET_ADDRESS	string	max 100		Delivery address: street address
STREET_ADDRESS2	string	max 35		Delivery address: street address 2
POSTAL_CODE	string	max 50		Delivery address: postal code
POST_OFFICE	string	max 30		Delivery address: post office
COUNTRY	string	max 2		Delivery country as ISO 3166-1 alpha-2 country code (FI/GB/SE etc.)
DELIVERY_LOCATION	string	max 100		Delivery location
INVOICE_ADDRESS			X	Invoice address
STREET_ADDRESS	string	max 100	X	Invoice address: street address
STREET_ADDRESS2	string	max 35		Invoice address: street address2
POSTAL_CODE	string	max 50	X	Invoice address: postal code
POST_OFFICE	string	max 30	X	Invoice address: post office
COUNTRY	string	max 2	X	Invoice country as ISO 3166-1 alpha-2 country code (FI/GB/SE etc.)
USE_EMAILBILLING	string			1 = Invoice is sent via e-mail
				(NOTE: Also SHIPMODE= 4 and EMAILBILLING_ADDRESS must be included)
EMAILBILLING_ADDRESS	string	max 100		The e-mail address of the payer
EMAIL_SEND_METHOD	string			Send method for e-mail invoices
				0 = link (default)
				1 = attachment
VAT_ID	string	max 20		VAT id of the end customer
BUSINESS_ID	string	max 20		Business id of the end customer
PHONE	string	max 15		Phone number of the end customer
MOBILE	string	max 15		Mobile number of the end customer
TELEFAX	string	max 15		Telefax number of the end customer
EMAIL	string	max 50		Email of the end customer
EINVOICEID	string	max 35		EInvoice id of the end customer.
				NOTE: if SHIPMODE = 1, this element cannot be empty.
INTERMEDIATOR	string	max 35		Intermediator is the number of the e-invoice operator.
INVOICE_LANGUAGE	language_type		X	Invoice language. Allowed values:
				fi-FI
				sv-SE
				en-GB
				de-DE
CUSTOMER_MESSAGE	string	max 200		Customer message
VAT_INCLUDED	decimal(19,4)			Invoice amount including VAT
VAT_EXCLUDED	decimal(19,4)			Invoice amount excluding VAT
ORIGINAL_CURRENCY	string	max 3		Original currency of the invoice according to ISO 4217 code list. (NOTE: EXCHANGE_RATE_TO_ EUR must also be included)
EXCHANGE_RATE_TO_EUR	decimal(19,4)			Exchange rate used to convert the total amount of invoice from original currency to euros for accounting (Calculation: sum of the invoice divided by exchange rate = sum of the invoice in euros). Value can’t be ≤ 0, has to be ≠ 1 (NOTE: ORIGINAL_CURRENCY must also be included)
ROWS				Invoice rows. Atleast one (ROW) per invoice
PRODUCT_NUMBER	string	max 30	X	Product number
PRODUCT_NAME	string	max 45	X	Product name
PRODUCT_INFO	string	max 1024	X	Product info
				Element PRODUCT_INFO is mandatory, but it can be empty, if ROW_TYPE=0. If ROW_TYPE=1, it must include the info text.
CN_CODE	string	max 20		Customs export code
QUANTITY	decimal(8,4)		X	Quantity
UNIT	string	max 15		Unit (example: st, kg, km, h, etc..)
PRICEPERUNIT	decimal(19,4)		X	Price per unit
DISCOUNT_PERCENTAGE	decimal(5,2)		X	Discount %
VAT_RATE	decimal(5,2)		X	VAT %
ROW_TYPE	row_type		X	Row type. Allowed values:
				0 (=Product)
				1 (=Info)
SALES_ACCOUNT_NUMBER	int	max 6	X	Sales account number
				The account number must exist in the Online Service.
VAT_INCLUDED	decimal(19,4)			Row amount including VAT
VAT_EXCLUDED	decimal(19,4)			Row amount excluding VAT
COST_CENTER_CODE	string	max 8		Cost center code.
				If the code does not exist in Online Service, new cost center will be inserted to the system.
COST_CENTER_INFO	string	max 50		Cost center name
COST_TYPE_CODE	string	max 8		Cost type code.
				If the code does not exist in Online Service, new cost type will be inserted to the system.
COST_TYPE_INFO	string	max 50		Cost type name
PROJECT_CODE	string	max 8		Project code.
				If the code does not exist in Online Service, new project will be inserted to the system.
PROJECT_INFO	string	max 50		Project name
PROJECT_TYPE_CODE	string	max 6		Project type code.
				If the code does not exist in Online Service, new cost center will be inserted to the system.
PROJECT_TYPE_INFO	string	max 50		Project type name

Below is an example of a return XML , when the invoice has been successfully added.

<?xml version="1.0" encoding="utf-8" ?> 
- <INVOICE xmlns="" Status="OK" ReturnMessage="Success: Invoice added">
  <INVOICE_NR>1009</INVOICE_NR> 
  <REFERENCE_NR>12310092</REFERENCE_NR> 
  <AMOUNT_TOTAL_VAT_INCLUDED>166.8836</AMOUNT_TOTAL_VAT_INCLUDED> 
  <AMOUNT_TOTAL_VAT_EXCLUDED>135.6777</AMOUNT_TOTAL_VAT_EXCLUDED> 
  <AMOUNT_VAT>31.2059</AMOUNT_VAT> 
  <INVOICE_ACCEPTED>09/12/2018 10:47:00</</INVOICE_ACCEPTED> 
  <CLIENT_ID>22</CLIENT_ID> 
  <INVOICE_DATE>2018-12-09</INVOICE_DATE> 
  <DUE_DATE>2018-12-23</DUE_DATE> 
  <DELIVERY_DATE>2018-12-30</DELIVERY_DATE> 
  <OUR_REFERENCE>our reference</OUR_REFERENCE> 
  <YOUR_REFERENCE>your reference</YOUR_REFERENCE> 
  <DNET>14</DNET> 
  <CASHDISDDATE>2018-12-16</CASHDISDDATE> 
  <CASHDISDATEPERC>2.50</CASHDISDATEPERC> 
  <OVERDUEINTEREST>8.50</OVERDUEINTEREST> 
  <REMARKTIME>8</REMARKTIME> 
  <INVOICE_MESSAGE>Invoice message</INVOICE_MESSAGE> 
  <CLIENT_MESSAGE>Client message</CLIENT_MESSAGE>
  <SHIPMODE>1</SHIPMODE> 
  <COMMENT /> 
- <PAYER>
  <NUMBER>123</NUMBER> 
  <NAME>Test Company Oy</NAME> 
  <NAME_EXT /> 
- <DELIVERY_ADDRESS>
  <STREET_ADDRESS>Saturnuksentie 45</STREET_ADDRESS> 
  <POSTAL_CODE>01480</POSTAL_CODE> 
  <POST_OFFICE>Helsinki</POST_OFFICE> 
  <COUNTRY>FI</COUNTRY> 
  <DELIVERY_LOCATION>Helsinki</DELIVERY_LOCATION> 
  </DELIVERY_ADDRESS>
- <INVOICE_ADDRESS>
  <STREET_ADDRESS>PL 125</STREET_ADDRESS> 
  <POSTAL_CODE>01481</POSTAL_CODE> 
  <POST_OFFICE>Espoo</POST_OFFICE> 
  <COUNTRY>FI</COUNTRY> 
   <USE_EMAILBILLING></USE_EMAILBILLING>
   <EMAILBILLING_ADDRESS></EMAILBILLING_ADDRESS>
  </INVOICE_ADDRESS>
  <VAT_ID>FI1122336</VAT_ID> 
  <BUSINESS_ID>112233-6</BUSINESS_ID> 
  <PHONE>09-123666</PHONE> 
  <MOBILE /> 
  <TELEFAX /> 
  <EMAIL /> 
  <EINVOICEID /> 
  <INTERMEDIATOR /> 
  <INVOICE_LANGUAGE>fi-FI</INVOICE_LANGUAGE> 
  <CUSTOMER_MESSAGE>Customer message</CUSTOMER_MESSAGE> 
  <DNET>14</DNET> 
  <CASH_DIS_DAYS>7</CASH_DIS_DAYS> 
  <CASH_DIS_DATE_PERC>2.50</CASH_DIS_DATE_PERC> 
  </PAYER>
- <ROWS>
- <ROW>
  <PRODUCT_NUMBER>10</PRODUCT_NUMBER> 
  <PRODUCT_NAME>Pen</PRODUCT_NAME> 
  <PRODUCT_INFO></PRODUCT_INFO> 
  <QUANTITY>1</QUANTITY> 
  <PRICEPERUNIT>100.1255</PRICEPERUNIT> 
  <DISCOUNT_PERCENTAGE>10.00</DISCOUNT_PERCENTAGE> 
  <VAT_RATE>24.00</VAT_RATE> 
  <ROW_TYPE>0</ROW_TYPE> 
  <SALES_ACCOUNT_NUMBER>123456</SALES_ACCOUNT_NUMBER>
  <PROPOSED_PURCHASE_ACCOUNT>4000</PROPOSED_PURCHASE_ACCOUNT>
  <COST_CENTER_CODE>1234</COST_CENTER_CODE> 
  <COST_CENTER_INFO>Cost center 1</COST_CENTER_INFO> 
  <COST_TYPE_CODE>345</COST_TYPE_CODE> 
  <COST_TYPE_INFO>Cost type 1</COST_TYPE_INFO> 
  <PROJECT_CODE /> 
  <PROJECT_INFO /> 
  <PROJECT_TYPE_CODE /> 
  <PROJECT_TYPE_INFO /> 
  <TOTAL_SUM_VAT_INCLUDED>110.8389</TOTAL_SUM_VAT_INCLUDED>
  <TOTAL_SUM_VAT_EXCLUDED>90.113</TOTAL_SUM_VAT_EXCLUDED>
  <TOTAL_VAT>20.726</TOTAL_VAT> 
  </ROW>
- <ROW>
  <PRODUCT_NUMBER>20</PRODUCT_NUMBER> 
  <PRODUCT_NAME>Paper clip</PRODUCT_NAME> 
  <PRODUCT_INFO></PRODUCT_INFO> 
  <QUANTITY>5</QUANTITY> 
  <PRICEPERUNIT>10.1255</PRICEPERUNIT> 
  <DISCOUNT_PERCENTAGE>10.00</DISCOUNT_PERCENTAGE> 
  <VAT_RATE>24.00</VAT_RATE> 
  <ROW_TYPE>0</ROW_TYPE> 
  <SALES_ACCOUNT_NUMBER>123777</SALES_ACCOUNT_NUMBER>
  <PROPOSED_PURCHASE_ACCOUNT />
  <COST_CENTER_CODE /> 
  <COST_CENTER_INFO /> 
  <COST_TYPE_CODE /> 
  <COST_TYPE_INFO /> 
  <PROJECT_CODE /> 
  <PROJECT_INFO /> 
  <PROJECT_TYPE_CODE /> 
  <PROJECT_TYPE_INFO /> 
  <TOTAL_SUM_VAT_INCLUDED>56.0446</TOTAL_SUM_VAT_INCLUDED>
  <TOTAL_SUM_VAT_EXCLUDED>45.5648</TOTAL_SUM_VAT_EXCLUDED>
  <TOTAL_VAT>10.4799</TOTAL_VAT> 
  </ROW>
- <ROW>
  <PRODUCT_NUMBER /> 
  <PRODUCT_NAME /> 
  <PRODUCT_INFO>Info for an info row</PRODUCT_INFO> 
  <QUANTITY>0</QUANTITY> 
  <PRICEPERUNIT>0</PRICEPERUNIT> 
  <DISCOUNT_PERCENTAGE>0</DISCOUNT_PERCENTAGE> 
  <VAT_RATE>0</VAT_RATE> 
  <ROW_TYPE>1</ROW_TYPE> 
  <SALES_ACCOUNT_NUMBER>0</SALES_ACCOUNT_NUMBER>
  <PROPOSED_PURCHASE_ACCOUNT />
  <COST_CENTER_CODE /> 
  <COST_CENTER_INFO /> 
  <COST_TYPE_CODE /> 
  <COST_TYPE_INFO /> 
  <PROJECT_CODE /> 
  <PROJECT_INFO /> 
  <PROJECT_TYPE_CODE /> 
  <PROJECT_TYPE_INFO /> 
  <TOTAL_SUM_VAT_INCLUDED>0</TOTAL_SUM_VAT_INCLUDED> 
  <TOTAL_SUM_VAT_EXCLUDED>0</TOTAL_SUM_VAT_EXCLUDED> 
  <TOTAL_VAT>0</TOTAL_VAT> 
  </ROW>
  </ROWS>
  </INVOICE>

Back

Integraatioportaali

Web service sales invoice technical description

Contact us

Thanks you!

An error has occured.