
#  API pour ScoDoc 
L'API ScoDoc permet à des applications tierces d'interroger ScoDoc. Elle offre un accès aux informations aux formats XML et JSON.
Cette API est encore incomplète: n'hésitez pas à demander de nouveaux accès en écrivant à la liste de diffusion.

L'ancienne API, un peu désordonnée, est décrite sur [ServicesXml](ServicesXml.md).

Chaque fonction d'accès (`*_list` et autres) prend un paramètre `format` qui indique le format de données désiré: `json` ou `xml` .

Les objets ScoDoc manipulables sont identifiés par des id, garantis uniques au sein d'un même département (mais pas au delà, car chaque département a sa base de données séparée).

 * 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.


L'URL complète est de la forme: `https://scodoc.example.com/ScoDoc/DEPT/Scolarite/Notes/fonction` où `DEPT`est le département et `fonction` la fonction appelée.

Un exemple d'utilisation de l'API en PHP pour publier les bulletins de notes sur un site externe pour les étudiants est disponible ici: source:/trunk/misc/PublicationBulletins/ExemplePHP


##  Fonctions d'accès aux données 
###  Programmes de formations 
  *  **`formation_list`**
    * Paramètres: `formation_id` (optionnel, si absent liste toutes les formations)
    * Résultat: liste de formations.

  * **`formation_export`**
    * Paramètres: `formation_id`, `export_ids` (défaut "faux")
    * Résultat: la formation, avec UE, matières, modules (un arbre).


###  Semestres de formation 
Les sessions de formation (dénommées "semestres" même si elles durent une année ou un mois) sont représentées par les `formsemestre`.

  * **`formsemestre_list`**
    * Paramètres (tous optionnels): `formsemestre_id`, `formation_id`, `etape_apo`, `etape_apo2`
    * Résultat: liste des semestres correspondant.
    * Exemple: `formsemestre_list?format=xml&etape_apo=V1RT`

Note sur les identifiants de sessions: le `session_id` peut être utilisé pour identifier de façon prévisible et (presque) unique une session dans un établissement, ce qui est utile notamment pour interfacer ScoDoc à d'autres logiciels (eg gestion d'emplois du temps ou de services d'enseignement). Cet identifiant est constitué des informations suivantes:

  * Département (RT, GEII, INFO...) (= paramètre `DeptName`, en majuscules)
  * Nom parcours: DUT, LP, ... (défini au niveau du parcours dans ScoDoc = NAME)
  *  Modalité: FI, FC, FA
  * "Spécialité" : S1 (ou S1D pour les sem. décalés), ou le `code_specialite` si pas de semestres.   Le code spécialité est un champ (libre) nouveau dans la "formation" (programme pédagogique).
  * Année: année de début de l'année scolaire correspondante (eg 2014 pour une session appartenant à   l'année scolaire 2014-2015, même si elle commence en mars 2015).

Exemple: `INFO-DUT-FI-S1-2014` : semestre S1 d'un DUT informatique de 2014 en formation initiale (FI)




###  Groupes et partitions 
L'ensemble des étudiants d'un semestre peut être réparti selon une ou plusieurs partitions (types de groupes). Chaque partition est constituée d'un nombre quelconque de groupes d'étudiants.

  * **`formsemestre_partition_list`**
    * Paramètres: `formsemestre_id`
    * Résultat: 
    * Exemple: ici au format JSON
