> ## Documentation Index
> Fetch the complete documentation index at: https://developers.luccasoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How to Send Time-Punches from Your Own Punch Clock

## Introduction

**This guide is aimed at helping you send the clock-ins and clock-outs of your own punch clock to Lucca Timesheet.**
Lucca Timesheet then computes the worked time of your employees from these time-punches, as it does for
time-punches made on a Lucca punch clock.

## Prerequisites

You will need:

* Your domain name `{yourDomain}`, eg: "[https://myawesomecompany.ilucca.net](https://myawesomecompany.ilucca.net)".
* An [API key](https://support.lucca.fr/hc/en-us/articles/115000084851) `{apiKey}` with the
  "Edit time-punches" permission on all departments (see step 1).
* Employees on a clock-in time-tracking profile.
* The Lucca identifier of each employee who clocks in and out on your punch clock (see step 2).

## Guide

### 1. Create an API key

In your Lucca account settings, [create a new API key](https://support.lucca.fr/hc/en-us/articles/115000084851)
dedicated to your punch clock integration.

Then, in the role of this API key (listed at the very bottom of the roles administration page, under the same name
as the key), grant the **"Edit time-punches"** permission ("Modifier les pointages" in French) in Lucca Timesheet,
**on all departments**, so that the key can send time-punches for any employee.

Learn more about API keys and how to use them on the [Authentication](https://developers.luccasoftware.com/api-reference/legacy/authentication.md) page.

> [!TIP]
>
> Create one API key per integration and set its "technical contact": we will use it to reach you in case of
> technical problems or API changes.

### 2. Map your punch clock identifiers to Lucca employees

Your punch clock identifies employees with its own identifiers: badge identifiers, personal PIN codes, logins, etc.
Lucca identifies them with their Lucca employee identifier, and each time-punch you send must reference it.

Your integration must therefore maintain a mapping between the identifiers of your punch clock and the identifiers
of Lucca employees. When an employee clocks in or out, use this mapping to tell Lucca which employee the time-punch
belongs to.

> [!WARNING]
>
> **Lucca does not store your punch clock identifiers.** The endpoints documented here do not manage badge identifiers,
> PIN codes or logins: keeping the mapping up to date (new employees, lost badges, etc.) is up to your integration.

Lucca employees and their identifiers can be retrieved through the [users API](https://developers.luccasoftware.com/api-reference/legacy/directory/user.md).

### 3. Send each time-punch

Each time an employee clocks in or out, send a POST request to the `/timmi-timesheet/api/time-punches` endpoint.
Please refer to the [API reference](https://developers.luccasoftware.com/api-reference/legacy/timmi-timesheet/time-punches/create-time-punch.md).

* `employee`: `{ "id": ... }`, with the Lucca identifier of the employee.
* `clientWalledTime`: the date and time the employee clocked in or out, **in local time without any offset**
  ("Z", "+01:00", etc...).
* `direction`: `in` for a clock-in, `out` for a clock-out.

```http theme={null}
POST /timmi-timesheet/api/time-punches HTTP/1.1
Host: {yourDomain}
Authorization: lucca application={apiKey}
Content-Type: application/json

{
  "employee": { "id": "416" },
  "clientWalledTime": "2026-10-22T08:04:23",
  "direction": "in"
}
```

The response is a `201 Created` with the created time-punch, or a `200 OK` with the existing time-punch if it was
already sent (see step 4).

> [!NOTE]
>
> **Resolved time.** Lucca resolves the `clientWalledTime` in the time zone of the employee's establishment on that
> date, and returns it as the `resolvedTime` of the time-punch, with its offset. For an employee of a Paris
> establishment, the time-punch above has a `resolvedTime` of `2026-10-22T08:04:23+02:00`.

### 4. Retry time-punches that were not sent

Your punch clock will sometimes fail to send a time-punch: network outage, timeout, temporary error on Lucca's side.
Keep every time-punch in a local queue until Lucca acknowledges it, and retry it according to the response.

**Sending the same time-punch twice is safe.** Lucca never creates the same time-punch twice: if you send a
time-punch again with the same `employee`, `clientWalledTime` and `direction`, Lucca answers `200 OK` with the existing
time-punch, instead of creating a new one.

So, when you retry a time-punch, **send exactly the same request body**. In particular, keep the original
`clientWalledTime`: never replace it with the time of the retry, or Lucca will create a second time-punch.

Then, depending on the response:

| Response | Meaning | What to do |
| - | - | - |
| `201 Created` | The time-punch was created. | Remove it from your queue. |
| `200 OK` | The time-punch had already been created, for instance by a previous attempt whose response was lost. | Remove it from your queue. |
| No response, timeout, `429` or `5xx` | The time-punch may or may not have been created. | Keep it in your queue, and retry it later with the same body. Wait longer between each attempt (e.g. 1 min, 2 min, 4 min…). |
| `400 Bad Request` | A required property is missing, or the employee is not on a clock-in time-tracking profile on this date. | Do not retry as is: fix the request or the employee's setup, then send it again. |
| `401 Unauthorized` | The API key is missing or invalid. | Do not retry: check the API key, then send your queue again. |
| `403 Forbidden` | The API key does not have the "Edit time-punches" permission on this employee. | Do not retry as is: fix the permissions of the API key (see step 1), then send it again. |

> [!WARNING]
>
> **Do not retry an archived time-punch.** Lucca only recognizes a previously sent time-punch if it is not archived. If a
> time-punch was archived in the meantime, for instance by a manager in Lucca, sending it again creates a new one.

### 5. Check the time-punches sent

You can retrieve the time-punches for a given period and set of employees with a GET request to the same endpoint.

```http theme={null}
GET /timmi-timesheet/api/time-punches?resolvedDate=2026-10-01--2026-10-31&employee.id=416&limit=100 HTTP/1.1
Host: {yourDomain}
Authorization: lucca application={apiKey}
Accept: application/json
```

If the response contains a `links.next.href`, call it to get the next page.


## Related topics

- [Legacy API Changelog](https://developers.luccasoftware.com/api-reference/legacy/changelog.md)
- [Create a time-punch](https://developers.luccasoftware.com/api-reference/legacy/timmi-timesheet/time-punches/create-time-punch.md)
- [Get a time-punch](https://developers.luccasoftware.com/api-reference/legacy/timmi-timesheet/time-punches/get-time-punch.md)
- [List time-punches](https://developers.luccasoftware.com/api-reference/legacy/timmi-timesheet/time-punches/list-time-punches.md)
- [Archive or restore a time-punch](https://developers.luccasoftware.com/api-reference/legacy/timmi-timesheet/time-punches/archive-time-punch.md)