<!-- markdownlint-disable MD024 -->
# Gestions des fichiers justificatifs pour le module Assiduité

Le fonctionnement de l'importation / lecture des fichiers justificatifs est légèrement plus complexe que l'utilisation de l'API seule. Voici les différentes informations à savoir pour correctement utiliser les fichiers justificatifs.

Afin de bien comprendre les différentes informations, merci de lire d'abord la documentation de l'API Assiduité : [Documentation Assiduité](ScoDoc9API.md#api-assiduite)

## Importer un fichier

L'importation d'un fichier pour un justificatif se fait en deux temps :

* Créer un nouvel objet justificatif à l'aide de l'API
* Envoyer le fichier sur le serveur ScoDoc

### Envoyer le fichier sur le serveur ScoDoc

Dans un premier temps il faut créer un objet justificatif à l'aide de l'API.

Dans un second temps il faut envoyer le fichier sur le serveur à l'aide d'une requête `POST`.

#### Exemple en Python

##### Script d'envoi du justificatif

> `token` est le même token que pour le reste de l'API

```py
    data = {
        "etat": "attente",
        "date_debut": "2022-10-27T08:00",
        "date_fin": "2022-10-27T12:00",
    }
    # la route de l'api est : /justificatif/<etudid:int>/create
    r = requests.post(API_URL + "/justificatif/123/create", json=data, headers=token)
    print(r.json)
```

##### Réponse

```json
{
    "justif_id" : 424242
}
```

##### Script d'envoi du fichier

> `token` est le même token que pour le reste de l'API

```py
with open('exemple.txt', 'rb') as f:
    # la route pour importer est : api/justificatif/<justif_id:int>/import
    r = requests.post(API_URL + "/justificatif/424242/import", files={"exemple.txt": f}, headers=token)
    print(r.json)
```

##### Réponse

```json
{
    "filename" : "exemple.txt"
}
```

Veillez à bien noter le nom de fichier renvoyé car c'est le nom coté "server", il sera à utiliser lors que vous souhaitez récupérer le fichier
ou lorsque vous voudrez le supprimer

## Télécharger un fichier

Pour télécharger un fichier de justificatif rien de plus simple

### Une simple requête POST

* **Méthode:** POST
* **Permission: `ScoView`**
* **Paramètres:**
  * `justif_id`
  * `filename`
* **Routes:** `/justificatif/<justif_id:int>/export/<filename>`
* **Exemple d'utilisation:** `/api/justificatif/424242/export/exemple.txt`
* **Résultat:** télécharge directement le fichier

## Supprimer un fichier

Pour supprimer un fichier il suffit d'envoyer une requête post sur le justificatif, avec un json correct

### Script de suppression du fichier

> `token` est le même token que pour le reste de l'API

```py
# la route pour supprimer est : api/justificatif/<justif_id:int>/remove

d = {

    "remove": "list",
    "filenames": [
        "exemple.txt"
    ]
}

# ou

d = {

    "remove": "al",
}

r = requests.post(API_URL + "/justificatif/424242/remove", data=d, headers=token)
print(r.json)
```

#### Réponse

```json
{
    "response" : "removed"
}
```