```
[
 {
  "formsemestre_id": "SEM12781", 
  "partition_id": "P23840", 
  "partition_name": "TD"
  "group": [
   {
    "formsemestre_id": "SEM12781", 
    "partition_id": "P23840", 
    "group_name": "A", 
    "group_id": "G23841", 
    "partition_name": "TD"
   }, 
   {
    "formsemestre_id": "SEM12781", 
    "partition_id": "P23840", 
    "group_name": "B", 
    "group_id": "G23843", 
    "partition_name": "TD"
   }, 
  ], 
 }, 
 {
  "formsemestre_id": "SEM12781", 
  "partition_id": "P23941", 
  "partition_name": "TP"
  "group": [
   {
    "formsemestre_id": "SEM12781", 
    "partition_id": "P23941", 
    "group_name": "A1", 
    "group_id": "G23942", 
    "partition_name": "TP"
   }, 
   {
    "formsemestre_id": "SEM12781", 
    "partition_id": "P23941", 
    "group_name": "A2", 
    "group_id": "G23943", 
    "partition_name": "TP"
   }, 
  ], 
 }, 
 {
  "formsemestre_id": "SEM12781", 
  "partition_id": "P22833", 
  "partition_name": null
  "group": [
   {
    "formsemestre_id": "SEM12781", 
    "partition_id": "P22833", 
    "group_name": null, 
    "group_id": "G22834", 
    "partition_name": null
   }
  ], 
 }
]
```
  * **`groups_view`**
    * Paramètres: `formsemestre_id `ou `group_ids` (peut être répété), `with_codes=0|1`, `all_groups=0|1`, `etat=None|I` 
    * Résultat: liste des étudiants dans un groupe.
    * Exemple: ici au format XML avec `with_codes=1`:
```
<group_list origin="" caption="soit 21 étudiants inscrits et 2 démissionaires." id="gt_711068">

<etud>
<nom value="TOTO"/>
<prenom value="Marc"/>
<etat value="I"/>
<email value="toto@example.com"/>
<etudid value="EID9876"/>
<code_nip value="987654"/>
<code_ine value=""/>
</etud>

<etud>
<nom value="ALVIS SAMOS"/>
<prenom value="NATHALIE"/>
<etat value="I"/>
<email value="xxx@example.com"/>
<etudid value="EID12345"/>
<code_nip value="12345678"/>
<code_ine value=""/>
</etud>
</group_list>
```
Et un autre exemple en format JSON:
```
[  
   {  
      "etat":"I",
      "emailperso":null,
      "prenom":"Dalil",
      "nom_disp":"CLINTO",
      "email":"xxx@example.com",
      "P62029":"A",
      "P62032":null,
      "P62031":"G1",
      "P62030":"A1"
   },
   {  
      "etat":"I",
      "emailperso":null,
      "prenom":"Georges",
      "nom_disp":"BUSH",
      "email":"bush@example.com",
      "P62029":"A",
      "P62032":null,
      "P62031":"G1",
      "P62030":"A1"
   },
  ...
]
```


###  Etudiants 
  * **`etud_info`**
    * Paramètres: `etudid` ou `code_nip` ou `code_ine`
    * Résultat: informations sur cette étudiant et les semestres dans lesquels il est (ou a été) inscrit.
    * Exemple: `etud_info?format=json&etudid=12345`
```
{
 "nom": "Mutis", 
 "sexe": "M.", 
 "email": "alvaro.mutis@example.com", 
 "prenom": "ALVARO",
 "nomprenom": "M. Alvaro MUTIS", 
 "insemestre": [
  {
   "etat": "I", 
   "formsemestre_id": "SEM12781", 
   "date_fin": "2010-07-30", 
   "date_debut": "2010-01-25"
  }, 
  {
   "etat": "I", 
   "formsemestre_id": "SEM8396", 
   "date_fin": "2009-01-16", 
   "date_debut": "2008-09-01"
  }
 ], 
 "code_ine": "", 
 "etudid": "EID8768", 
 "code_nip": "10991002", 
 "photo_url": "/ScoDoc/static/photos/F13/RT_EID8768.h90.jpg", 

 "domicile": "2 Rue Madame", 
 "villedomicile": "Paris",  
 "telephonemobile": ""
 "fax": "", 

 "annee_bac": "2010", 
 "bac": "S",
 "specialite": "SCIENTIFIQUE",  

 "nomlycee": "", 
 "villelycee": "",
 "codelycee": "0950650R", 
 "codepostallycee": "", 

}
```



