DocScoDoc/docs/ScoDoc9API.md

# API pour ScoDoc 9

!!! warning "Attention"
    *Page générée par la commande `flask gen-api-doc`. Ne pas modifier manuellement.*


L'API ScoDoc permet à des applications tierces d'interroger ScoDoc. Elle offre
un accès aux objets de l'application via une API REST.

Les composants internes de ScoDoc, et notamment le schéma de la base de données,
sont susceptibles d'évoluer à tout moment sans préavis: il est vivement
déconseillé d'écrire une extension ne passant pas par l'API. Vous ne devez même
pas supposer qu'il existe une base de données SQL.

La version ScoDoc 9 a introduit une nouvelle API avec un nouveau mécanisme d'authentification.
**Les clients de l'ancienne API ScoDoc 7 doivent être adaptés pour fonctionner avec ScoDoc 9.**

Cette API est encore incomplète: n'hésitez pas à demander de nouveaux accès ([contacts](Contact.md))
(et canal `#API` du Discord développeurs si vous y avez accès).

L'API fournit des données JSON, sauf exception (bulletins PDF par exemple).

Les objets ScoDoc manipulables sont identifiés par des id numériques.

* `etudid` : étudiant
* `formation_id` : un programme de formation (page "programmes");
* `ue_id` : une UE dans un programme;
* `matiere_id` : une matière dans un programme;
* `module_id` : un module dans un programme;
* `moduleimpl_id` : un module réalisé dans un semestre;
* `formsemestre_id` : un "semestre" de formation.

(pour plus de précisions, voir le [guide développeurs](GuideDeveloppeurs.md))

