> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hr-easy.nlead.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# bexio integration

> Two-way sync of employees, hours and leave with bexio Lohn, plus payslip import and reconciliation.

For organizations that run payroll in **bexio Lohn**, Swiss HR Easy stays the system of
record for people and pushes what payroll needs, rather than asking anyone to maintain
two employee lists.

## What syncs

<CardGroup cols={2}>
  <Card title="Employees" icon="user">
    Push employee master data into bexio; pull the bexio side back to detect divergence. Mapping is
    maintained per employee so a bexio record is never duplicated.
  </Card>

  <Card title="Hours and leave" icon="clock">
    Recorded time and approved absences flow to bexio as payroll inputs.
  </Card>

  <Card title="Payslips" icon="file-invoice">
    Generated payslips are imported back and made available to the employee in the portal — one
    place for the employee regardless of where payroll ran.
  </Card>

  <Card title="Reconciliation" icon="arrows-rotate">
    Compares both sides and reports what differs, per employee and per field.
  </Card>
</CardGroup>

## How the sync engine behaves

Syncing to an external SaaS API fails sometimes. The engine is built for that rather
than around it:

* **Retries with backoff.** A transient failure is retried; the retry count is tracked
  per item, and retryable items are re-queued rather than silently dropped.
* **A sync log.** Every run records what was attempted, what succeeded and what failed,
  with statistics. When someone asks "did the March hours reach bexio?", the answer is
  a lookup rather than an investigation.
* **Conflict detection.** When both sides changed the same field since the last sync,
  the engine reports a conflict instead of picking a winner. A silent overwrite of a
  bexio-side correction would be worse than a stalled sync.

## Setup

<Steps>
  <Step title="Register an app with bexio">
    At [developer.bexio.com](https://developer.bexio.com/). You need the `payroll_employee_edit`
    scope to create employees.
  </Step>

  <Step title="Configure the credentials">
    `BEXIO_CLIENT_ID`, `BEXIO_CLIENT_SECRET`, `BEXIO_REDIRECT_URI` and `BEXIO_SCOPES`. In production
    these belong in Key Vault — see [Environment variables](/operations/environment-variables).
  </Step>

  <Step title="Complete the OAuth flow">
    An administrator authorises the connection from **Settings → Integrations**. Tokens are stored
    encrypted at the application layer, never as plaintext.
  </Step>

  <Step title="Map existing employees">
    Reconciliation matches your employees against the bexio side and reports the ones that need a
    decision.
  </Step>

  <Step title="Enable ongoing sync">
    New hires flow through as part of the onboarding checklist.
  </Step>
</Steps>

## Turning it off

Set `FEATURE_BEXIO_SYNC=false` on installations that use the built-in payroll engine or
a different provider.

<Note>
  bexio sync and the built-in payroll engine are alternatives, not layers. Running both against the
  same population means two systems believe they own the payslip.
</Note>