Payroll integration
Lucca to Loket integration: employment, job and working-time arrangement from Lucca ready for the Loket payroll run
With an integration between Lucca and Loket, a new employee of the Dutch establishment arrives from Lucca as a concept employee in Loket, and end date, job, working-time arrangement and bank account reach the employment with their effective date. Payroll only completes the Dutch payroll details; a BSN or account that is not right comes back as an alert first.
What the integration does
Organisations that run HR in Lucca, often with a head office in France or Switzerland, and have Dutch employees paid in Loket retype data from Lucca into Loket. Lucca is set up for French and Swiss social security numbers and free-text job titles, which regularly leads to rejected or incomplete records in Loket.
- Lucca reports a changed employment, job position or personal record; KoppelHet fetches that employee's current data.
- A new employee at the Dutch entity becomes a concept employee in Loket, even if the employment in Lucca is still upcoming.
- The payroll bureau completes collective agreement, pay, payroll tax credit and pension and converts the concept.
- A new job position with a different working-time arrangement becomes a new working hours record from the effective date.
- An end date on the employment ends the employment in Loket as of that last day.
What to watch for with Lucca and Loket
- The social security number in Lucca has the formats French, Swiss or other, and Lucca only validates the first two. A BSN therefore sits under other without any check. Because the BSN is separately authorised in Loket and the tax return relies on it, KoppelHet checks the number with the Dutch eleven test before it goes to Loket.
- Lucca stores a bank account as an IBAN or as a local account number with a bank code. An IBAN goes without spaces to the SEPA payment details in Loket. A local number, such as an account in the United States, becomes a non-SEPA payment in Loket, so the payroll bureau does not have to enter it by hand.
- Lucca's working-time arrangement is only a reference with a name in the API, such as a thirty-five hours per week arrangement; there is no hours field. Loket calculates with a shift with full-time hours and possibly deviating hours per week. KoppelHet translates each arrangement with a table into those Loket values, and an unknown arrangement becomes an alert.
- Every job position in Lucca indicates which attributes changed compared with the previous position. KoppelHet uses that list to only send what affects Loket: a different working-time arrangement becomes a new working hours record, a different job title a different job. A new manager or department causes no change in Loket.
- A job title in Lucca is free text of over a thousand characters. A job in Loket has a description of at most fifty characters and comes from the employer's job list. KoppelHet links titles to existing Loket jobs through a lookup table, so dozens of near-identical jobs do not appear.
- An employment in Lucca without an end date is permanent; with an end date it is fixed-term and that date is the last day. KoppelHet therefore sets the duration on the concept to fixed or indefinite. For a fixed-term contract the end date comes along, so the payroll bureau does not have to ask about the duration itself.
How we build and run it
- The integration runs on the KoppelHet platform, hosted in a data centre in the EU.
- Every sync and every error is visible in the functional log; on an error your administrator is notified.
- A change that cannot go through is not half-applied but queued for another attempt.
- KoppelHet is ISO 27001 certified. Data travels encrypted and stays on the platform no longer than needed.
- After go-live we manage the integration and adjust it when your process changes.
- The integration fits next to your existing integration layer. Only the fields in the design are transferred; the platform keeps no register of its own.
Implementation and price
This is not an app you switch on. We build the integration for your organisation on our platform, with building blocks we reuse on every project. So it is custom work that does not start from scratch.
A consultant prepares the intake and analyses both systems. We then record the mapping and exceptions field by field, test in the test or acceptance environment and go live at a moment you choose. Costs are a one-off amount for the setup and a monthly amount for platform, monitoring and support.
Frequently asked questions
Does salary from Lucca go along?
Not in the first version: compensation in Lucca sits in an older, separate API and is not active for every customer. The payroll bureau sets pay when converting the concept; salary from Lucca can be added later as an extension.
What if a job title is not in the table?
Then the rest of the change goes through and the payroll bureau gets an alert to choose or add the job.
Does this work if a payroll bureau manages Loket?
Yes. The bureau gives the integration access to your employer in Loket, including the BSN permission.
Technical details for IT
For those who want to know how it works under the hood: APIs, fields and sources used.
- Lucca API (v5, beta) with webhooks through webhook-endpoints. employments (legalEntity derived from the business-establishment of the first job position, status upcoming, active or deactivated, start.date, end.date empty when permanent), job-positions (startsOn, endsOn read-only, jobTitle up to 1024 characters, workingTimeArrangement, updatedAttributes), working-time-arrangements (opt-in, name and holiday calendar only), employee-personal-records (insuranceNumber with format frenchSSN, swissSSN or other; bankAccount with format iban or other).
- Loket through the REST API with OAuth - POST conceptemployees (employmentDurationType, commissionUntilDate), PUT citizenservicenumber, workinghours (shift, deviatingHoursPerWeek; chain validation on start date), functions per employer (description at most 50 characters), paymentinformationsepa (IBAN without spaces) and paymentinformationnonsepa, PATCH terminate.
Which fields are transferred
The key fields. The full mapping is agreed per customer.
| Field in Lucca | Field in Loket | Notes |
|---|---|---|
employee.id | Personeelsnummer of vrij veld | Fixed key |
employment.legalEntity | Werkgever | Derived from the establishment of the first job position |
employment.start.date, end.date | Begindatum dienstverband en einddatum contract | Empty end means indefinite |
jobPosition.jobTitle | Functie | Through a lookup table to the employer's job list |
jobPosition.workingTimeArrangement | Arbeidstijd (rooster of afwijkende uren per week) | Lookup table on the arrangement name |
personalRecord.insuranceNumber (format other) | Burgerservicenummer | After the Dutch eleven test |
personalRecord.bankAccount | Betaalgegevens SEPA of niet-SEPA | |
personalRecord.birthDate | Geboortedatum |
Related
Lucca → Active Directory
Lucca to Active Directory integration: accounts in your own domain based on Lucca
Lucca → ADP iHCM
Lucca to ADP iHCM integration: fixed and variable pay from Lucca Compensation to Dutch ADP payroll
Lucca → AFAS Profit
Lucca to AFAS integration: employees and pay of the Dutch entity from Lucca in AFAS
ASLucca → Arbodienst (SIVI)
Lucca to the occupational health service via SIVI: confirmed sickness per half day as absence reports