Setting up Bexio: OAuth, contacts and invoices

The Bexio integration pushes customers and invoices from i-Reserve to Bexio: the customer becomes a contact, the invoice a sales invoice with invoice lines. The integration uses OAuth2 and is outbound — changes you make in Bexio do not come back to i-Reserve.

To reach Management > Integrations you need the menu_confmod_integrations right.

1. On the Bexio side (one-time)

1. Register an OAuth app in the Bexio developer portal and note the Client ID and Client Secret.
2. Add the redirect URL shown by i-Reserve to that app's allowed list.
3. The app needs permissions on contacts (read and write), sales invoices (read and write) and articles; i-Reserve requests those on the consent screen itself.
4. Configure the VAT rates in Bexio — you need them for the mapping in step 5.

2. Authentication tab

Then run Step 1 – application consent (you are redirected to Bexio to allow the integration) and Step 2 – connect to Bexio (i-Reserve exchanges the consent code for an access and refresh token). The access token is refreshed automatically from then on. If consent does expire, run steps 1 and 2 again; nothing else needs reconfiguring.

3. Details tab

4. Fields: which customer data is sent?

On the integration's field card you decide, per Bexio field, which i-Reserve field fills it. By default the following is sent:

Besides a regular customer or company field you can also pick a composed value: full name, informal name, address or company address.

Contact type. If a company is attached to the customer, i-Reserve creates a company in Bexio (name 1 = company name, name 2 = last name). Without a company it becomes a person (name 1 = last name, name 2 = first name). That is the Bexio convention and is not configurable.

i-Reserve looks for an existing contact by the stored Bexio id first. If there is none, or that contact no longer exists, it searches by contact number. If nothing is found, i-Reserve creates a new contact.

5. VAT mapping (required)

• On the mapping card, link every i-Reserve VAT rate in use to a Bexio tax code. i-Reserve fetches the active tax codes live from Bexio, so you pick them from a list.
• If the mapping for a rate on the invoice is missing, the invoice is not created and i-Reserve reports that there is no VAT code for that rate.
• The other mapping types (article, payment condition) are not used by the Bexio integration.

6. When does it synchronise?

• Invoice finalised — as soon as an invoice is finalised in i-Reserve, first the contact and then the invoice with its lines go to Bexio.
• Sending the invoice — with "send email from Bexio" enabled, Bexio takes care of the invoice email on finalising.
• Manually — from the customer and invoice screen the Bexio button pushes the customer or invoice on request. See Bexio: comparing invoice lines and syncing manually.

For an invoice that already exists in Bexio, i-Reserve updates it: the existing lines are deleted and recreated, after which the invoice data is updated. Bexio does not accept lines when the invoice itself is updated.

7. Testing and checking

• On the integration test screen you can, without a booking: find a customer, create or update a customer, find an invoice, create an invoice and fetch the VAT codes. The data sent and Bexio's answer are shown side by side — useful for tracing an error message.
• Every call to Bexio is logged. See How do I check what an integration has done?.
• Background and a comparison with the other accounting integrations: Accounting integrations: introduction and functional background.

8. Activate & checklist

• ☐ OAuth app created in Bexio; Client ID and Client Secret noted; redirect URL allowed.
• ☐ VAT rates configured in Bexio.
• ☐ Authentication tab filled; step 1 and step 2 succeeded.
• ☐ Details tab: customer number prefix/length, finalising and email deliberately set.
• ☐ VAT mapping complete for all rates in use.
• ☐ Field card checked; contact type (person or company) matches what you expect in Bexio.
• ☐ Test invoice pushed and checked in Bexio: contact, lines, quantities and VAT.
• ☐ Integration set to active; rollback known (setting it inactive stops new synchronisations).