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

# How to Download Reports

## Introduction

This guide is aimed at helping you generate Timesheet reports directly through API requests.

## Prerequisites

You will need:

* (required) Your domain name `{yourDomain}`, eg: "[https://myawesomecompany.ilucca.net](https://myawesomecompany.ilucca.net)".
* (required) An [API key](https://support.lucca.fr/hc/en-us/articles/115000084851) `{apiKey}` that has report generation rights.

## Guide

A `report` can only be generated from an existing `report-template`, referenced by its unique identifier `templateId`, for which your API key must have access to.

If an existing `report-template` is publicly available, you can generate a `report` from it.

But in most cases, you will need to create a dedicated `report-template` for your API key.

### 1. Create a report-template

As the resource is not yet documented, the easiest way is to create a new `report-template` through Lucca Timesheet user interface, then **copy-paste the generated payload to make your POST request `/report-templates` with your API key.**

For example :

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

{
  "id": 0,
  "blueprintId": "times",
  "name": "Rapport sur les temps",
  "columns": [
    {
      "kind": "ownerName",
      "name": "Nom complet",
      "description": "",
      "category": "owner",
      "isRequired": true,
      "isPeriodic": false,
      "isDefault": true
    },
    {
      "kind": "ownerDepartment",
      "name": "Département",
      "description": "",
      "category": "owner",
      "isRequired": false,
      "isPeriodic": false,
      "isDefault": true
    },
    {
      "kind": "attendanceTime",
      "name": "Temps de travail",
      "description": "",
      "category": "time",
      "isRequired": true,
      "isPeriodic": true,
      "isDefault": true
    },
    {
      "kind": "leavesDuration",
      "name": "Absences",
      "description": "",
      "category": "time",
      "isRequired": false,
      "isPeriodic": true,
      "isDefault": true
    },
    {
      "kind": "theoreticalWorkingTime",
      "name": "Temps théorique",
      "description": "",
      "category": "time",
      "isRequired": false,
      "isPeriodic": true,
      "isDefault": true
    },
    {
      "kind": "overUnderTime",
      "name": "Écart",
      "description": "",
      "category": "time",
      "isRequired": false,
      "isPeriodic": true,
      "isDefault": true
    }
  ],
  "periodicity": "quarterly",
  "defaultPeriod": "thisYear",
  "total": {
    "kind": "manager",
    "name": "Par manager"
  },
  "onlyShowTotals": false,
  "isPublic": false,
  "collaborators": [],
  "filters": [
    {
      "kind": "ownerLegalEntityId",
      "name": "Établissements",
      "category": "owner",
      "values": [
        1
      ]
    },
    {
      "kind": "timesheetStatuteId",
      "name": "Réglementaires",
      "category": "timesheet",
      "values": [
        4,
        16
      ]
    }
  ]
}
```

The created `report-template` `{id}` will be answered in reponse.

### 2. Generate a new report from this report-template

You can now generate a report through `/timmi-timesheet/api/reports` with :

* The `report-template` `{id}` you just created.
* The start date of the report to generate `{reportStartDate}`. If left null, default date from the `report-template` is applied.
* The end date of the report to generate `{reportEndDate}`. If left null, default date from the `report-template` is applied.

These will be used as parameters in the following request:

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

{
  "templateId": {templateId},
  "startsOn": {reportStartDate},
  "endsOn": {reportEndDate}
}
```

Which response should look like:

```json theme={null}
{
  "id": 1,
  "status": "pending",
  ...
}
```

This response contains, among other things:

* the identifier `(integer) id` of the created report, to be kept carefully as the `{reportId}`
* the status `(string) status` of the generation of its content, which is an enum:

```yaml theme={null}
ReportStatus:
  type: string
  enum:
    - "pending"
    - "done"
    - "error"
```

#### Background process

The generation of a report content is a background process. As long as this process is not complete, the report status stays `pending`. Once the report is complete, its status is set to `done`. May an error be encountered while generating its content, then its status is set to `error`.

The report content can only be viewed and downloaded once it is `done`.
The generation of the report is an asynchronous process. In practice, when the POST request is received, the server immediately responds with a `200 OK` if successful, otherwise an error code is displayed.

### 3. Track report background building progress

The next request should be repeated at regular intervals (say, every 10 seconds) until the response indicates a `done` status (rather than `pending`).

If request is met with an error, the status `error` will be returned. In this case, it will be necessary to try creating a new report and if the error occurs again, please contact our support.

Here, `{reportId}` should be equal to the identifier of report recovered in response to the previous POST:

```http theme={null}
GET /timmi-timesheet/api/reports/{reportId} HTTP/1.1
Domain: {yourDomain}
Authorization: lucca application={apiKey}
Accept: application/json

Response:
{
  ...,
  "status": "done"
}
```

### 4. Download the finalized report data

Once the content of the report is generated (status `done`), it can be downloaded in a CSV file:

```http theme={null}
GET /timmi-timesheet/api/reports/{reportId}/download-csv HTTP/1.1
```

Or in Excel format:

```http theme={null}
GET /timmi-timesheet/api/reports/{reportId}/download-excel HTTP/1.1
```

Reports expire after 24h, and will be deleted as soon as another report from any report-template is generated.