Exporting invoices to Heeros (API)

Opter can be connected to (integrated with) the Heeros accounting system. Invoices can then be exported from Opter to Heeros. More information about Heeros is available at heeros.com (in Finnish) and heeros.com/en (in English).

Step 1: Create an invoice export for Heeros in Opter

Click on Economy > Invoices > Invoice export and create a new invoice export by clicking on . The following fields must be filled in on the General tab:
- Name: For example, 'Heeros (API)'.
- Report: None.
- Type: XmlSerializer. (Type must be XmlSerializer).
- Encoding: UTF-8.
- Customer code: The customer code can be found in Heeros, "la_id" or "end customer id" (loppuasiakastunnus).
- Office code: The office code can be found in Heeros, "tt_id" or "accounting customer id" (tilitoimistotunnus).
- Start text: In this field, other parameters can be added to customise the export.
  
  Use the format "parameter=value" and write one parameter per line, as in the example below.
  Example, Start text field
```
1
2
3
4
5
6
7
MoveOnlyToLedger=true
SendToCustomer=false
CreateCustomer=true
UpdateCustomer=true
CreateProduct=true
UpdateProduct=true
CreateAccountingObjects=true
```
  If a specific parameter is not entered in the Start text field, the default setting is used. For more information on the parameters, see the Parameters table in the Start text field below.
- Select the One file per invoice checkbox.
Click on to save all changes.
Click on the File transfer tab. The following fields must be filled in:
- Method: Heeros API.
- Client identity: Heeros API user identity ("Heeros user name").
- Client key: Heeros API key ("Heeros password").
Click on to save all changes.

Step 2: Insert the transform into the invoice export

This step is ordered by Opter. Contact for more information.

Step 3: Add the invoice export to an invoice export group

To create a new invoice export setting (i.e. group of exports) or to check if there is already an invoice export setting (group) where you want to add the invoice export to Heeros, proceed as follows:

Click on Economy > Invoices > Invoice export settings.
Look in the list on the left to see if there is already an invoice export setting (group) where you want to add the invoice export to Heeros. Click on that invoice export setting and select the checkbox for "Heeros API" (or the name you gave the invoice export) under Exports.

If there is no invoice export setting (group) where you want to add the invoice export to Heeros, create a new one. Click on and give the invoice export setting a name, for example “Heeros API”. Select the checkbox for "Heeros API" (or the name you gave the invoice export) under Exports.
Click on to save all changes.
Choose which invoice export setting should be the default. To choose Heeros API as the default, select “Heeros API” from the list on the left and click on .
To ensure that all invoices are recorded in Heeros, select the “Heeros API” export for all export settings (groups).
Click on to save all changes.
To set which invoice export setting (group) applies to a particular customer, click on Register > Customers and search for the customer for which the setting is to be made. Click on the Invoice information tab and select invoice export setting (group) in the Invoice export setting drop-down list. Click on to save all changes.

Step 4: Export invoices to Heeros

The invoice information can be exported from Opter when closing an invoice period, or subsequently when choosing whether to export entire invoice periods or individual invoices.

Click on Economy > Invoices > Invoices.
Select the invoice or invoice period you want to export, right-click and select Export.