###  Bulletins de notes 
 * **`Notes/formsemestre_bulletinetud`**
    * Paramètres: `formsemestre_id`, `etudid`, `format` (`xml`ou `json`), `version` (`short`, `selectedevals`ou `long`)
    * Résultat: bulletin de notes
    * Exemple: ici au format JSON, pour une version courte (`version=short`)
```
{
  "rang": {
    "ninscrits": 52,
    "value": "1"
  },
  "etape_apo2": "",
  "etape_apo3": "",
  "etape_apo4": "",
  "etudiant": {
    "nom": "BOLANO",
    "prenom": "Roberto",
    "sexe": "M.",
    "code_ine": "",
    "etudid": "EID9860",
    "code_nip": "123456789",
    "email": "roberto@santateresa.mx",
    "photo_url": "\/ScoDoc\/static\/photos\/F68\/RT_EID29960.h90.jpg"
  },
  "bonus_sport_culture": {
    "value": 0
  },
  "absences": {
    "nbabsjust": 0,
    "nbabs": 1
  },
  "decision": {
    "etat": "I",
    "code": "ADM",
    "compense_formsemestre_id" : "SEM12345" /* si ce semestre en compense un autre */
  },
  "note": {
    "max": "15.51",
    "moy": "10.80",
    "value": "15.51",
    "min": "07.29"
  },
  "etudid": "EID9860",
  "decision_ue": [
    {
      "acronyme": "UE11",
      "code": "ADM",
      "ects": "16.0",
      "titre": "D\u00e9couverte m\u00e9tiers",
      "numero": "11",
      "ue_id": "UE21456"
    },
    {
      "acronyme": "UE12",
      "code": "ADM",
      "ects": "14.0",
      "titre": "Mise \u00e0 niveau des comp\u00e9tences transversales et scientifiques",
      "numero": "12",
      "ue_id": "UE21478"
    }
  ],
  "ue_capitalisee": [
    
  ],
  "publie": 1,
  "autorisation_inscription": [
    {
      "semestre_id": 2
    }
  ],
  "appreciation": [
    
  ],
  "note_max": {
    "value": 20
  },
  "date": "2014-07-12T17:38:47.693262",
  "rang_group": [
    {
      "ninscrits": 26,
      "value": "1",
      "group_type": "TD",
      "group_name": "B"
    },
    {
      "ninscrits": 13,
      "value": "1",
      "group_type": "TP",
      "group_name": "B1"
    },
    {
      "ninscrits": 4,
      "value": "1",
      "group_type": "G",
      "group_name": "G4"
    },
    {
      "ninscrits": "",
      "value": "",
      "group_type": "tutorat",
      "group_name": ""
    },
    {
      "ninscrits": "",
      "value": "",
      "group_type": "App",
      "group_name": ""
    },
    {
      "ninscrits": "",
      "value": "",
      "group_type": "sport",
      "group_name": ""
    }
  ],
  "formsemestre_id": "SEM12345",
  "etape_apo": "V1RT",
  "ue": [
    {
      "acronyme": "UE11",
      "rang": "1",
      "code_apogee": "VRTU11",
      "ects": "16",
      "numero": "11",
      "note": {
        "max": "16.17",
        "value": "16.17",
        "min": "06.56"
      },
      "module": [
        {
          "coefficient": 3,
          "rang": {
            "value": "1"
          },
          "code": "M1101",
          "code_apogee": "VRT1101",
          "numero": 1101,
          "note": {
            "moy": "08.94",
            "nb_notes": 51,
            "nb_missing": 0,
            "max": "19.18",
            "min": "03.70",
            "nb_valid_evals": 3,
            "value": "19.18"
          },
          "abbrev": "R\u00e9seaux d&apos;entreprises",
          "effectif": {
            "value": 51
          },
          "titre": "Initiation aux r\u00e9seaux d&apos;entreprises",
          "evaluation": [
            
          ],
          "id": "MIP27427"
        },
        {
          "coefficient": 2,
          "rang": {
            "value": "2"
          },
          "code": "M1102",
          "code_apogee": "VRT1102",
          "numero": 1102,
          "note": {
            "moy": "12.58",
            "nb_notes": 50,
            "nb_missing": 1,
            "max": "16.79",
            "min": "02.50",
            "nb_valid_evals": 2,
            "value": "16.50"
          },
          "abbrev": "Initiation \u00e0 la t\u00e9l\u00e9phonie",
          "effectif": {
            "value": 51
          },
          "titre": "Initiation \u00e0 la t\u00e9l\u00e9phonie d&apos;entreprise",
          "evaluation": [
            
          ],
          "id": "MIP27437"
        },
        {
          "coefficient": 1.5,
          "rang": {
            "value": "1"
          },
          "code": "M1103",
          "code_apogee": "VRT1103",
          "numero": 1103,
          "note": {
            "moy": "08.26",
            "nb_notes": 51,
            "nb_missing": 0,
            "max": "13.41",
            "min": "00.94",
            "nb_valid_evals": 2,
            "value": "13.41"
          },
          "abbrev": "Architecture des \u00e9quipements informatiques",
          "effectif": {
            "value": 51
          },
          "titre": "Architecture des \u00e9quipements informatiques",
          "evaluation": [
            
          ],
          "id": "MIP27451"
        },
        {
          "coefficient": 2,
          "rang": {
            "value": "1"
          },
          "code": "M1104",
          "code_apogee": "VRT1104",
          "numero": 1104,
          "note": {
            "moy": "10.77",
            "nb_notes": 51,
            "nb_missing": 0,
            "max": "17.90",
            "min": "04.63",
            "nb_valid_evals": 3,
            "value": "17.90"
          },
          "abbrev": "Principe et architecture des r\u00e9seaux",
          "effectif": {
            "value": 51
          },
          "titre": "Principe et architecture des r\u00e9seaux",
          "evaluation": [
            
          ],
          "id": "MIP27431"
        },
        {
          "coefficient": 2,
          "rang": {
            "value": "1"
          },
          "code": "M1105",
          "code_apogee": "VRT1105",
          "numero": 1105,
          "note": {
            "moy": "11.00",
            "nb_notes": 51,
            "nb_missing": 0,
            "max": "17.83",
            "min": "04.98",
            "nb_valid_evals": 2,
            "value": "17.83"
          },
          "abbrev": "Bases des syst\u00e8mes d&apos;exploitation",
          "effectif": {
            "value": 51
          },
          "titre": "Bases des syst\u00e8mes d&apos;exploitation",
          "evaluation": [
            
          ],
          "id": "MIP27433"
        },
        {
          "coefficient": 1.5,
          "rang": {
            "value": "6"
          },
          "code": "M1106",
          "code_apogee": "VRT1106",
          "numero": 1106,
          "note": {
            "moy": "13.05",
            "nb_notes": 51,
            "nb_missing": 0,
            "max": "17.79",
            "min": "07.08",
            "nb_valid_evals": 1,
            "value": "16.25"
          },
          "abbrev": "Initiation au d\u00e9veloppement Web",
          "effectif": {
            "value": 51
          },
          "titre": "Initiation au d\u00e9veloppement Web",
          "evaluation": [
            
          ],
          "id": "MIP27449"
        },
        {
          "coefficient": 1.5,
          "rang": {
            "value": "9"
          },
          "code": "M1107",
          "code_apogee": "VRT1107",
          "numero": 1107,
          "note": {
            "moy": "09.36",
            "nb_notes": 51,
            "nb_missing": 0,
            "max": "14.21",
            "min": "04.17",
            "nb_valid_evals": 3,
            "value": "11.66"
          },
          "abbrev": "Initiation \u00e0 la mesure du signal",
          "effectif": {
            "value": 51
          },
          "titre": "Initiation \u00e0 la mesure du signal",
          "evaluation": [
            
          ],
          "id": "MIP27440"
        },
        {
          "coefficient": 1.5,
          "rang": {
            "value": "7"
          },
          "code": "M1108",
          "code_apogee": "VRT1108",
          "numero": 1108,
          "note": {
            "moy": "10.49",
            "nb_notes": 51,
            "nb_missing": 0,
            "max": "16.31",
            "min": "05.39",
            "nb_valid_evals": 4,
            "value": "13.22"
          },
          "abbrev": "Acquisition et codage de l&apos;information",
          "effectif": {
            "value": 51
          },
          "titre": "Acquisition et codage de l&apos;information",
          "evaluation": [
            
          ],
          "id": "MIP27453"
        },
        {
          "coefficient": 1,
          "rang": {
            "value": "4 ex"
          },
          "code": "M1109",
          "code_apogee": "VRT1109",
          "numero": 1109,
          "note": {
            "moy": "12.46",
            "nb_notes": 51,
            "nb_missing": 0,
            "max": "16.00",
            "min": "09.00",
            "nb_valid_evals": 1,
            "value": "15.00"
          },
          "abbrev": "PT : Recherche documentaire",
          "effectif": {
            "value": 51
          },
          "titre": "PT : Recherche documentaire",
          "evaluation": [
            
          ],
          "id": "MIP27444"
        }
      ],
      "effectif": "51",
      "titre": "D\u00e9couverte m\u00e9tiers",
      "id": "UE21456"
    },
    {
      "acronyme": "UE12",
      "rang": "5",
      "code_apogee": "VRTU12",
      "ects": "14",
      "numero": "12",
      "note": {
        "max": "15.20",
        "value": "14.63",
        "min": "07.94"
      },
      "module": [
        {
          "coefficient": 2,
          "rang": {
            "value": "3 ex"
          },
          "code": "M1201",
          "code_apogee": "VRT1201",
          "numero": 10,
          "note": {
            "moy": "13.02",
            "nb_notes": 51,
            "nb_missing": 0,
            "max": "16.00",
            "min": "10.00",
            "nb_valid_evals": 1,
            "value": "14.00"
          },
          "abbrev": "Anglais",
          "effectif": {
            "value": 51
          },
          "titre": "Anglais g\u00e9n\u00e9ral de communication et initiation au vocabulaire technique",
          "evaluation": [
            
          ],
          "id": "MIP27430"
        },
        {
          "coefficient": 2,
          "rang": {
            "value": "16 ex"
          },
          "code": "M1202",
          "code_apogee": "VRT1202",
          "numero": 20,
          "note": {
            "moy": "12.74",
            "nb_notes": 51,
            "nb_missing": 0,
            "max": "17.75",
            "min": "04.00",
            "nb_valid_evals": 2,
            "value": "14.00"
          },
          "abbrev": "Expression",
          "effectif": {
            "value": 51
          },
          "titre": "EC: \u00c9l\u00e9ments fondamentaux de la communication",
          "evaluation": [
            
          ],
          "id": "MIP27439"
        },
        {
          "coefficient": 1,
          "rang": {
            "value": "1 ex"
          },
          "code": "M1203",
          "code_apogee": "VRT1203",
          "numero": 30,
          "note": {
            "moy": "NA",
            "nb_notes": 0,
            "nb_missing": 51,
            "max": "-",
            "min": "-",
            "nb_valid_evals": 0,
            "value": "-"
          },
          "abbrev": "PPP: Connaitre son champ d&apos;activit\u00e9",
          "effectif": {
            "value": 51
          },
          "titre": "PPP: Connaitre son champ d&apos;activit\u00e9",
          "evaluation": [
            
          ],
          "id": "MIP27436"
        },
        {
          "coefficient": 2,
          "rang": {
            "value": "6"
          },
          "code": "M1204",
          "code_apogee": "VRT1204",
          "numero": 40,
          "note": {
            "moy": "10.66",
            "nb_notes": 51,
            "nb_missing": 0,
            "max": "16.35",
            "min": "05.73",
            "nb_valid_evals": 8,
            "value": "14.09"
          },
          "abbrev": "Mise \u00e0 niveau en num\u00e9ration et calculs",
          "effectif": {
            "value": 51
          },
          "titre": "Mise \u00e0 niveau en num\u00e9ration et calculs",
          "evaluation": [
            
          ],
          "id": "MIP27454"
        },
        {
          "coefficient": 2,
          "rang": {
            "value": "23"
          },
          "code": "M1205",
          "code_apogee": "VRT1205",
          "numero": 50,
          "note": {
            "moy": "10.37",
            "nb_notes": 51,
            "nb_missing": 0,
            "max": "18.69",
            "min": "05.01",
            "nb_valid_evals": 5,
            "value": "10.58"
          },
          "abbrev": "Connaissances et Outils pour le signal",
          "effectif": {
            "value": 51
          },
          "titre": "Harmonisation des connaissances et des outils pour le signal",
          "evaluation": [
            
          ],
          "id": "MIP27432"
        },
        {
          "coefficient": 2,
          "rang": {
            "value": "3 ex"
          },
          "code": "M1206",
          "code_apogee": "VRT1206",
          "numero": 60,
          "note": {
            "moy": "11.22",
            "nb_notes": 51,
            "nb_missing": 0,
            "max": "16.76",
            "min": "03.91",
            "nb_valid_evals": 6,
            "value": "15.12"
          },
          "abbrev": "Circuits \u00e9lectroniques : mise \u00e0 niveau",
          "effectif": {
            "value": 51
          },
          "titre": "Circuits \u00e9lectroniques : mise \u00e0 niveau",
          "evaluation": [
            
          ],
          "id": "MIP27435"
        },
        {
          "coefficient": 2,
          "rang": {
            "value": "1 ex"
          },
          "code": "M1207",
          "code_apogee": "VRT1207",
          "numero": 70,
          "note": {
            "moy": "08.39",
            "nb_notes": 51,
            "nb_missing": 0,
            "max": "20.00",
            "min": "00.00",
            "nb_valid_evals": 1,
            "value": "20.00"
          },
          "abbrev": "Programmation 1",
          "effectif": {
            "value": 51
          },
          "titre": "Bases de la programmation",
          "evaluation": [
            
          ],
          "id": "MIP27445"
        },
        {
          "coefficient": 1,
          "rang": {
            "value": "1 ex"
          },
          "code": "M1208",
          "code_apogee": "VRT1208",
          "numero": 80,
          "note": {
            "moy": "NA",
            "nb_notes": 0,
            "nb_missing": 51,
            "max": "-",
            "min": "-",
            "nb_valid_evals": 0,
            "value": "-"
          },
          "abbrev": "M\u00e9thodologie Universitaire 1",
          "effectif": {
            "value": 51
          },
          "titre": "Adaptation et m\u00e9thodologie pour la r\u00e9ussite Universitaire",
          "evaluation": [
            
          ],
          "id": "MIP27434"
        }
      ],
      "effectif": "51",
      "titre": "Mise \u00e0 niveau des comp\u00e9tences transversales et scientifiques",
      "id": "UE21478"
    },
    {
      "acronyme": "UE 1S",
      "rang": "1 ex",
      "code_apogee": "",
      "ects": "0",
      "numero": "13",
      "note": {
        "max": "00.00",
        "value": "00.00",
        "min": "00.00"
      },
      "module": [
        
      ],
      "effectif": "51",
      "titre": "Sport &amp;amp; Culture",
      "id": "UE23716"
    }
  ],
  "situation": "Inscrit le 02\/09\/2015. D\u00e9cision jury: Valid\u00e9.  UE acquises: UE11, UE12.  Autoris\u00e9 \u00e0 s&apos;inscrire en S2."
}
```



###  Modules 
 * **`Notes/do_moduleimpl_list`**
    * Paramètres: `[formsemestre_id, moduleimpl_id, module_id]`
    * Résultat: liste de moduleimpl

 * **`Notes/do_moduleimpl_withmodule_list`**
    * Paramètres: `[formsemestre_id, moduleimpl_id, module_id]`
    * Résultat: liste triée de moduleimpl, avec l'attribut `module`


###  En savoir plus 
Voir l'exemple complet d'utilisation de l'API JSON en Python, dans `misc/example-api-1.py`





