HaloCRM Guides

A guide outlining the configuration and use of the Fortnox integration. 

Please note that you need a Fortnox Licence with a subscription of appropriate permissions to be able to use this integration.

Enabling the Module

To enable the Fortnox integration, go to Configuration > Integrations > Accounts and Payments and enable the module using the plus icon in the top right hand corner of the menu icon. Once the module has been enabled, click the menu icon to begin configuring it.

Fortnox Tenants

Halo allows you to connect to multiple Fortnox tenants. Once connected to a tenant, you will be able to configure Accounts and Customers. You will also be able to sync any changes to Customers and Invoices from Halo to Fortnox.

Before configuring any of the general settings for this integration, you must first connect to at least one Fortnox tenant. Click the Fortnox tenants button to start this process.

Connecting to Fortnox

Start by creating a new Fortnox connection. First you must specify a sensible name for the connection. It is recommended that you use your company name that you will be connecting to, as this name will be displayed throughout the Halo application in different places.

Once a sensible name has been chosen, click the Connect Now button to begin the authorization process with Fortnox. You will be redirected to the Fortnox login screen to log in to Fortnox. Once logged in, you will be asked to authorise the scopes of the integration. Once you have confirmed this, you will be redirected back to the Fortnox connection you started setting up in Halo. Providing there were no issues with your authentication, extra options will now be available on the setup screen.

IMPORTANT: Once connected, remember to save the connection in Halo. If you complete the connection process without saving the connection, then the connection will remain in an disconnected state. 

Should you wish to disconnect from a Fortnox tenant at any time, you can either use the Disconnect button that is now available, or you can delete the connection.

Tax Rates

Before proceeding with any further configuration, it is recommended you setup your tax rates in Halo to mirror the rates found in Fortnox. Note that these can't be imported from Fortnox at the time of writing of this guide so you will need to make sure the tax rate % match something in Fortnox, however name does not matter here.

Customer Imports

Now that tax rates have been configured, you can move onto importing customers. In order for invoices to sync, each customer in Halo must be assigned a Fortnox ID, so you should ensure that all of your customers are imported from Fortnox if you want to be able to sync their invoices across.

IMPORTANT: This step of the integration is compulsory if you want invoices for a customer to be synced. If the customer already exists in your system, but is not assigned a Fortnox ID via this import, their invoices will not sync. 

When importing, existing customer records in Halo will be updated if they have the same name or accounts code in Halo as they do in Fortnox. If they are being imported for a second time, then the record will be updated based on the Fortnox ID that has been previously assigned to the record.

NOTE: If a customer already exists with the same name but is assigned to different Fortnox tenant, then a new record will be created.

When you are happy, click the Import Customers button to open the importer screen, where your customers from Fortnox will be listed for you to import. 

Once you have imported at least one record, navigate to the customers view and open a customer that has been imported. On the settings tab of this customer, you will see that your customer record has been linked to your Fortnox tenant, along with other information which has been imported from Fortnox. 

It is not possible to edit the Fortnox tenant that a customer belongs to once it has been assigned to the tenant.

Accounts Codes Imports

Note that this step is optional but can save you a lot of time later. If you enable the Accounts codes module in Configuration > Billing first then navigate to the accounts codes tab in your Fortnox Tenant, you can import all your accounts from Fortnox. This will then allow you to use these per-line on invoices rather than manually writing in the account number. If you wish to manually enter the accounts code each time, you can skip this step, however it can considerably cut down the time spent setting up each invoice so it is recommended to complete this:

Syncing to Fortnox

Now that you have imported customers and setup taxes, you can now either enable syncing to Fortnox. By enabling this feature, whenever you create or update a customer/Invoice in Halo, the changes will be synced to Fortnox. If the customer/Invoice in Halo is correctly linked to a Fortnox record, then the record will be updated in Fortnox, otherwise a new record will be created.

To enable syncing of any entity to Fortnox, add the entity to the Entities to Sync field.

Firstly, there is an option to show a message whenever a sync is successful. It is highly recommended that you enable this feature, particularly when first using the integration, as it gives a good indication that the actions you are taking are working. 

You should also disable auto-population of accounts ID by going to Configuration -> Billing -> General Settings -> Advanced Settings -> 'Auto generate an accounts id for new customer'. This is important to ensure that customer's created in Halo are successfully created in Fortnox. 

Example: with this feature enabled, if you try to sync an invoice for a customer who has not been correctly linked to a Fortnox customer, then no popup will display, which will indicate to you that Halo has not tried to sync the invoice to Fortnox.

General Settings

Now that you have connected to one of your Fortnox tenants, you can revisit the initial module setup screen (Configuration > Billing > Fortnox Integration). Here you can configure the default tenant for new Customers:

IMPORTANT: This field should not be left blank. If left blank and you don't set this value manually when creating a new record, the record will not be synced to Fortnox. If the new record is a customer, it would mean that you cannot sync their invoices to Fortnox.

Syncing Customers

When you are creating a new customer, there are some compulsory fields that must be completed for the sync to be successful. These fields are located on the settings tab of the customer under the Billing Settings header. The only non-standard compulsory field is the Fortnox tenant. If you have chosen a default Fortnox tenant, then this field will already be populated for you.

If you wish to match a customer to an already existing customer in Fortnox you can set the Customer ID for Accounting Integration which will then manually try and update that client, linking them together.

WARNING: Failure to populate the tenant field will result in the customer not being synced to Fortnox.

Syncing Invoices

Providing all steps of this guide have been followed, and every entity in Halo is correctly linked to an entity in Fortnox, syncing invoices will be straightforward. All types of invoices can be synced to Fortnox, whether it be for labour on tickets or an invoice created from a recurring invoice. We will only look at raising a basic manual invoice in this guide for simplicity. The process should be the same as creating a Halo invoice as normal with no additional inputs.

If no errors have been shown but no message is shown when it should or no record is found in the Outbound Requests tab in the tenant, then Halo has not tried to sync the invoice. This will be due to the customer record not being linked to a Fortnox tenant. In this scenario, you should ensure that this is set against the customer record and then update the invoice.

Updates to invoices that have already successfully synced to Fortnox will also be synced to Fortnox, for example, if you wanted to increase the quantity of an existing invoice line.

Should you wish to remove an invoice, deleting it from Halo will not currently remove the invoice from Fortnox.

Errors

In the event that a sync to Fortnox fails, all errors are saved against the Fortnox tenant connection for traceability. To review these errors, navigate to Configuration > Integrations > Fortnox > Fortnox Tenants, open a tenant that you are connected to and switch to the Outbound Integrations tab.

The table will provide an overview of the Outbound requests in the order in which they occurred. By clicking the request, you can review the post request we made to Fortnox and review the values we sent or review the error for example:

Would indicate a customer you're trying to update, is no longer found in Fortnox, usually due to being deleted.

As of v2.156 products can be imported from Fortnox, this is acheived via the products tab of a Fortnox tenant.