L'URL complète est de la forme:
`https://scodoc.example.com/ScoDoc/api/<fonction>`.
(<fonction> à choisir dans [Référence](#reference))

## Configuration de ScoDoc pour utiliser l'API

Il est nécessaire de disposer d'un compte utilisateur avec les droits adéquats.

Les droits à accorder dépendent des fonctionnalités nécessaires. la permission
`ScoView` est généralement suffisante car elle permet toutes les consultations.
Cependant si, par l'API, on veut effectuer des opérations de modification ou
encore consulter les comptes utilisateurs, d'autres droits (`ScoChangeGroups`,
`UsersView`, `ScoSuperAdmin`, ...) peuvent être requis. La consultation du
[tableau récapitulatif](#tableau-recapitulatif-des-entrees-de-lapi) ou la ligne
`permission`de chaque entrée vous donnera la permission requise pour chaque
opération.

En général, il est recommandé de créer un rôle, de lui attribuer les permissions
que l'on veut utiliser, puis de créer un utilisateur ayant ce rôle.

En ligne de commande, cela peut se faire comme suit (voir détail des commandes
[sur le guide de configuration](GuideConfig.md)).

```bash
# se connecter comme utilisateur scodoc
su - scodoc

# Créer un rôle
flask create-role LecteurAPI
# Lui donner les droits nécessaires: ici ScoView
flask edit-role LecteurAPI -a ScoView

# Créer un nouvel utilisateur avec ce rôle:
flask user-create lecteur_api LecteurAPI @all

# Ou bien, si on veut utiliser un compte existant:
#   associer notre rôle à un utilisateur
flask user-role lecteur_api -a LecteurAPI


# Au besoin, changer le mot de passe de l'utilisateur
# (on aura besoin de ce mot de passe dans la configuration du client d'API)
flask user-password lecteur_api
...
```

Si vous êtes intéressé par le développement, voir

* [la section sur les tests unitaires de l'API](TestsScoDoc.md#tests-de-lapi-scodoc9);
* [la documentation développeurs](GuideDeveloppeurs.md) et sur les [vues de l'API](DevInternals.md#vues-de-lapi-et-permissions).

!!! note

    * Si vous utilisez le CAS, pensez à laisser les comptes utilisateurs API se
    connecter via ScoDoc sans CAS. Pour cela, cocher l'option
    *Autorise connexion via CAS si CAS est activé* et décocher `Autorise connexion via CAS`
    dans leur formulaire de configuration.

    * Si l'utilisateur est associé à un département (cas des comptes créés via l'interface Web),
    il ne pourra accéder à l'API que via une *route départementale*, c'est à dire une route comprenant
    l'acronyme de son département, de la forme `https://...//ScoDoc/DEPARTEMENT/api/...`.

## Essais avec HTTPie

[HTTPie](https://httpie.io/) est un client universel livre et gratuit très commode, disponible
pour Windows, Linux, en ligne de commande ou interface graphique.

Exemple d'utilisation en ligne de commande et interroger votre ScoDoc pour
obtenir la liste des départements:

```bash
http -a USER:PASSWORD POST  'http://localhost:5000/ScoDoc/api/tokens'
```

Qui affiche:

```text
HTTP/1.1 200 OK
Content-Length: 50
Content-Type: application/json
Date: Thu, 05 May 2022 04:29:33 GMT

{
    "token": "jS7iVl1234cRDzboAfO5xseE0Ain6Zyz"
}
```

(remplacer `USER:PASSWORD` par les identifiants de votre utilisateur et adapter
l'URL qui est ici celle d'un client local sur le serveur de test).

Avec ce jeton (*token*), on peut interroger le serveur:

```bash
http GET http://localhost:5000/ScoDoc/api/departements "Authorization:Bearer jS7iVlH1234cRDzboAfO5xseE0Ain6Zyz"
```

qui affiche par exemple:

```text
HTTP/1.1 200 OK
Content-Length: 151
Content-Type: application/json
Date: Thu, 05 May 2022 05:21:33 GMT

[
    {
        "acronym": "TAPI",
        "date_creation": "Wed, 04 May 2022 21:09:25 GMT",
        "description": null,
        "id": 1,
        "visible": true
    }
]
```

## Fonctions d'API ScoDoc 9

La documentation ci-dessous concerne la nouvelle API, disponible à partir de la
version de ScoDoc 9.3.25.

### Accès à l'API REST

L'API est accessible à l'adresse:
`https://scodoc.monsite.tld/ScoDoc/api/<fonction>`, et aussi via les *routes
départementales* de la forme
`https://scodoc.monsite.tld/ScoDoc/<dept_acronyme>/api/<fonction>` pour un accès
avec des droits restreints au département indiqué. La liste des `<fonctions>` est
donnée ci-dessous dans [Référence](#reference).

#### Authentification

Lors de votre authentification (*connexion avec login et mot de passe*) à Scodoc, il
vous sera attribué un jeton (token jwt *généré automatiquement*) vous permettant
d'utiliser l'api suivant les droits correspondant à votre session.

Pour obtenir le jeton, il faut un compte sur ScoDoc (`user_name`et `password`).
Les autorisations et rôles sont gérés exactement comme pour l'application.

Exemple avec `curl` (un outil en ligne de commande présent sur la plupart des
systèmes, voir plus haut pour la même chose avec la commande `http`):

```bash
curl -u user_name:password --request POST  https://SERVEUR/ScoDoc/api/tokens
```

où `SERVEUR` est l'adresse (IP ou nom) de votre serveur.
La réponse doit ressembler à ceci:

```json
{
  "token": "LuXXxk+i74TXYZZl8MulgbiCGmVHXXX"
}
```

Vous trouverez dans `/opt/scodoc/tests/api/exemple-api-basic.py` un exemple
complet en python d'interrogation de l'API.

#### Codes HTTP

Chaque appel à l'API donne lieu à une réponse retournant un code spécifique en
fonction du résultat obtenu. L'analyse de ce code vous permet de vous assurer
que la requête a été traitée avec succès.

Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succès
par le serveur ScoDoc.

* [200](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/200) : OK.
* [401](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/401) : Authentification nécessaire. (jeton non précisé ou invalide)
* [403](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/403) : Action
  non autorisée pour l'utilisateur associé au jeton.
* [404](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/401) : Adresse
  incorrecte, paramètre manquant ou invalide, ou objet inexistant.
* [500](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/500) : Erreur
  inconnue côté serveur.

## Règles générales

* une route s'écrit comme une suite de noms et d'identifiants;
* les noms token, département, formation, formsemestre, groupe, etudiant,
  bulletin, absence, logo, programme, évaluation, résultat, décision désignent
  des types d'objets;
* les noms (verbes ou groupes verbaux): set_etudiant, remove_etudiant, query,
  create, delete, edit, order sont des actions;
* les noms restants (ids, courants, long, ...) sont des options, les autres noms
  sont des options ou des actions;
* le dernier nom apparaissant sur une route donne le type d'objet renvoyé. Ce
  nom peut apparaître au singulier ou au pluriel.
  * au singulier un seul objet est renvoyé, si aucun objet n'est trouvé, retourne un 404;
  * au pluriel une collection d'objets est renvoyée, si aucun objet n'est
    trouvé, retourne une collection vide.
* un type d'objet au singulier est généralement suivi immédiatement de son
  identifiant (unique). Exception: pour un étudiant, on peut également utiliser
  le NIP ou l'INE (qui ne sont pas uniques dans la base car un étudiant de même
  INE/NIP peut passer par plusieurs départements).

## Référence

La [carte syntaxique](#carte-syntaxique) vous permet de retrouver une entrée à
partir de sa syntaxe (le `?` amène sur la documentation associée).

Le [tableau récapitulatif](#tableau-recapitulatif-des-entrees-de-lapi) vous
permet de rechercher une entrée à partir du résultat attendu.

### Carte syntaxique

<div style="overflow: scroll;">
   <div style="width: 1200px;">
       ![carte_syntaxique](img/API_Chart.svg)
   </div>
</div>

(carte générée avec `flask gen-api-doc`)

### Tableau récapitulatif des entrées de l'API

| Route | Méthode | Permission |
|---|---|---|
| [assiduite](#assiduite) | GET | ScoView |
| [assiduite_create](#assiduite_create) | POST | AbsChange |
| [assiduite_delete](#assiduite_delete) | POST | AbsChange |
| [assiduite_edit](#assiduite_edit) | POST | AbsChange |
| [assiduite_justificatifs](#assiduite_justificatifs) | GET | ScoView |
| [assiduites](#assiduites-query) | GET | ScoView |
| [assiduites_count](#assiduites_count-query) | GET | ScoView |
| [assiduites_create](#assiduites_create) | POST | AbsChange |
| [assiduites_edit](#assiduites_edit) | POST | AbsChange |
| [assiduites_evaluations](#assiduites_evaluations) | GET | ScoView |
| [assiduites_formsemestre](#assiduites_formsemestre-query) | GET | ScoView |
| [assiduites_formsemestre_count](#assiduites_formsemestre_count-query) | GET | ScoView |
| [assiduites_group](#assiduites_group-query) | GET | ScoView |
| [autorisation_inscription_delete](#autorisation_inscription_delete) | POST | EtudInscrit |
| [billets_absence_create](#billets_absence_create) | POST | Aucune permission requise |
| [billets_absence_delete](#billets_absence_delete) | POST | Aucune permission requise |
| [billets_absence_etudiant](#billets_absence_etudiant) | GET | Aucune permission requise |
| [bulletin](#bulletin) | GET | ScoView |
| [bulletins](#bulletins) | GET | ScoView |
| [decisions_jury](#decisions_jury) | GET | ScoView |
| [departement_by_acronym](#departement_by_acronym) | GET | ScoView |
| [departement_create](#departement_create) | POST | ScoSuperAdmin |
| [departement_delete](#departement_delete) | POST | ScoSuperAdmin |
| [departement_edit](#departement_edit) | POST | ScoSuperAdmin |
| [departement_etudiants](#departement_etudiants) | GET | ScoView |
| [departement_etudiants_by_id](#departement_etudiants_by_id) | GET | ScoView |
| [departement_formsemestres_courants](#departement_formsemestres_courants-query) | GET | ScoView |
| [departement_formsemestres_ids](#departement_formsemestres_ids) | GET | ScoView |
| [departement_formsemestres_ids_by_id](#departement_formsemestres_ids_by_id) | GET | ScoView |
| [departement_get](#departement_get) | GET | ScoView |
| [departement_logos](#departement_logos) | GET | ScoSuperAdmin |
| [departement_logos_by_id](#departement_logos_by_id) | GET | ScoSuperAdmin |
| [departements_ids](#departements_ids) | GET | ScoView |
| [departements_list](#departements_list) | GET | ScoView |
| [etudiant](#etudiant) | GET | ScoView |
| [etudiant_annotation](#etudiant_annotation) | POST | EtudInscrit |
| [etudiant_annotation_delete](#etudiant_annotation_delete) | POST | EtudInscrit |
| [etudiant_create](#etudiant_create) | POST | EtudInscrit |
| [etudiant_edit](#etudiant_edit) | POST | EtudInscrit |
| [etudiant_formsemestres](#etudiant_formsemestres) | GET | ScoView |
| [etudiant_get_photo_image](#etudiant_get_photo_image-query) | GET | ScoView |
| [etudiant_groups](#etudiant_groups) | GET | ScoView |
| [etudiants](#etudiants) | GET | ScoView |
| [etudiants_by_name](#etudiants_by_name) | GET | ScoView |
| [etudiants_courants](#etudiants_courants-query) | GET | ScoView |
| [evaluation_assiduites](#evaluation_assiduites) | GET | ScoView |
| [evaluation_create](#evaluation_create) | POST | EnsView |
| [evaluation_delete](#evaluation_delete) | POST | EnsView |
| [evaluation_notes](#evaluation_notes) | GET | ScoView |
| [evaluation_set_notes](#evaluation_set_notes) | POST | EnsView |
| [formation_export_by_formation_id](#formation_export_by_formation_id) | GET | ScoView |
| [formation_get](#formation_get) | GET | ScoView |
| [formation_module_edit](#formation_module_edit) | POST | EditFormation |
| [formation_module_get](#formation_module_get) | GET | ScoView |
| [formation_module_set_code_apogee](#formation_module_set_code_apogee) | POST | EditFormation |
| [formations](#formations) | GET | ScoView |
| [formations_ids](#formations_ids) | GET | ScoView |
| [formsemestre_edit](#formsemestre_edit) | POST | EditFormSemestre |
| [formsemestre_edt](#formsemestre_edt-query) | GET | ScoView |
| [formsemestre_etat_evaluations](#formsemestre_etat_evaluations) | GET | ScoView |
| [formsemestre_etud_desinscrit](#formsemestre_etud_desinscrit) | POST | EtudInscrit |
| [formsemestre_etud_inscrit](#formsemestre_etud_inscrit) | POST | EtudInscrit |
| [formsemestre_etudiants](#formsemestre_etudiants-query) | GET | ScoView |
| [formsemestre_get](#formsemestre_get) | GET | ScoView |
| [formsemestre_partitions](#formsemestre_partitions) | GET | ScoView |
| [formsemestre_programme](#formsemestre_programme) | GET | ScoView |
| [formsemestre_resultat](#formsemestre_resultat-query) | GET | ScoView |
| [formsemestre_set_apo_etapes](#formsemestre_set_apo_etapes) | POST | EditApogee |
| [formsemestre_set_elt_annee_apo](#formsemestre_set_elt_annee_apo) | POST | EditApogee |
| [formsemestre_set_elt_passage_apo](#formsemestre_set_elt_passage_apo) | POST | EditApogee |
| [formsemestre_set_elt_sem_apo](#formsemestre_set_elt_sem_apo) | POST | EditApogee |
| [formsemestre_set_partitions_order](#formsemestre_set_partitions_order) | POST | ScoView |
| [formsemestres_query](#formsemestres_query-query) | GET | ScoView |
| [group_create](#group_create) | POST | ScoView |
| [group_delete](#group_delete) | POST | ScoView |
| [group_edit](#group_edit) | POST | ScoView |
| [group_etudiants](#group_etudiants) | GET | ScoView |
| [group_etudiants_query](#group_etudiants_query-query) | GET | ScoView |
| [group_remove_etud](#group_remove_etud) | POST | ScoView |
| [group_set_edt_id](#group_set_edt_id) | POST | ScoView |
| [group_set_etudiant](#group_set_etudiant) | POST | ScoView |
| [groups_get_auto_assignment](#groups_get_auto_assignment) | GET | ScoView |
| [groups_save_auto_assignment](#groups_save_auto_assignment) | POST | ScoView |
| [justif_create](#justif_create) | POST | AbsChange |
| [justif_delete](#justif_delete) | POST | AbsChange |
| [justif_edit](#justif_edit) | POST | AbsChange |
| [justif_export](#justif_export) | POST | ScoView |
| [justif_import](#justif_import) | POST | AbsChange |
| [justif_justifies](#justif_justifies) | GET | AbsChange |
| [justif_list](#justif_list) | GET | ScoView |
| [justif_remove](#justif_remove) | POST | AbsChange |
| [justificatif](#justificatif) | GET | ScoView |
| [justificatifs](#justificatifs-query) | GET | ScoView |
| [justificatifs_dept](#justificatifs_dept-query) | GET | ScoView |
| [justificatifs_formsemestre](#justificatifs_formsemestre-query) | GET | ScoView |
| [logo_get_global](#logo_get_global) | GET | ScoSuperAdmin |
| [logo_get_local_dept_by_acronym](#logo_get_local_dept_by_acronym) | GET | ScoSuperAdmin |
| [logo_get_local_dept_by_id](#logo_get_local_dept_by_id) | GET | ScoSuperAdmin |
| [logo_list_globals](#logo_list_globals) | GET | ScoSuperAdmin |
| [moduleimpl_etud_desinscrit](#moduleimpl_etud_desinscrit) | POST | ScoView |
| [moduleimpl_etud_inscrit](#moduleimpl_etud_inscrit) | POST | ScoView |
| [moduleimpl_evaluations](#moduleimpl_evaluations) | GET | ScoView |
| [moduleimpl_inscriptions](#moduleimpl_inscriptions) | GET | ScoView |
| [moduleimpl_notes](#moduleimpl_notes) | GET | ScoView |
| [partition_create](#partition_create) | POST | ScoView |
| [partition_delete](#partition_delete) | POST | ScoView |
| [partition_edit](#partition_edit) | POST | ScoView |
| [partition_info](#partition_info) | GET | ScoView |
| [partition_order_groups](#partition_order_groups) | POST | ScoView |
| [partition_remove_etud](#partition_remove_etud) | POST | ScoView |
| [permissions_list](#permissions_list) | GET | UsersView |
| [referentiel_competences](#referentiel_competences) | GET | ScoView |
| [role_create](#role_create) | POST | ScoSuperAdmin |
| [role_delete](#role_delete) | POST | ScoSuperAdmin |
| [role_edit](#role_edit) | POST | ScoSuperAdmin |
| [role_get](#role_get) | GET | UsersView |
| [role_permission_add](#role_permission_add) | POST | ScoSuperAdmin |
| [role_permission_remove](#role_permission_remove) | POST | ScoSuperAdmin |
| [roles_list](#roles_list) | GET | UsersView |
| [token_get](#token_get) | POST | Aucune permission requise |
| [ue_assoc_niveau](#ue_assoc_niveau) | POST | EditFormation |
| [ue_desassoc_niveau](#ue_desassoc_niveau) | POST | EditFormation |
| [ue_edit](#ue_edit) | POST | EditFormation |
| [ue_set_code_apogee](#ue_set_code_apogee) | POST | EditFormation |
| [ue_set_code_apogee_rcue](#ue_set_code_apogee_rcue) | POST | EditFormation |
| [ue_set_parcours](#ue_set_parcours) | POST | EditFormation |
| [user_create](#user_create) | POST | UsersAdmin |
| [user_edit](#user_edit) | POST | UsersAdmin |
| [user_info](#user_info) | GET | UsersView |
| [user_password](#user_password) | POST | UsersAdmin |
| [user_role_add](#user_role_add) | POST | ScoSuperAdmin |
| [user_role_remove](#user_role_remove) | POST | ScoSuperAdmin |
| [users_info_query](#users_info_query-query) | GET | ScoView |
| [validation_annee_but_delete](#validation_annee_but_delete) | POST | EtudInscrit |
| [validation_dut120_delete](#validation_dut120_delete) | POST | EtudInscrit |
| [validation_formsemestre_delete](#validation_formsemestre_delete) | POST | ScoView |
| [validation_rcue_delete](#validation_rcue_delete) | POST | EtudInscrit |
| [validation_rcue_record](#validation_rcue_record) | POST | EtudInscrit |
| [validation_ue_delete](#validation_ue_delete) | POST | ScoView |

(table générée avec `flask gen-api-doc`)

#### Note sur les exemples d'utilisation

Pour uniformiser les résultats des exemples, ceux sont soumis à quelques post-traitements non réalisés par l'API.

- les clés sont triées (ce n'est pas toujours garanti);
- les listes de plus de 2 éléments sont tronquées à 2 éléments, la fin de la liste étant
    représentée par la notation en json '...';
- les dates (au format ISO) sont systématiquement remplacées par une date fixe et ne sont pas réalistes.

### API Assiduites

#### **`assiduite`**

* **Route:** `/ScoDoc/api/assiduite/<int:assiduite_id>`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** Retourne un objet assiduité à partir de son id

    Exemple de résultat:

    ```json
    {
        "assiduite_id": 1,
        "etudid": 2,
        "moduleimpl_id": 3,
        "date_debut": "2022-10-31T08:00+01:00",
        "date_fin": "2022-10-31T10:00+01:00",
        "etat": "retard",
        "desc": "une description",
        "user_id": 1 or null,
        "user_name" : login scodoc or null,
        "user_nom_complet": "Marie Dupont",
        "est_just": False or True,
    }
    ```

* **Exemple de résultat:** [assiduite.json](./samples/sample_assiduite.json.md)


#### **`assiduite_create`**

* **Routes:**
    * `/ScoDoc/api/assiduite/ine/<ine>/create`
    * `/ScoDoc/api/assiduite/nip/<nip>/create`
    * `/ScoDoc/api/assiduite/etudid/<int:etudid>/create`
    * `/ScoDoc/api/assiduite/<int:etudid>/create`
* **Méthode:** `POST`
* **Permission:** `AbsChange`
* **Description:** Enregistrement d'assiduités pour un étudiant (etudid)

* **Exemple de résultat:** [assiduite_create.json](./samples/sample_assiduite_create.json.md)


#### **`assiduite_delete`**

* **Route:** `/ScoDoc/api/assiduite/delete`
* **Méthode:** `POST`
* **Permission:** `AbsChange`
* **Description:** Suppression d'une assiduité à partir de son id

* **Exemple de résultat:** [assiduite_delete.json](./samples/sample_assiduite_delete.json.md)


#### **`assiduite_edit`**

* **Route:** `/ScoDoc/api/assiduite/<int:assiduite_id>/edit`
* **Méthode:** `POST`
* **Permission:** `AbsChange`
* **Description:** Edition d'une assiduité à partir de son id

* **Exemple de résultat:** [assiduite_edit.json](./samples/sample_assiduite_edit.json.md)


#### **`assiduite_justificatifs`**

* **Routes:**
    * `/ScoDoc/api/assiduite/<int:assiduite_id>/justificatifs/long`
    * `/ScoDoc/api/assiduite/<int:assiduite_id>/justificatifs`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** Retourne la liste des justificatifs qui justifient cette assiduité.

    Exemple de résultat:

    ```json
    [
        1,
        2,
        3,
        ...
    ]
    ```

* **Exemple de résultat:** [assiduite_justificatifs.json](./samples/sample_assiduite_justificatifs.json.md)


#### **`assiduites(-query)`**

* **Routes:**
    * `/ScoDoc/api/assiduites/ine/<ine>/query`
    * `/ScoDoc/api/assiduites/ine/<ine>`
    * `/ScoDoc/api/assiduites/nip/<nip>/query`
    * `/ScoDoc/api/assiduites/nip/<nip>`
    * `/ScoDoc/api/assiduites/etudid/<int:etudid>/query`
    * `/ScoDoc/api/assiduites/etudid/<int:etudid>`
    * `/ScoDoc/api/assiduites/<int:etudid>/query`
    * `/ScoDoc/api/assiduites/<int:etudid>`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Paramètres:**
    * `user_id` : l'id de l'auteur de l'assiduité
    * `est_just` : si l'assiduité est justifiée (fait aussi filtre abs/retard)
    * `moduleimpl_id` : l'id du module concerné par l'assiduité
    * `date_debut` : date de début de l'assiduité (supérieur ou égal)
    * `date_fin` : date de fin de l'assiduité (inférieur ou égal)
    * `etat` : etat de l'étudiant &rightarrow; absent, present ou retard
    * `formsemestre_id` : l'identifiant du formsemestre concerné par l'assiduité
    * `with_justif` : ajoute les justificatifs liés à l'assiduité
* **Description:** Retourne toutes les assiduités d'un étudiant

* **Exemple de résultat:** [assiduites.json](./samples/sample_assiduites.json.md)


#### **`assiduites_count(-query)`**

* **Routes:**
    * `/ScoDoc/api/assiduites/ine/<ine>/count/query`
    * `/ScoDoc/api/assiduites/ine/<ine>/count`
    * `/ScoDoc/api/assiduites/nip/<nip>/count/query`
    * `/ScoDoc/api/assiduites/nip/<nip>/count`
    * `/ScoDoc/api/assiduites/etudid/<int:etudid>/count/query`
    * `/ScoDoc/api/assiduites/etudid/<int:etudid>/count`
    * `/ScoDoc/api/assiduites/<int:etudid>/count/query`
    * `/ScoDoc/api/assiduites/<int:etudid>/count`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Paramètres:**
    * `user_id` : l'id de l'auteur de l'assiduité
    * `est_just` : si l'assiduité est justifiée (fait aussi filtre abs/retard)
    * `moduleimpl_id` : l'id du module concerné par l'assiduité
    * `date_debut` : date de début de l'assiduité (supérieur ou égal)
    * `date_fin` : date de fin de l'assiduité (inférieur ou égal)
    * `etat` : etat de l'étudiant &rightarrow; absent, present ou retard
    * `formsemestre_id` : l'identifiant du formsemestre concerné par l'assiduité
    * `metric` : la/les métriques de comptage (journee, demi, heure, compte)
    * `split` : divise le comptage par état
* **Description:** Retourne le nombre d'assiduités d'un étudiant.

* **Exemple de résultat:** [assiduites_count.json](./samples/sample_assiduites_count.json.md)


#### **`assiduites_create`**

* **Route:** `/ScoDoc/api/assiduites/create`
* **Méthode:** `POST`
* **Permission:** `AbsChange`
* **Description:** Création d'une assiduité ou plusieurs assiduites

* **Exemple de résultat:** [assiduites_create.json](./samples/sample_assiduites_create.json.md)


#### **`assiduites_edit`**

* **Route:** `/ScoDoc/api/assiduites/edit`
* **Méthode:** `POST`
* **Permission:** `AbsChange`
* **Description:** Edition de plusieurs assiduités



#### **`assiduites_evaluations`**

* **Routes:**
    * `/ScoDoc/api/assiduites/nip/<nip>/evaluations`
    * `/ScoDoc/api/assiduites/ine/<ine>/evaluations`
    * `/ScoDoc/api/assiduites/etudid/<int:etudid>/evaluations`
    * `/ScoDoc/api/assiduites/<int:etudid>/evaluations`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** Retourne la liste de toutes les évaluations de l'étudiant
    Pour chaque évaluation, retourne la liste des objets assiduités
    sur la plage de l'évaluation

    Exemple de résultat:

    ```json
    [
        {
            "evaluation_id": 1234,
            "assiduites": [
                {
                    "assiduite_id":1234,
                    ...
                },
            ]
        }
    ]

    ```

* **Exemple de résultat:** [assiduites_evaluations.json](./samples/sample_assiduites_evaluations.json.md)


#### **`assiduites_formsemestre(-query)`**

* **Routes:**
    * `/ScoDoc/api/assiduites/formsemestre/<int:formsemestre_id>/query`
    * `/ScoDoc/api/assiduites/formsemestre/<int:formsemestre_id>`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Paramètres:**
    * `user_id` : l'id de l'auteur de l'assiduité
    * `est_just` : si l'assiduité est justifiée (fait aussi filtre abs/retard)
    * `moduleimpl_id` : l'id du module concerné par l'assiduité
    * `date_debut` : date de début de l'assiduité (supérieur ou égal)
    * `date_fin` : date de fin de l'assiduité (inférieur ou égal)
    * `etat` : etat de l'étudiant &rightarrow; absent, present ou retard
    * `formsemestre_id` : l'identifiant du formsemestre concerné par l'assiduité
* **Description:** Retourne toutes les assiduités du formsemestre

* **Exemple de résultat:** [assiduites_formsemestre.json](./samples/sample_assiduites_formsemestre.json.md)


#### **`assiduites_formsemestre_count(-query)`**

* **Routes:**
    * `/ScoDoc/api/assiduites/formsemestre/<int:formsemestre_id>/count/query`
    * `/ScoDoc/api/assiduites/formsemestre/<int:formsemestre_id>/count`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Paramètres:**
    * `user_id` : l'id de l'auteur de l'assiduité
    * `est_just` : si l'assiduité est justifiée (fait aussi filtre abs/retard)
    * `moduleimpl_id` : l'id du module concerné par l'assiduité
    * `date_debut` : date de début de l'assiduité (supérieur ou égal)
    * `date_fin` : date de fin de l'assiduité (inférieur ou égal)
    * `etat` : etat de l'étudiant &rightarrow; absent, present ou retard
    * `formsemestre_id` : l'identifiant du formsemestre concerné par l'assiduité
    * `metric` : la/les métriques de comptage (journee, demi, heure, compte)
    * `split` : divise le comptage par état
* **Description:** Comptage des assiduités du formsemestre

* **Exemple de résultat:** [assiduites_formsemestre_count.json](./samples/sample_assiduites_formsemestre_count.json.md)


#### **`assiduites_group(-query)`**

* **Route:** `/ScoDoc/api/assiduites/group/query`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Paramètres:**
    * `user_id` : l'id de l'auteur de l'assiduité
    * `est_just` : si l'assiduité est justifiée (fait aussi filtre abs/retard)
    * `moduleimpl_id` : l'id du module concerné par l'assiduité
    * `date_debut` : date de début de l'assiduité (supérieur ou égal)
    * `date_fin` : date de fin de l'assiduité (inférieur ou égal)
    * `etat` : etat de l'étudiant &rightarrow; absent, present ou retard
    * `etudids` : liste des ids des étudiants concernés par la recherche
    * `formsemestre_id` : l'identifiant du formsemestre concerné par l'assiduité
    * `with_justifs` : ajoute les justificatifs liés à l'assiduité
* **Description:** Retourne toutes les assiduités d'un groupe d'étudiants
    chemin : /assiduites/group/query?etudids=1,2,3

* **Exemple de résultat:** [assiduites_group.json](./samples/sample_assiduites_group.json.md)


### API Billets d'absence

#### **`billets_absence_create`**

* **Route:** `/ScoDoc/api/billets_absence/create`
* **Méthode:** `POST`
* **Permission:** `Aucune permission requise`
* **Description:** Ajout d'un billet d'absence. Renvoie le billet créé en json.

* **Exemple de résultat:** [billets_absence_create.json](./samples/sample_billets_absence_create.json.md)


#### **`billets_absence_delete`**

* **Route:** `/ScoDoc/api/billets_absence/<int:billet_id>/delete`
* **Méthode:** `POST`
* **Permission:** `Aucune permission requise`
* **Description:** Suppression d'un billet d'absence



#### **`billets_absence_etudiant`**

* **Route:** `/ScoDoc/api/billets_absence/etudiant/<int:etudid>`
* **Méthode:** `GET`
* **Permission:** `Aucune permission requise`
* **Description:** Liste des billets d'absence pour cet étudiant.



### API Département

#### **`departement_by_acronym`**

* **Route:** `/ScoDoc/api/departement/<string:acronym>`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** Info sur un département. Accès par acronyme.

* **Exemple de résultat:** [departement_by_acronym.json](./samples/sample_departement_by_acronym.json.md)


#### **`departement_create`**

* **Route:** `/ScoDoc/api/departement/create`
* **Méthode:** `POST`
* **Permission:** `ScoSuperAdmin`
* **Description:** Création d'un département.
    Le content type doit être `application/json`.

* **Exemple de résultat:** [departement_create.json](./samples/sample_departement_create.json.md)


#### **`departement_delete`**

* **Route:** `/ScoDoc/api/departement/<string:acronym>/delete`
* **Méthode:** `POST`
* **Permission:** `ScoSuperAdmin`
* **Description:** Suppression d'un département identifié par son acronyme.



#### **`departement_edit`**

* **Route:** `/ScoDoc/api/departement/<string:acronym>/edit`
* **Méthode:** `POST`
* **Permission:** `ScoSuperAdmin`
* **Description:** Édition d'un département: seul le champ `visible` peut être modifié.



#### **`departement_etudiants`**

* **Route:** `/ScoDoc/api/departement/<string:acronym>/etudiants`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Paramètres:**
    * `acronym` : l'acronyme d'un département
* **Description:** Retourne la liste des étudiants d'un département.

* **Exemple de résultat:** [departement_etudiants.json](./samples/sample_departement_etudiants.json.md)


#### **`departement_etudiants_by_id`**

* **Route:** `/ScoDoc/api/departement/id/<int:dept_id>/etudiants`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** Retourne la liste des étudiants d'un département d'id donné.



#### **`departement_formsemestres_courants(-query)`**

* **Routes:**
    * `/ScoDoc/api/departement/id/<int:dept_id>/formsemestres_courants`
    * `/ScoDoc/api/departement/<string:acronym>/formsemestres_courants`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** Liste les formsemestres du département indiqué (par son acronyme ou son id)
    contenant la date courante, ou à défaut celle indiquée en argument
    (au format ISO).

* **Exemple de résultat:** [departement_formsemestres_courants.json](./samples/sample_departement_formsemestres_courants.json.md)


#### **`departement_formsemestres_ids`**

* **Route:** `/ScoDoc/api/departement/<string:acronym>/formsemestres_ids`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** Liste des ids de tous les formsemestres du département.

* **Exemple de résultat:** [departement_formsemestres_ids.json](./samples/sample_departement_formsemestres_ids.json.md)


#### **`departement_formsemestres_ids_by_id`**

* **Route:** `/ScoDoc/api/departement/id/<int:dept_id>/formsemestres_ids`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** Liste des ids de tous les formsemestres du département.

* **Exemple de résultat:** [departement_formsemestres_ids_by_id.json](./samples/sample_departement_formsemestres_ids_by_id.json.md)


#### **`departement_get`**

* **Route:** `/ScoDoc/api/departement/id/<int:dept_id>`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** Info sur un département. Accès par id.

* **Exemple de résultat:** [departement_get.json](./samples/sample_departement_get.json.md)


#### **`departements_ids`**

* **Route:** `/ScoDoc/api/departements_ids`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** Liste des ids de tous les départements.

* **Exemple de résultat:** [departements_ids.json](./samples/sample_departements_ids.json.md)


#### **`departements_list`**

* **Route:** `/ScoDoc/api/departements`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** Liste tous les départements.

* **Exemple de résultat:** [departements_list.json](./samples/sample_departements_list.json.md)


### API Étudiants

#### **`bulletin`**

* **Routes:**
    * `/ScoDoc/api/etudiant/<string:code_type>/<string:code>/formsemestre/<int:formsemestre_id>/bulletin/<string:version>/pdf/nosig`
    * `/ScoDoc/api/etudiant/<string:code_type>/<string:code>/formsemestre/<int:formsemestre_id>/bulletin/<string:version>/pdf`
    * `/ScoDoc/api/etudiant/<string:code_type>/<string:code>/formsemestre/<int:formsemestre_id>/bulletin/<string:version>`
    * `/ScoDoc/api/etudiant/<string:code_type>/<string:code>/formsemestre/<int:formsemestre_id>/bulletin`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Paramètres:**
    * `formsemestre_id` : l'id d'un formsemestre
    * `code_type` : "etudid", "nip" ou "ine"
    * `code` : valeur du code INE, NIP ou etudid, selon code_type.
    * `version` : type de bulletin (par défaut, "selectedevals"): short, long, selectedevals, butcourt
    * `pdf` : si spécifié, bulletin au format PDF (et non JSON).
* **Description:** Retourne le bulletin d'un étudiant dans un formsemestre.

* **Exemple de résultat:** [bulletin.json](./samples/sample_bulletin.json.md)


#### **`etudiant`**

* **Routes:**
    * `/ScoDoc/api/etudiant/ine/<string:ine>`
    * `/ScoDoc/api/etudiant/nip/<string:nip>`
    * `/ScoDoc/api/etudiant/etudid/<int:etudid>`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Paramètres:**
    * `etudid` : l'etudid de l'étudiant
    * `nip` : le code nip de l'étudiant
    * `ine` : le code ine de l'étudiant
* **Description:** Retourne les informations de l'étudiant correspondant, ou 404 si non trouvé.

    `etudid` est unique dans la base (tous départements).
    Les codes INE et NIP sont uniques au sein d'un département.
    Si plusieurs objets ont le même code, on ramène le plus récemment inscrit.



#### **`etudiant_annotation`**

* **Route:** `/ScoDoc/api/etudiant/<string:code_type>/<string:code>/annotation`
* **Méthode:** `POST`
* **Permission:** `EtudInscrit`
* **Paramètres:**
    * ``code_type`` : le type du code, `etudid`, `ine` ou `nip`.
    * ``code`` : la valeur du code
* **Description:** Ajout d'une annotation sur un étudiant.

    Renvoie l'annotation créée.

* **Exemple de résultat:** [etudiant_annotation.json](./samples/sample_etudiant_annotation.json.md)


#### **`etudiant_annotation_delete`**

* **Route:** `/ScoDoc/api/etudiant/<string:code_type>/<string:code>/annotation/<int:annotation_id>/delete`
* **Méthode:** `POST`
* **Permission:** `EtudInscrit`
* **Paramètres:**
    * ``code_type`` : le type du code, `etudid`, `ine` ou `nip`.
    * ``code`` : la valeur du code
    * ``annotation_id`` : id de l'annotation
* **Description:** Suppression d'une annotation. On spécifie l'étudiant et l'id de l'annotation.



#### **`etudiant_create`**

* **Routes:**
    * `/ScoDoc/api/etudiant/create/force`
    * `/ScoDoc/api/etudiant/create`
* **Méthode:** `POST`
* **Permission:** `EtudInscrit`
* **Description:** Création d'un nouvel étudiant.

    Si force, crée même si homonymie détectée.

    L'étudiant créé n'est pas inscrit à un semestre.

    Champs requis: nom, prenom (sauf si config sans prénom), dept (string:acronyme)



#### **`etudiant_edit`**

* **Route:** `/ScoDoc/api/etudiant/<string:code_type>/<string:code>/edit`
* **Méthode:** `POST`
* **Permission:** `EtudInscrit`
* **Paramètres:**
    * ``code_type`` : le type du code, `etudid`, `ine` ou `nip`.
    * ``code`` : la valeur du code
* **Description:** Édition des données étudiant (identité, admission, adresses).

* **Exemple de résultat:** [etudiant_edit.json](./samples/sample_etudiant_edit.json.md)


#### **`etudiant_formsemestres`**

* **Routes:**
    * `/ScoDoc/api/etudiant/ine/<string:ine>/formsemestres`
    * `/ScoDoc/api/etudiant/nip/<string:nip>/formsemestres`
    * `/ScoDoc/api/etudiant/etudid/<int:etudid>/formsemestres`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** Liste des formsemestres qu'un étudiant a suivi, triés par ordre chronologique.
    Accès par etudid, nip ou ine.

    Attention, si accès via NIP ou INE, les formsemestres peuvent être de départements
    différents (si l'étudiant a changé de département). L'id du département est `dept_id`.

    Si accès par département, ne retourne que les formsemestres suivis dans le département.



#### **`etudiant_get_photo_image(-query)`**

* **Routes:**
    * `/ScoDoc/api/etudiant/ine/<string:ine>/photo`
    * `/ScoDoc/api/etudiant/nip/<string:nip>/photo`
    * `/ScoDoc/api/etudiant/etudid/<int:etudid>/photo`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Paramètres:**
    * `etudid` : l'etudid de l'étudiant
    * `nip` : le code nip de l'étudiant
    * `ine` : le code ine de l'étudiant
* **Description:** Retourne la photo de l'étudiant ou un placeholder si non existant.
    Le paramètre `size` peut prendre la valeur `small` (taille réduite, hauteur
    environ 90 pixels) ou `orig` (défaut, image de la taille originale).



#### **`etudiant_groups`**

* **Route:** `/ScoDoc/api/etudiant/etudid/<int:etudid>/formsemestre/<int:formsemestre_id>/groups`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Paramètres:**
    * `formsemestre_id` : l'id d'un formsemestre
    * `etudid` : l'etudid d'un étudiant
* **Description:** Retourne la liste des groupes auxquels appartient l'étudiant dans le formsemestre indiqué

* **Exemple de résultat:** [etudiant_groups.json](./samples/sample_etudiant_groups.json.md)


#### **`etudiants`**

* **Routes:**
    * `/ScoDoc/api/etudiants/ine/<string:ine>`
    * `/ScoDoc/api/etudiants/nip/<string:nip>`
    * `/ScoDoc/api/etudiants/etudid/<int:etudid>`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** Info sur le ou les étudiants correspondants.

    Comme `/etudiant` mais renvoie toujours une liste.

    Si non trouvé, liste vide, pas d'erreur.

    Dans 99% des cas, la liste contient un seul étudiant, mais si l'étudiant a
    été inscrit dans plusieurs départements, on a plusieurs objets (1 par dept.).



#### **`etudiants_by_name`**

* **Route:** `/ScoDoc/api/etudiants/name/<string:start>`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** Liste des étudiants dont le nom débute par `start`.

    Si `start` fait moins de `min_len=3` caractères, liste vide.
    La casse et les accents sont ignorés.



#### **`etudiants_courants(-query)`**

* **Routes:**
    * `/ScoDoc/api/etudiants/courants/long`
    * `/ScoDoc/api/etudiants/courants`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** La liste des étudiants des semestres "courants".
    Considère tous les départements dans lesquels l'utilisateur a la
    permission `ScoView` (donc tous si le dépt. du rôle est `None`),
    et les formsemestres contenant la date courante,
    ou à défaut celle indiquée en argument (au format ISO).

    En format "long": voir l'exemple.

* **Exemple de résultat:** [etudiants_courants.json](./samples/sample_etudiants_courants.json.md)


### API Évaluations

#### **`evaluation_assiduites`**

* **Route:** `/ScoDoc/api/evaluation/<int:evaluation_id>/assiduites`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** Retourne les objets assiduités de chaque étudiant sur la plage de l'évaluation

    Exemple de résultat:

    ```json
    {
        "<etudid>" : [
            {
                "assiduite_id":1234,
                ...
            },
        ]
    }
    ```



#### **`evaluation_create`**

* **Route:** `/ScoDoc/api/moduleimpl/<int:moduleimpl_id>/evaluation/create`
* **Méthode:** `POST`
* **Permission:** `EnsView`
* **Description:** Création d'une évaluation.

    Résultat: l'évaluation créée.

* **Exemple de résultat:** [evaluation_create.json](./samples/sample_evaluation_create.json.md)


#### **`evaluation_delete`**

* **Route:** `/ScoDoc/api/evaluation/<int:evaluation_id>/delete`
* **Méthode:** `POST`
* **Permission:** `EnsView`
* **Description:** Suppression d'une évaluation.
    Efface aussi toutes ses notes.



#### **`evaluation_notes`**

* **Route:** `/ScoDoc/api/evaluation/<int:evaluation_id>/notes`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Paramètres:**
    * `evaluation_id` : l'id de l'évaluation
* **Description:** Retourne la liste des notes de l'évaluation.

* **Exemple de résultat:** [evaluation_notes.json](./samples/sample_evaluation_notes.json.md)


#### **`evaluation_set_notes`**

* **Route:** `/ScoDoc/api/evaluation/<int:evaluation_id>/notes/set`
* **Méthode:** `POST`
* **Permission:** `EnsView`
* **Description:** Écriture de notes dans une évaluation.

    Résultat:

     - etudids_changed: étudiants dont la note est modifiée
     - etudids_with_decision: liste des etudiants dont la note a changé
          alors qu'ils ont une décision de jury enregistrée.
     - history_menu: un fragment de HTML expliquant l'historique de la note de chaque étudiant modifié.

* **Exemple de résultat:** [evaluation_set_notes.json](./samples/sample_evaluation_set_notes.json.md)


#### **`moduleimpl_evaluations`**

* **Route:** `/ScoDoc/api/moduleimpl/<int:moduleimpl_id>/evaluations`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Paramètres:**
    * `moduleimpl_id` : l'id d'un moduleimpl
* **Description:** Retourne la liste des évaluations d'un moduleimpl.

* **Exemple de résultat:** [moduleimpl_evaluations.json](./samples/sample_moduleimpl_evaluations.json.md)


### API Formations

#### **`formation_export_by_formation_id`**

* **Routes:**
    * `/ScoDoc/api/formation/<int:formation_id>/export_with_ids`
    * `/ScoDoc/api/formation/<int:formation_id>/export`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Paramètres:**
    * `formation_id` : l'id d'une formation
    * `export_with_ids` : si présent, exporte aussi les ids des objets ScoDoc de la formation.
* **Description:** Retourne la formation, avec UE, matières, modules

* **Exemple de résultat:** [formation_export_by_formation_id.json](./samples/sample_formation_export_by_formation_id.json.md)


#### **`formation_get`**

* **Route:** `/ScoDoc/api/formation/<int:formation_id>`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** La formation d'id donné.

* **Exemple de résultat:** [formation_get.json](./samples/sample_formation_get.json.md)


#### **`formation_module_edit`**

* **Route:** `/ScoDoc/api/formation/module/<int:module_id>/edit`
* **Méthode:** `POST`
* **Permission:** `EditFormation`
* **Description:** Édition d'un module. Renvoie le module en json.



#### **`formation_module_get`**

* **Route:** `/ScoDoc/api/formation/module/<int:module_id>`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** Renvoie le module.

* **Exemple de résultat:** [formation_module_get.json](./samples/sample_formation_module_get.json.md)


#### **`formation_module_set_code_apogee`**

* **Routes:**
    * `/ScoDoc/api/formation/module/<int:module_id>/set_code_apogee`
    * `/ScoDoc/api/formation/module/<int:module_id>/set_code_apogee/<string:code_apogee>`
    * `/ScoDoc/api/formation/module/set_code_apogee`
* **Méthode:** `POST`
* **Permission:** `EditFormation`
* **Description:** Change le code Apogée du module.

    Le code est une chaîne, avec éventuellement plusieurs valeurs séparées
    par des virgules.

    Ce changement peut être fait sur formation verrouillée.

    Si `module_id` n'est pas spécifié, utilise l'argument `oid` du POST.
    Si `code_apogee` n'est pas spécifié ou vide,
    utilise l'argument value du POST (utilisé par jinplace.js)

    Le retour est une chaîne (le code enregistré), pas du json.



#### **`formations`**

* **Route:** `/ScoDoc/api/formations`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** Retourne la liste de toutes les formations (tous départements,
    sauf si route départementale).

* **Exemple de résultat:** [formations.json](./samples/sample_formations.json.md)


#### **`formations_ids`**

* **Route:** `/ScoDoc/api/formations_ids`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** Retourne la liste de toutes les id de formations
    (tous départements, ou du département indiqué dans la route)

    Exemple de résultat : `[ 17, 99, 32 ]`.

* **Exemple de résultat:** [formations_ids.json](./samples/sample_formations_ids.json.md)


#### **`referentiel_competences`**

* **Route:** `/ScoDoc/api/formation/<int:formation_id>/referentiel_competences`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** Retourne le référentiel de compétences de la formation
    ou null si pas de référentiel associé.

* **Exemple de résultat:** [referentiel_competences.json](./samples/sample_referentiel_competences.json.md)


#### **`ue_assoc_niveau`**

* **Route:** `/ScoDoc/api/formation/ue/<int:ue_id>/assoc_niveau/<int:niveau_id>`
* **Méthode:** `POST`
* **Permission:** `EditFormation`
* **Description:** Associe l'UE au niveau de compétence.



#### **`ue_desassoc_niveau`**

* **Route:** `/ScoDoc/api/formation/ue/<int:ue_id>/desassoc_niveau`
* **Méthode:** `POST`
* **Permission:** `EditFormation`
* **Description:** Désassocie cette UE de son niveau de compétence
    (si elle n'est pas associée, ne fait rien).



#### **`ue_edit`**

* **Route:** `/ScoDoc/api/formation/ue/<int:ue_id>/edit`
* **Méthode:** `POST`
* **Permission:** `EditFormation`
* **Description:** Édition d'une UE. Renvoie l'UE en json.



#### **`ue_set_code_apogee`**

* **Routes:**
    * `/ScoDoc/api/formation/ue/<int:ue_id>/set_code_apogee`
    * `/ScoDoc/api/formation/ue/<int:ue_id>/set_code_apogee/<string:code_apogee>`
    * `/ScoDoc/api/formation/ue/set_code_apogee`
* **Méthode:** `POST`
* **Permission:** `EditFormation`
* **Description:** Change le code Apogée de l'UE.

    Le code est une chaîne, avec éventuellement plusieurs valeurs séparées
    par des virgules.

    Ce changement peut être fait sur formation verrouillée.

    Si `ue_id` n'est pas spécifié, utilise l'argument oid du POST.
    Si `code_apogee` n'est pas spécifié ou vide,
    utilise l'argument value du POST.

    Le retour est une chaîne (le code enregistré), pas du json.



#### **`ue_set_code_apogee_rcue`**

* **Routes:**
    * `/ScoDoc/api/formation/ue/<int:ue_id>/set_code_apogee_rcue`
    * `/ScoDoc/api/formation/ue/<int:ue_id>/set_code_apogee_rcue/<string:code_apogee>`
* **Méthode:** `POST`
* **Permission:** `EditFormation`
* **Description:** Change le code Apogée du RCUE de l'UE.

    Le code est une chaîne, avec éventuellement plusieurs valeurs séparées
    par des virgules.

    Ce changement peut être fait sur formation verrouillée.

    Si code_apogee n'est pas spécifié ou vide,
    utilise l'argument value du POST (utilisé par `jinplace.js`)

    Le retour est une chaîne (le code enregistré), pas du json.



#### **`ue_set_parcours`**

* **Route:** `/ScoDoc/api/formation/ue/<int:ue_id>/set_parcours`
* **Méthode:** `POST`
* **Permission:** `EditFormation`
* **Description:** Associe UE et parcours BUT.

    La liste des ids de parcours est passée en argument JSON.



### API Formsemestre

#### **`bulletins`**

* **Routes:**
    * `/ScoDoc/api/formsemestre/<int:formsemestre_id>/bulletins/<string:version>`
    * `/ScoDoc/api/formsemestre/<int:formsemestre_id>/bulletins`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Paramètres:**
    * `formsemestre_id` : int
    * `version` : string ("long", "short", "selectedevals")
* **Description:** Retourne les bulletins d'un formsemestre.

* **Exemple de résultat:** [bulletins.json](./samples/sample_bulletins.json.md)


#### **`formsemestre_edit`**

* **Route:** `/ScoDoc/api/formsemestre/<int:formsemestre_id>/edit`
* **Méthode:** `POST`
* **Permission:** `EditFormSemestre`
* **Description:** Modifie les champs d'un formsemestre.

    On peut spécifier un ou plusieurs champs.



#### **`formsemestre_edt(-query)`**

* **Route:** `/ScoDoc/api/formsemestre/<int:formsemestre_id>/edt`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** L'emploi du temps du semestre.

    Si ok, une liste d'évènements. Sinon, une chaine indiquant un message d'erreur.

    Expérimental, ne pas utiliser hors ScoDoc.



#### **`formsemestre_etat_evaluations`**

* **Route:** `/ScoDoc/api/formsemestre/<int:formsemestre_id>/etat_evals`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** Informations sur l'état des évaluations d'un formsemestre.

* **Exemple de résultat:** [formsemestre_etat_evaluations.json](./samples/sample_formsemestre_etat_evaluations.json.md)


#### **`formsemestre_etud_desinscrit`**

* **Route:** `/ScoDoc/api/formsemestre/<int:formsemestre_id>/etudid/<int:etudid>/desinscrit`
* **Méthode:** `POST`
* **Permission:** `EtudInscrit`
* **Description:** Désinscrit l'étudiant de ce formsemestre et TOUS ses modules



#### **`formsemestre_etud_inscrit`**

* **Route:** `/ScoDoc/api/formsemestre/<int:formsemestre_id>/etudid/<int:etudid>/inscrit`
* **Méthode:** `POST`
* **Permission:** `EtudInscrit`
* **Description:** Inscrit l'étudiant à ce formsemestre et TOUS ses modules STANDARDS
    (donc sauf les modules bonus sport).



#### **`formsemestre_etudiants(-query)`**

* **Routes:**
    * `/ScoDoc/api/formsemestre/<int:formsemestre_id>/etudiants/long/query`
    * `/ScoDoc/api/formsemestre/<int:formsemestre_id>/etudiants/query`
    * `/ScoDoc/api/formsemestre/<int:formsemestre_id>/etudiants/long`
    * `/ScoDoc/api/formsemestre/<int:formsemestre_id>/etudiants`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** Étudiants d'un formsemestre.

    Si l'état est spécifié, ne renvoie que les  inscrits (`I`), les
    démissionnaires (`D`) ou les défaillants (`DEF`)

* **Exemple de résultat:** [formsemestre_etudiants.json](./samples/sample_formsemestre_etudiants.json.md)


#### **`formsemestre_get`**

* **Route:** `/ScoDoc/api/formsemestre/<int:formsemestre_id>`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** Information sur le formsemestre indiqué.

    formsemestre_id : l'id du formsemestre

* **Exemple de résultat:** [formsemestre_get.json](./samples/sample_formsemestre_get.json.md)


#### **`formsemestre_programme`**

* **Route:** `/ScoDoc/api/formsemestre/<int:formsemestre_id>/programme`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** Retourne la liste des UEs, ressources et SAEs d'un semestre

* **Exemple de résultat:** [formsemestre_programme.json](./samples/sample_formsemestre_programme.json.md)


#### **`formsemestre_resultat(-query)`**

* **Route:** `/ScoDoc/api/formsemestre/<int:formsemestre_id>/resultats`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** Tableau récapitulatif des résultats.

    Pour chaque étudiant, son état, ses groupes, ses moyennes d'UE et de modules.

    Si `format=raw`, ne converti pas les valeurs.

* **Exemple de résultat:** [formsemestre_resultat.json](./samples/sample_formsemestre_resultat.json.md)


#### **`formsemestre_set_apo_etapes`**

* **Route:** `/ScoDoc/api/formsemestre/apo/set_etapes`
* **Méthode:** `POST`
* **Permission:** `EditApogee`
* **Description:** Change les codes étapes du semestre indiqué.

    Le code est une chaîne, avec éventuellement plusieurs valeurs séparées
    par des virgules.

    Ce changement peut être fait sur un semestre verrouillé.



#### **`formsemestre_set_elt_annee_apo`**

* **Route:** `/ScoDoc/api/formsemestre/apo/set_elt_annee`
* **Méthode:** `POST`
* **Permission:** `EditApogee`
* **Description:** Change les codes étapes du semestre indiqué (par le champ oid).

    Le code est une chaîne, avec éventuellement plusieurs valeurs séparées
    par des virgules.

    Ce changement peut être fait sur un semestre verrouillé.



#### **`formsemestre_set_elt_passage_apo`**

* **Route:** `/ScoDoc/api/formsemestre/apo/set_elt_passage`
* **Méthode:** `POST`
* **Permission:** `EditApogee`
* **Description:** Change les codes Apogée de passage du semestre indiqué (par le champ oid).

    Le code est une chaîne, avec éventuellement plusieurs valeurs séparées
    par des virgules.

    Ce changement peut être fait sur un semestre verrouillé.



#### **`formsemestre_set_elt_sem_apo`**

* **Route:** `/ScoDoc/api/formsemestre/apo/set_elt_sem`
* **Méthode:** `POST`
* **Permission:** `EditApogee`
* **Description:** Change les codes étapes du semestre indiqué.

    Le code est une chaîne, avec éventuellement plusieurs valeurs séparées
    par des virgules.

    Ce changement peut être fait sur un semestre verrouillé.



#### **`formsemestres_query(-query)`**

* **Route:** `/ScoDoc/api/formsemestres/query`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Paramètres:**
    * `etape_apo` : un code étape apogée
    * `annee_scolaire` : année de début de l'année scolaire
    * `dept_acronym` : acronyme du département (eg "RT")
    * `dept_id` : id du département
    * `ine ou nip` : code d'un étudiant: ramène alors tous les semestres auxquels il est inscrit.
    * `etat` : 0 si verrouillé, 1 sinon
* **Description:** Retourne les formsemestres filtrés par étape Apogée ou année scolaire
    ou département (acronyme ou id) ou état ou code étudiant. Si
    `annee_scolaire`, ne sélectionne que les formsemestres de cette année scolaire.



#### **`groups_get_auto_assignment`**

* **Route:** `/ScoDoc/api/formsemestre/<int:formsemestre_id>/groups_get_auto_assignment`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** Rend les données stockées par `groups_save_auto_assignment`.



#### **`groups_save_auto_assignment`**

* **Route:** `/ScoDoc/api/formsemestre/<int:formsemestre_id>/groups_save_auto_assignment`
* **Méthode:** `POST`
* **Permission:** `ScoView`
* **Description:** Enregistre les données, associées à ce formsemestre.
    Usage réservé aux fonctions de gestion des groupes, ne pas utiliser ailleurs.



### API Groupes et partitions

#### **`formsemestre_partitions`**

* **Route:** `/ScoDoc/api/formsemestre/<int:formsemestre_id>/partitions`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** Liste de toutes les partitions d'un formsemestre.

* **Exemple de résultat:** [formsemestre_partitions.json](./samples/sample_formsemestre_partitions.json.md)


#### **`formsemestre_set_partitions_order`**

* **Route:** `/ScoDoc/api/formsemestre/<int:formsemestre_id>/partitions/order`
* **Méthode:** `POST`
* **Permission:** `ScoView`
* **Description:** Modifie l'ordre des partitions du formsemestre.



#### **`group_create`**

* **Route:** `/ScoDoc/api/partition/<int:partition_id>/group/create`
* **Méthode:** `POST`
* **Permission:** `ScoView`
* **Description:** Création d'un groupe dans une partition.

* **Exemple de résultat:** [group_create.json](./samples/sample_group_create.json.md)


#### **`group_delete`**

* **Route:** `/ScoDoc/api/group/<int:group_id>/delete`
* **Méthode:** `POST`
* **Permission:** `ScoView`
* **Description:** Suppression d'un groupe.



#### **`group_edit`**

* **Route:** `/ScoDoc/api/group/<int:group_id>/edit`
* **Méthode:** `POST`
* **Permission:** `ScoView`
* **Description:** Édition d'un groupe.

* **Exemple de résultat:** [group_edit.json](./samples/sample_group_edit.json.md)


#### **`group_etudiants`**

* **Route:** `/ScoDoc/api/group/<int:group_id>/etudiants`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Paramètres:**
    * `group_id` : l'id d'un groupe
* **Description:** Retourne la liste des étudiants dans un groupe
    (inscrits au groupe et inscrits au semestre).

* **Exemple de résultat:** [group_etudiants.json](./samples/sample_group_etudiants.json.md)


#### **`group_etudiants_query(-query)`**

* **Route:** `/ScoDoc/api/group/<int:group_id>/etudiants/query`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** Étudiants du groupe, filtrés par état (aucun, `I`, `D`, `DEF`)



#### **`group_remove_etud`**

* **Route:** `/ScoDoc/api/group/<int:group_id>/remove_etudiant/<int:etudid>`
* **Méthode:** `POST`
* **Permission:** `ScoView`
* **Description:** Retire l'étudiant de ce groupe. S'il n'y est pas, ne fait rien.



#### **`group_set_edt_id`**

* **Route:** `/ScoDoc/api/group/<int:group_id>/set_edt_id/<string:edt_id>`
* **Méthode:** `POST`
* **Permission:** `ScoView`
* **Description:** Set edt_id du groupe.

    Contrairement à `/edit`, peut-être changé pour toute partition
    d'un formsemestre non verrouillé.

* **Exemple de résultat:** [group_set_edt_id.json](./samples/sample_group_set_edt_id.json.md)


#### **`group_set_etudiant`**

* **Route:** `/ScoDoc/api/group/<int:group_id>/set_etudiant/<int:etudid>`
* **Méthode:** `POST`
* **Permission:** `ScoView`
* **Description:** Affecte l'étudiant au groupe indiqué.



#### **`partition_create`**

* **Route:** `/ScoDoc/api/formsemestre/<int:formsemestre_id>/partition/create`
* **Méthode:** `POST`
* **Permission:** `ScoView`
* **Description:** Création d'une partition dans un semestre.



#### **`partition_delete`**

* **Route:** `/ScoDoc/api/partition/<int:partition_id>/delete`
* **Méthode:** `POST`
* **Permission:** `ScoView`
* **Description:** Suppression d'une partition (et de tous ses groupes).

    * Note 1: La partition par défaut (tous les étudiants du sem.) ne peut
        pas être supprimée.
    * Note 2: Si la partition de parcours est supprimée, les étudiants
        sont désinscrits des parcours.



#### **`partition_edit`**

* **Route:** `/ScoDoc/api/partition/<int:partition_id>/edit`
* **Méthode:** `POST`
* **Permission:** `ScoView`
* **Description:** Modification d'une partition dans un semestre.

    Tous les champs sont optionnels.

* **Exemple de résultat:** [partition_edit.json](./samples/sample_partition_edit.json.md)


#### **`partition_info`**

* **Route:** `/ScoDoc/api/partition/<int:partition_id>`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** Info sur une partition.

* **Exemple de résultat:** [partition_info.json](./samples/sample_partition_info.json.md)


#### **`partition_order_groups`**

* **Route:** `/ScoDoc/api/partition/<int:partition_id>/groups/order`
* **Méthode:** `POST`
* **Permission:** `ScoView`
* **Description:** Modifie l'ordre des groupes de la partition.



#### **`partition_remove_etud`**

* **Route:** `/ScoDoc/api/partition/<int:partition_id>/remove_etudiant/<int:etudid>`
* **Méthode:** `POST`
* **Permission:** `ScoView`
* **Description:** Enlève l'étudiant de tous les groupes de cette partition.

    (NB: en principe, un étudiant ne doit être que dans 0 ou 1 groupe d'une partition)



### API Jury

#### **`autorisation_inscription_delete`**

* **Route:** `/ScoDoc/api/etudiant/<int:etudid>/jury/autorisation_inscription/<int:validation_id>/delete`
* **Méthode:** `POST`
* **Permission:** `EtudInscrit`
* **Description:** Efface cette autorisation d'inscription.



#### **`decisions_jury`**

* **Route:** `/ScoDoc/api/formsemestre/<int:formsemestre_id>/decisions_jury`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** Décisions du jury des étudiants du formsemestre.

Exemple abrégé de résultat pour un semestre BUT S1:

```json
[
  {
    "etudid": 16375,
    "code_nip": "16375",
    "code_ine": null,
    "is_apc": true,
    "etat": "I",
    "nb_competences": 3,
    "rcues": [
      {
        "ue_1": {
          "ue_id": 1896,
          "moy": 10.317715802881702,
          "code": "ADM"
        },
        "ue_2": {
          "ue_id": 2458,
          "moy": 11.11946734181982,
          "code": "ADM"
        },
        "moy": 10.71859157235076,
        "code": "ADM"
      },
      ...
    ],
    "ues": [
      {
        "ue_id": 1896,
        "code": "ADM",
        "ects": 11.0
      },
      ...
    ],
    "semestre": {},
    "annee": {
      "code": "ADM",
      "ordre": 1,
      "annee_scolaire": 2022
    },
    "autorisations": [
      {
        "etudid": 16375,
        "id": 35998,
        "origin_formsemestre_id": 1105,
        "formation_code": "VRET",
        "semestre_id": 2,
        "date": "2024-03-22T19:33:36.868001+01:00"
      }
    ]
  },
  ...
]
```


* **Exemple de résultat:** [decisions_jury.json](./samples/sample_decisions_jury.json.md)


#### **`validation_annee_but_delete`**

* **Route:** `/ScoDoc/api/etudiant/<int:etudid>/jury/validation_annee_but/<int:validation_id>/delete`
* **Méthode:** `POST`
* **Permission:** `EtudInscrit`
* **Description:** Efface cette validation d'année BUT.



#### **`validation_dut120_delete`**

* **Route:** `/ScoDoc/api/etudiant/<int:etudid>/jury/validation_dut120/<int:validation_id>/delete`
* **Méthode:** `POST`
* **Permission:** `EtudInscrit`
* **Description:** Efface cette validation de DUT120.



#### **`validation_formsemestre_delete`**

* **Route:** `/ScoDoc/api/etudiant/<int:etudid>/jury/validation_formsemestre/<int:validation_id>/delete`
* **Méthode:** `POST`
* **Permission:** `ScoView`
* **Description:** Efface cette validation de semestre.



#### **`validation_rcue_delete`**

* **Route:** `/ScoDoc/api/etudiant/<int:etudid>/jury/validation_rcue/<int:validation_id>/delete`
* **Méthode:** `POST`
* **Permission:** `EtudInscrit`
* **Description:** Efface cette validation de RCUE.



#### **`validation_rcue_record`**

* **Route:** `/ScoDoc/api/etudiant/<int:etudid>/jury/validation_rcue/record`
* **Méthode:** `POST`
* **Permission:** `EtudInscrit`
* **Description:** Enregistre une validation de RCUE.

    Si une validation existe déjà pour ce RCUE, la remplace.



#### **`validation_ue_delete`**

* **Route:** `/ScoDoc/api/etudiant/<int:etudid>/jury/validation_ue/<int:validation_id>/delete`
* **Méthode:** `POST`
* **Permission:** `ScoView`
* **Description:** Efface cette validation d'UE.



### API Justificatifs

#### **`justif_create`**

* **Routes:**
    * `/ScoDoc/api/justificatif/ine/<ine>/create`
    * `/ScoDoc/api/justificatif/nip/<nip>/create`
    * `/ScoDoc/api/justificatif/etudid/<int:etudid>/create`
    * `/ScoDoc/api/justificatif/<int:etudid>/create`
* **Méthode:** `POST`
* **Permission:** `AbsChange`
* **Description:** Création d'un justificatif pour l'étudiant.



#### **`justif_delete`**

* **Route:** `/ScoDoc/api/justificatif/delete`
* **Méthode:** `POST`
* **Permission:** `AbsChange`
* **Description:** Suppression d'un justificatif à partir de son id.

* **Exemple de résultat:** [justif_delete.json](./samples/sample_justif_delete.json.md)


#### **`justif_edit`**

* **Route:** `/ScoDoc/api/justificatif/<int:justif_id>/edit`
* **Méthode:** `POST`
* **Permission:** `AbsChange`
* **Description:** Édition d'un justificatif à partir de son id.

* **Exemple de résultat:** [justif_edit.json](./samples/sample_justif_edit.json.md)


#### **`justif_export`**

* **Route:** `/ScoDoc/api/justificatif/<int:justif_id>/export/<filename>`
* **Méthode:** `POST`
* **Permission:** `ScoView`
* **Description:** Retourne un fichier d'une archive d'un justificatif.

    La permission est `ScoView` + (`AbsJustifView` ou être l'auteur du justificatif).

    > Procédure de téléchargement de fichier : [télécharger un justificatif](FichiersJustificatifs.md#télécharger-un-fichier)



#### **`justif_import`**

* **Route:** `/ScoDoc/api/justificatif/<int:justif_id>/import`
* **Méthode:** `POST`
* **Permission:** `AbsChange`
* **Description:** Importation d'un fichier (création d'archive).

    > Procédure d'importation de fichier : [importer un justificatif](FichiersJustificatifs.md#importer-un-fichier)



#### **`justif_justifies`**

* **Route:** `/ScoDoc/api/justificatif/<int:justif_id>/justifies`
* **Méthode:** `GET`
* **Permission:** `AbsChange`
* **Description:** Liste `assiduite_id` justifiées par le justificatif.

* **Exemple de résultat:** [justif_justifies.json](./samples/sample_justif_justifies.json.md)


#### **`justif_list`**

* **Route:** `/ScoDoc/api/justificatif/<int:justif_id>/list`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** Liste les fichiers du justificatif.

* **Exemple de résultat:** [justif_list.json](./samples/sample_justif_list.json.md)


#### **`justif_remove`**

* **Route:** `/ScoDoc/api/justificatif/<int:justif_id>/remove`
* **Méthode:** `POST`
* **Permission:** `AbsChange`
* **Description:** Supression d'un fichier ou d'une archive.

    > Procédure de suppression de fichier : [supprimer un justificatif](FichiersJustificatifs.md#supprimer-un-fichier)



#### **`justificatif`**

* **Route:** `/ScoDoc/api/justificatif/<int:justif_id>`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** Retourne un objet justificatif à partir de son id.

    Exemple de résultat:

    ```json
    {
        "justif_id": 1,
        "etudid": 2,
        "date_debut": "2022-10-31T08:00+01:00",
        "date_fin": "2022-10-31T10:00+01:00",
        "etat": "valide",
        "fichier": "archive_id",
        "raison": "une raison", // VIDE si pas le droit
        "entry_date": "2022-10-31T08:00+01:00",
        "user_id": 1 or null,
    }
    ```

* **Exemple de résultat:** [justificatif.json](./samples/sample_justificatif.json.md)


#### **`justificatifs(-query)`**

* **Routes:**
    * `/ScoDoc/api/justificatifs/ine/<ine>/query`
    * `/ScoDoc/api/justificatifs/ine/<ine>`
    * `/ScoDoc/api/justificatifs/nip/<nip>/query`
    * `/ScoDoc/api/justificatifs/nip/<nip>`
    * `/ScoDoc/api/justificatifs/etudid/<int:etudid>/query`
    * `/ScoDoc/api/justificatifs/etudid/<int:etudid>`
    * `/ScoDoc/api/justificatifs/<int:etudid>/query`
    * `/ScoDoc/api/justificatifs/<int:etudid>`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Paramètres:**
    * `user_id` : l'id de l'auteur du justificatif
    * `date_debut` : date de début du justificatif (supérieur ou égal)
    * `date_fin` : date de fin du justificatif (inférieur ou égal)
    * `etat` : etat du justificatif &rightarrow; valide, non_valide, attente, modifie
    * `order` : retourne les justificatifs dans l'ordre décroissant (non vide = True)
    * `courant` : retourne les justificatifs de l'année courante (bool : v/t ou f)
    * `group_id` : <int:group_id>
* **Description:** Retourne toutes les assiduités d'un étudiant

* **Exemple de résultat:** [justificatifs.json](./samples/sample_justificatifs.json.md)


#### **`justificatifs_dept(-query)`**

* **Routes:**
    * `/ScoDoc/api/justificatifs/dept/<int:dept_id>/query`
    * `/ScoDoc/api/justificatifs/dept/<int:dept_id>`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Paramètres:**
    * `user_id` : l'id de l'auteur du justificatif
    * `date_debut` : date de début du justificatif (supérieur ou égal)
    * `date_fin` : date de fin du justificatif (inférieur ou égal)
    * `etat` : etat du justificatif &rightarrow; valide, non_valide, attente, modifie
    * `order` : retourne les justificatifs dans l'ordre décroissant (non vide = True)
    * `courant` : retourne les justificatifs de l'année courante (bool : v/t ou f)
    * `group_id` : <int:group_id>
* **Description:** Renvoie tous les justificatifs d'un département
    (en ajoutant un champ "`formsemestre`" si possible).

* **Exemple de résultat:** [justificatifs_dept.json](./samples/sample_justificatifs_dept.json.md)


#### **`justificatifs_formsemestre(-query)`**

* **Routes:**
    * `/ScoDoc/api/justificatifs/formsemestre/<int:formsemestre_id>/query`
    * `/ScoDoc/api/justificatifs/formsemestre/<int:formsemestre_id>`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Paramètres:**
    * `user_id` : l'id de l'auteur du justificatif
    * `date_debut` : date de début du justificatif (supérieur ou égal)
    * `date_fin` : date de fin du justificatif (inférieur ou égal)
    * `etat` : etat du justificatif &rightarrow; valide, non_valide, attente, modifie
    * `order` : retourne les justificatifs dans l'ordre décroissant (non vide = True)
    * `courant` : retourne les justificatifs de l'année courante (bool : v/t ou f)
    * `group_id` : <int:group_id>
* **Description:** Retourne tous les justificatifs du formsemestre.

* **Exemple de résultat:** [justificatifs_formsemestre.json](./samples/sample_justificatifs_formsemestre.json.md)


### API Logos

#### **`departement_logos`**

* **Route:** `/ScoDoc/api/departement/<string:dept_acronym>/logos`
* **Méthode:** `GET`
* **Permission:** `ScoSuperAdmin`
* **Description:** Liste des noms des logos définis pour le département
    désigné par son acronyme.

* **Exemple de résultat:** [departement_logos.json](./samples/sample_departement_logos.json.md)


#### **`departement_logos_by_id`**

* **Route:** `/ScoDoc/api/departement/id/<int:dept_id>/logos`
* **Méthode:** `GET`
* **Permission:** `ScoSuperAdmin`
* **Description:** Liste des noms des logos définis pour le département
    désigné par son id.



#### **`logo_get_global`**

* **Route:** `/ScoDoc/api/logo/<string:logoname>`
* **Méthode:** `GET`
* **Permission:** `ScoSuperAdmin`
* **Description:** Renvoie le logo global de nom donné.

    L'image est au format png ou jpg; le format retourné dépend du format sous lequel
    l'image a été initialement enregistrée.

* **Exemple de résultat:** [logo_get_global.json](./samples/sample_logo_get_global.json.md)


#### **`logo_get_local_dept_by_acronym`**

* **Route:** `/ScoDoc/api/departement/<string:departement>/logo/<string:logoname>`
* **Méthode:** `GET`
* **Permission:** `ScoSuperAdmin`
* **Description:** Le logo: image (format png ou jpg).

    **Exemple d'utilisation:**

        * `/ScoDoc/api/departement/MMI/logo/header`



#### **`logo_get_local_dept_by_id`**

* **Route:** `/ScoDoc/api/departement/id/<int:dept_id>/logo/<string:logoname>`
* **Méthode:** `GET`
* **Permission:** `ScoSuperAdmin`
* **Description:** Le logo: image (format png ou jpg).

    **Exemple d'utilisation:**

            * `/ScoDoc/api/departement/id/3/logo/header`



#### **`logo_list_globals`**

* **Route:** `/ScoDoc/api/logos`
* **Méthode:** `GET`
* **Permission:** `ScoSuperAdmin`
* **Description:** Liste des noms des logos définis pour le site ScoDoc.

* **Exemple de résultat:** [logo_list_globals.json](./samples/sample_logo_list_globals.json.md)


### API Moduleimpl

#### **`moduleimpl_etud_desinscrit`**

* **Route:** `/ScoDoc/api/moduleimpl/<int:moduleimpl_id>/etudid/<int:etudid>/desinscrit`
* **Méthode:** `POST`
* **Permission:** `ScoView`
* **Description:** Désinscrit l'étudiant de ce moduleimpl.

* **Exemple de résultat:** [moduleimpl_etud_desinscrit.json](./samples/sample_moduleimpl_etud_desinscrit.json.md)


#### **`moduleimpl_etud_inscrit`**

* **Route:** `/ScoDoc/api/moduleimpl/<int:moduleimpl_id>/etudid/<int:etudid>/inscrit`
* **Méthode:** `POST`
* **Permission:** `ScoView`
* **Description:** Inscrit l'étudiant à ce moduleimpl.

* **Exemple de résultat:** [moduleimpl_etud_inscrit.json](./samples/sample_moduleimpl_etud_inscrit.json.md)


#### **`moduleimpl_inscriptions`**

* **Route:** `/ScoDoc/api/moduleimpl/<int:moduleimpl_id>/inscriptions`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** Liste des inscriptions à ce moduleimpl.

* **Exemple de résultat:** [moduleimpl_inscriptions.json](./samples/sample_moduleimpl_inscriptions.json.md)


#### **`moduleimpl_notes`**

* **Route:** `/ScoDoc/api/moduleimpl/<int:moduleimpl_id>/notes`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** Liste des notes dans ce moduleimpl.

* **Exemple de résultat:** [moduleimpl_notes.json](./samples/sample_moduleimpl_notes.json.md)


### API Tokens

#### **`token_get`**

* **Route:** `/ScoDoc/api/tokens`
* **Méthode:** `POST`
* **Permission:** `Aucune permission requise`
* **Description:** Renvoie un jeton jwt pour l'utilisateur courant.



### API Utilisateurs

#### **`permissions_list`**

* **Route:** `/ScoDoc/api/permissions`
* **Méthode:** `GET`
* **Permission:** `UsersView`
* **Description:** Liste des noms de permissions définies.

* **Exemple de résultat:** [permissions_list.json](./samples/sample_permissions_list.json.md)


#### **`role_create`**

* **Route:** `/ScoDoc/api/role/create/<string:role_name>`
* **Méthode:** `POST`
* **Permission:** `ScoSuperAdmin`
* **Description:** Création d'un nouveau rôle avec les permissions données.

* **Exemple de résultat:** [role_create.json](./samples/sample_role_create.json.md)


#### **`role_delete`**

* **Route:** `/ScoDoc/api/role/<string:role_name>/delete`
* **Méthode:** `POST`
* **Permission:** `ScoSuperAdmin`
* **Description:** Suppression d'un rôle.

* **Exemple de résultat:** [role_delete.json](./samples/sample_role_delete.json.md)


#### **`role_edit`**

* **Route:** `/ScoDoc/api/role/<string:role_name>/edit`
* **Méthode:** `POST`
* **Permission:** `ScoSuperAdmin`
* **Description:** Édition d'un rôle. On peut spécifier un nom et/ou des permissions.



#### **`role_get`**

* **Route:** `/ScoDoc/api/role/<string:role_name>`
* **Méthode:** `GET`
* **Permission:** `UsersView`
* **Description:** Un rôle.

* **Exemple de résultat:** [role_get.json](./samples/sample_role_get.json.md)


#### **`role_permission_add`**

* **Route:** `/ScoDoc/api/role/<string:role_name>/add_permission/<string:perm_name>`
* **Méthode:** `POST`
* **Permission:** `ScoSuperAdmin`
* **Description:** Ajoute une permission à un rôle.



#### **`role_permission_remove`**

* **Route:** `/ScoDoc/api/role/<string:role_name>/remove_permission/<string:perm_name>`
* **Méthode:** `POST`
* **Permission:** `ScoSuperAdmin`
* **Description:** Retire une permission d'un rôle.



#### **`roles_list`**

* **Route:** `/ScoDoc/api/roles`
* **Méthode:** `GET`
* **Permission:** `UsersView`
* **Description:** Tous les rôles définis.

* **Exemple de résultat:** [roles_list.json](./samples/sample_roles_list.json.md)


#### **`user_create`**

* **Route:** `/ScoDoc/api/user/create`
* **Méthode:** `POST`
* **Permission:** `UsersAdmin`
* **Description:** Création d'un utilisateur



#### **`user_edit`**

* **Route:** `/ScoDoc/api/user/<int:uid>/edit`
* **Méthode:** `POST`
* **Permission:** `UsersAdmin`
* **Description:** Modification d'un utilisateur.

    Champs modifiables:
    ```json
    {
        "dept": str or null,
        "nom": str,
        "prenom": str,
        "active":bool
        ...
    }
    ```



#### **`user_info`**

* **Route:** `/ScoDoc/api/user/<int:uid>`
* **Méthode:** `GET`
* **Permission:** `UsersView`
* **Description:** Info sur un compte utilisateur ScoDoc.

* **Exemple de résultat:** [user_info.json](./samples/sample_user_info.json.md)


#### **`user_password`**

* **Route:** `/ScoDoc/api/user/<int:uid>/password`
* **Méthode:** `POST`
* **Permission:** `UsersAdmin`
* **Description:** Modification du mot de passe d'un utilisateur.

    Si le mot de passe ne convient pas, erreur 400.

* **Exemple de résultat:** [user_password.json](./samples/sample_user_password.json.md)


#### **`user_role_add`**

* **Routes:**
    * `/ScoDoc/api/user/<int:uid>/role/<string:role_name>/add/departement/<string:dept>`
    * `/ScoDoc/api/user/<int:uid>/role/<string:role_name>/add`
* **Méthode:** `POST`
* **Permission:** `ScoSuperAdmin`
* **Description:** Ajoute un rôle à l'utilisateur dans le département donné.



#### **`user_role_remove`**

* **Routes:**
    * `/ScoDoc/api/user/<int:uid>/role/<string:role_name>/remove/departement/<string:dept>`
    * `/ScoDoc/api/user/<int:uid>/role/<string:role_name>/remove`
* **Méthode:** `POST`
* **Permission:** `ScoSuperAdmin`
* **Description:** Retire le rôle (dans le département donné) à cet utilisateur.



#### **`users_info_query(-query)`**

* **Route:** `/ScoDoc/api/users/query`
* **Méthode:** `GET`
* **Permission:** `ScoView`
* **Description:** Utilisateurs, filtrés par dept, active ou début nom

    Exemple:
    ```
    /users/query?departement=dept_acronym&active=1&starts_with=<string:nom>
    ```

    Seuls les utilisateurs "accessibles" (selon les permissions) sont retournés.
    Si accès via API web,  le département de l'URL est ignoré, seules
    les permissions de l'utilisateur sont prises en compte.






---------------------------------------------------------------------------------------------------------------------

### En savoir plus

Voir exemples d'utilisation de l'API en Python, dans `tests/api/`.

!!! info
    Cette page a été générée par la commande `flask gen-api-doc`, et les exemples de résultats
    sont créés par `tools/test_api.sh --make-samples`.

!!! note "Voir aussi"

    - [Guide configuration et ligne de commande](GuideConfig.md)
    - [Guide administrateur ScoDoc](GuideAdminSys.md)
    - [ServicesXml](ServicesXml.md) : anciens web services XML (obsolète)
    - [FAQ](FAQ.md)
    - [Contacts](Contact.md)