Payroll integration
Lucca to AFAS integration: employees and pay of the Dutch entity from Lucca in AFAS
With an integration between Lucca and AFAS Profit, new employees, contract changes, salaries and departures of the Dutch entity reach AFAS automatically from Lucca, with the start and end dates from Lucca. A hire already prepared in Lucca is thus in AFAS in time for the first payroll run.
What the integration does
Organisations with a French parent or branch that run HR in Lucca and pay their Dutch employees in AFAS Profit enter every hire and rise twice. Lucca is set up around French payroll concepts, so payroll has to work out what a pay item means for the Dutch payslip.
- HR records an employment at the Dutch legal entity in Lucca, often weeks before the start date.
- KoppelHet fetches the employments of that entity that were updated since the previous run.
- The employee reaches AFAS with personal data, BSN, bank account, contract, job and salary.
- KoppelHet puts the AFAS number back on the employment in Lucca as the key for later changes.
- An end date in Lucca becomes the end date of the contract in AFAS.
What to watch for with Lucca and AFAS Profit
- Lucca derives the legal entity of an employment from the establishment in the first job position. KoppelHet filters employments on the Dutch entity and checks at the initial load that every Dutch employee really falls under it, because a wrongly chosen establishment puts someone in another country.
- Lucca has a French and a Swiss format for the social security number, and a free field without validation for all other countries. A BSN is therefore unvalidated in Lucca; KoppelHet runs the Dutch check-digit test before the number goes to AFAS and reports a wrong number.
- An employee with an employment that has yet to start has the status upcoming in Lucca. KoppelHet already puts such a person in AFAS once the contract is fixed, so the first month is not missed.
- An employment in Lucca has a field for the number in another system. KoppelHet puts the AFAS employee number there, so HR in Lucca can see which employee is linked to which AFAS employee.
- A fixed pay item in Lucca can be an amount or a quantity, depending on its kind, and is in the currency of the establishment. KoppelHet only takes the kinds agreed as salary or fixed allowance and checks that the establishment works in euro.
- In Lucca compensation is still in the older API generation, employees and employments in the new one. KoppelHet uses per part the generation that covers it and tracks when Lucca moves compensation to the new API, so the integration can move along in time.
- Lucca allows fifty requests per minute per environment, shared by all integrations on that environment. KoppelHet fetches employments and job positions together and only requests updated records, so other integrations with Lucca do not stall.
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
What if HR changes an employment retroactively in Lucca?
The employment gets a new update timestamp in Lucca. KoppelHet takes the change along with the date from Lucca, and AFAS settles the difference.
What does payroll fill in AFAS itself?
Collective agreement, scale and step, payroll tax credit and pension. Lucca does not know these Dutch concepts, and the integration does not overwrite them.
Does leave from Lucca go along too?
Not in this integration. Leave and absence from Lucca to AFAS is a separate flow and can be added later as an extension.
Technical details for IT
For those who want to know how it works under the hood: APIs, fields and sources used.
- Lucca API (v5) for employees, employee-personal-records (insuranceNumber with format frenchSSN, swissSSN or other; bankAccount with format iban), employments (filters legalEntity.id and lastUpdatedAt, start.date, end.date, remoteId) and job-positions. Compensation through the older Compensation API (fixed-items with natureId, amount, startsOn, endsOn per work contract and amendment). OAuth 2.0; 50 requests per minute per tenant, 429 with Retry-After.
- AFAS through the KnEmployee UpdateConnector with AfasContract, AfasSalary and AfasBankInfo.
Which fields are transferred
The key fields. The full mapping is agreed per customer.
| Field in Lucca | Field in AFAS Profit | Notes |
|---|---|---|
employee.id | Vrij veld in AFAS | Fixed key |
givenName en familyName | Voornaam, voorvoegsel en achternaam | |
employee-personal-record.insuranceNumber (format other) | BSN (SoSe) | KoppelHet validates the number |
employee-personal-record.bankAccount (format iban) | Bankrekening (AfasBankInfo) | |
employment.start.date | Begindatum contract (DaBe) | |
employment.end.date | Einddatum contract (DaEn) | Last working day included |
job-position: jobTitle, department | Functie (FuId) en organisatorische eenheid (DpId) | Through a lookup table |
fixed-item (nature basissalaris): amount, startsOn | Salaris (EmSa) met ingangsdatum | |
AFAS-medewerkernummer | employment.remoteId | Back to Lucca |
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
ASLucca → Arbodienst (SIVI)
Lucca to the occupational health service via SIVI: confirmed sickness per half day as absence reports
Lucca → DATEV
Lucca to DATEV integration: German joiners, leavers and master data from Lucca to DATEV