If the Preview (don't send) checkbox is selected and then the Preview button (which then appears) is clicked, nothing is sent to Heeros.
Click on Export and send to export the invoice or invoice period to Heeros.

The number of invoices to be exported and the number of invoices exported are displayed, as well as a progress bar (at the bottom of the window), are shown in the Invoice export window in Opter. When the invoice export has been completed, the entire progress bar is green.

If the invoice export fails, the progress bar turns grey and there is a statement indicating that the export failed. If the export fails, an error message is displayed, see Error messages below.

Parameters in the Start text field

The table lists the parameters that can be entered in the Start text field. For more information and examples, see Step 1 above.

Parameter	Description
MoveOnlyToLedge=<true/false>	Invoices in Heeros can be sent to the receiver (customer) via Opentext. Choose whether or not to send the invoice automatically to Opentext: ”True” (default): The invoice is sent automatically to Opentext. “False”: The invoice is saved in "Heeros Sales Invoices" in the "complete" status. The invoice can then manually be sent to Opentext or directly to the customer. Only one of the parameters MoveOnlyToLedge and SendToCustomer (see below) can be set to "true".
SendToCustomer=<true/false>	Choose whether or not to send the invoice automatically to the customer: “True”: The invoice is sent automatically to the customer. ”False” (default): The invoice is saved in "Heeros Sales Invoices" in the "complete" status. The invoice can then manually be sent to Opentext or directly to the customer. Only one of the parameters MoveOnlyToLedge (see above) and SendToCustomer can be set to "true".
CreateCustomer=<true/false>	Choose whether or not the customer should be created automatically in Heeros: ”True” (default): If the customer on the invoice being exported does not exist in Heeros, the customer is automatically created in Heeros. “False”: If the customer on the invoice being exported does not exist in Heeros, an error message is issued by Heeros when the invoice is exported. So, the customer is not automatically created in Heeros, but the customer can be manually created in Heeros and the invoice can then be exported again.
UpdateCustomer=<true/false>	Choose whether or not customer information should be updated automatically in Heeros: ”True” (default): If the information about the customer on the exported invoice does not match the information in Heeros, the customer information is automatically updated in Heeros. “False”: If the information about the customer on the exported invoice does not match the information in Heeros, an error message is issued by Heeros when the invoice is exported. So, the customer information is not automatically updated in Heeros, but the information about the customer can be manually updated in Heeros and the invoice can then be exported again.
CreateProduct=<true/false>	In Opter, price items and/or products can be listed on the invoice, (you usually choose to use price items or products). In Heeros it is just called products. Choose whether or not the product should be created automatically in Heeros: ”True” (default): If the product on the invoice being exported does not exist in Heeros, the product is automatically created in Heeros. “False”: If the product on the invoice being exported does not exist in Heeros, an error message is issued by Heeros when the invoice is exported. So, the product is not automatically created in Heeros, but the product can be manually created in Heeros and the invoice can then be exported again.
UpdateProduct=<true/false>	In Opter, price items and/or products can be listed on the invoice, (you usually choose to use price items or products). In Heeros it is just called products. Choose whether or not the product should be updated automatically in Heeros: ”True” (default): If the information about the product on the exported invoice does not match the information in Heeros, the product information is automatically updated in Heeros. “False”: If the information about the product on the exported invoice does not match the information in Heeros, an error message is issued by Heeros when the invoice is exported. So, the product information is not automatically updated in Heeros, but the information about the product can be manually updated in Heeros and the invoice can then be exported again.
CreateAccountingObjects=<true/false>	Choose whether or not the account coding should be created automatically in Heeros: ”True” (default): When exporting invoices, the account coding is created automatically in Heeros. “False”: The account coding is not created automatically in Heeros.

Troubleshooting

Error messages

If the export to Heeros does not work, an error message is displayed. Error messages only appear if something goes wrong during export. Error messages are displayed in a popup window, and are not saved anywhere.

Error message	Description
Could not log into Heeros. Either the username/password is incorrect or it is not possible to connect to Heeros at the moment. Please try again in a few minutes.	Check in Opter, on the File transfer tab, that everything is correct in the fields: Client identity: API user identity from Heeros. (Heeros username). Client key: API key from Heeros. (Heeros password). (See the instruction above). Then try to export the invoices again.
It was not possible to send the invoice to Heeros. Error code from Heeros: {0}. Error message from Heeros: {1}	Read the error code and error message from Heeros and try to rectify the problem. Then you can try to export the invoices again.
The invoice has been sent but it could not be processed in Heeros because it is incomplete. Please check incomplete invoices in Heeros. Invoice ID in Heeros: {0}.	Contact Heeros and ask for more information.
The invoice has been sent but it could not be confirmed within the time limit. Please check incomplete invoices in Heeros to see if it has been registered and its current status. Invoice ID in Heeros: {0}.	Check the invoice in Heeros, whether it has come to Heeros and what its status is. You can try exporting the invoice again.
It was not possible to send the invoice {1} to Heeros due to validation errors. Number of errors: {2}. Please contact Opter support.	Contact Opter support if you receive this error message.