Commandes & Distributions

Workflow de commande automatique

  1. Récupération du catalogue produit

  2. Commander pour un établissement

  3. Récupérer le statut de la commande

  4. Créer les référents pour un ou plusieurs établissement(s)

  5. Exporter toutes les commandes de l'année scolaire en cours

  6. Exporter tous les abonnements GAR des commandes de l'année scolaire en cours

Environnements

Deux environnements sont à votre disposition pour la réalisation de vos appels :

  • Pré-production : https://api-dev.lelivrescolaire.fr. Disponible pour vos tests, les codes licences générées ne seront pas valables sur des applications de production.

  • Production : https://api.lelivrescolaire.fr. Environnement principal, une commande engage le distributeur qui la passe et entraîne la réalisation d'une facture adressée dans les semaines suivant la commande.

Authentification

L'ensemble des appels sur ces APIs est conditionné à l'envoi d'une clé distributeur identifiant l'entreprise source. Il est de votre responsabilité de conserver cet identifiant de manière confidentielle et sécurisée.

La clé distributeur est envoyée via un "paramètre de query" apiKey. Un appel sur l'URL https://api.lelivrescolaire.fr/webservice devient donc https://api.lelivrescolaire.fr/webservice?apiKey=ABC avec ici ABC la clé distributeur.

Récupération du catalogue produit

API : GET https://api(-dev).lelivrescolaire.fr/sales/products

Format de sortie : JSON Exemple de produit de type manuel numérique :

{
  id: "01t0Y000001BBJOQA4",
  reference: "Numerique_2017-Français 5e - Manuel numérique interactif",
  ean: "9791090910270"
}

Exemple de produit de type pack :

{
  id: "01t0Y000001rBbtQAE",
  reference: "Numerique_2017-Pack numérique 5e toutes matières",
  ean: "9791090910386"
}

Passage d'une commande

API : POST https://api(-dev).lelivrescolaire.fr/sales/commands

Les paramètres d'entrée et de sortie sont au format JSON.

Paramètres d'entrée :

  • uai : UAI de l'établissement à l'origine de la commande

  • products : Tableau des produits souhaités. Chaque produit est sous le format { <EAN_PRODUCT>: <QUANTITE_SOUHAITEE> }

  • vref (optionnel) : permet de spécifier la référence de votre facture

  • deployEmail1 (optionnel) : permet de spécifier l'email de référent

  • deployEmail2 (optionnel) : permet de spécifier l'email de référent 2

  • billingEmail (optionnel) : permet de spécifier l'email de facturation

  • garComment (optionnel) : permet de spécifier le code projet ressource (anciennement commentaire GAR)

Exemple d'envoi :

{
  "uai":"0010079F",
  "products": {"9791090910300":10},
  "vref": "361715",
  "deployEmail1":"deployEmail1@lelivrescolaire.fr",
  "deployEmail2":"deployEmail2@lelivrescolaire.fr",
  "billingEmail":"billinEmail@lelivrescolaire.fr",
}

Retour d'appel

  • Code de réponse : 200

  • Contenu de la réponse :

{
    "school": "0941091A",
    "code": "Y5WWH7O",
    "credits": 378,
    "vref": "361715",
    "createdAt": "2018-07-05T05:26:31.224Z",
    "expiredAt": "2019-08-01T16:41:21.000Z",
    "booksNumber": 2
}

Détail

  • school : UAI de l'établissement concerné

  • code : code licence à utiliser pour l'activation des applications

  • credits : estimation du nombre d'appareils autorisés. Cette information est surtout utile pour constater la prise en compte d'une mise à jour de commande.

  • createdAt : date de création de la licence au format ISO 8601

  • expiredAt : date d'expiration de la licence au format ISO 8601

  • booksNumber : le nombre de livre associés à la licence

Codes d'erreur

  • 401 : erreur d'authentification, probablement du à l'apiKey

  • 400 : erreur dans le format des paramètres d'entrée. Autant que possible, un message décrivant l'erreur complètera le message.

Récupération du statut d'une commande

APIs :

  • Via le code de la licence : GET https://api(-dev).lelivrescolaire.fr/sales/commands/:uai. Renvoie la licence active pour une école donnée, ainsi que toutes les commandes associées

Paramètres d'entrée :

  • uai : UAI de l'établissement à l'origine de la commande

Retour d'appel

Code de réponse : 200

Format d'une commande :

{
  "vref": "BC EMLS177442",
  "school": "0941091A",
  "code": "Y5WWH7O",
  "credits": 378,
  "booksNumber": 1,
  "createdAt": "2018-07-05T05:26:31.224Z",
  "expiredAt": "2019-08-01T16:41:21.000Z",
  "commands": [{
    "name": "WS6646385",
    "vref": "WS6646385",
    "created": "2019-05-15T22:00:00.000Z",
    "expires": "2020-08-15T22:00:00.000Z",
    "products": [{
      "ean": "9791090910225",
      "books": [
        "Histoire-Géographie-EMC 6e"
      ],
      "quantity": 378,
      "duration": 12
    }]
  }]
}

Codes d'erreur

  • 401 : erreur d'authentification, probablement du à l'apiKey

  • 400 : erreur dans le format des paramètres d'entrée. Autant que possible, un message décrivant l'erreur complètera le message.

Créer les référents pour un ou plusieurs établissement(s)

API : POST https://api(-dev).lelivrescolaire.fr/sales/referents

Les paramètres d'entrée et de sortie sont au format JSON.

Paramètres d'entrée :

Tableau d'objets contenant chacun :

  • email : l'email du référent

  • uai : l'uai de l'école associée au référent

Exemple d'envoi :

[{
  "email": "my.email@gmail.com",
  "uai": "0011275F"
}]

Retour d'appel

  • Code de réponse : 200

  • Contenu de la réponse :

[{
  "id": 5746352,
  "profileId": 5746352,
  "email": "my.email@gmail.com",
  "emailCanonical": "test@testtytt",
  "created": 1536219837185,
  "updated": 1536222114061,
  "passwordUpdateRequired": false,
  "enabled": true,
  "confirmed": true,
  "role": "ROLE_REFERENT",
  "roleCalc": "ROLE_USER",
  "isStudent": false,
  "isTeacher": true,
  "academicEnabled": true,
  "hasTrialData": false,
  "isTrialData": false,
  "schools": [
      884456
  ],
  "classes": [],
  "subjects": [],
  "levels": [],
  "revisions": [],
  "hasRenewedSubscription": false
}]

Codes d'erreur

  • 401 : erreur d'authentification, probablement du à l'apiKey

  • 400 : erreur dans le format des paramètres d'entrée. Autant que possible, un message décrivant l'erreur complètera le message.

Exporter toutes les commandes de l'année scolaire en cours

API : GET https://api(-dev).lelivrescolaire.fr/sales/export/commands

Les paramètres d'entrée et de sortie sont au format JSON.

Paramètres d'entrée :

  • year : (optionnel) détermine l'année scolaire souhaitée pour l'export des ventes. [default = currentYear]. A noter que cette valeur correspond au "début d'année". Par exemple 2022 correspond à l'année scolaire 2022-2023.

Exemple d'envoi :

{ year: 2022 }

Retour d'appel

  • Code de réponse : 200

  • Contenu de la réponse :

{
  "commands": [
    {
      "id": "0060Y000003Zr5KQAS",
      "name": "SOME COMMANDE",
      "recordType": "Manuels_num_riques",
      "vref": "SOME BILLING REF",
      "code": "4MYYA6SWZ",
      "amount": 1151.55,
      "amountIncludingTaxes": 1214.89,
      "closeDate": "2016-12-15",
      "discount": null,
      "discountDistributor": 10,
      "taxesPercentage": 5.5,
      "amountTaxes": 63.34,
      "items": [
        {
          "id": "00k0Y000006UIbiQAG",
          "code": "NUM10A_HG5_2016",
          "salesPrice": 8.53,
          "totalPrice": 1214.88525,
          "totalPriceWithProductDiscount": 1349.87,
          "quantity": 150,
          "discount": null,
          "tva": 5.5,
          "totalPriceWithoutTaxesWithProductDiscount": 1279.5
        }
      ]
    }
  ]
}

Codes d'erreur

  • 401 : erreur d'authentification, probablement du à l'apiKey

Exporter tous les abonnements GAR correspondant aux commandes de l'année scolaire en cours

/!\ Cet appel peut prendre plusieurs dizaines de secondes, le temps de récupération des abonnements étant relativement lent selon le nombre d'établissements concernés.

API : GET https://api(-dev).lelivrescolaire.fr/sales/export/gar-subscriptions

Les paramètres d'entrée et de sortie sont au format JSON.

Paramètres d'entrée :

  • year : (optionnel) détermine l'année scolaire souhaitée pour l'export des abonnements. [default = currentYear]. A noter que cette valeur correspond au "début d'année". Par exemple 2022 correspond à l'année scolaire 2022-2023.

Exemple d'envoi :

{ year: 2022 }

Retour d'appel

  • Code de réponse : 200

  • Contenu de la réponse :

{
  "subscriptions": [
    {
      "idAbonnement": "53678103-20137482",
      "idDistributeurCom": "524383585_0000000000000000",
      "idRessource": "ark:/27704/20137482",
      "typeIdRessource": "ark",
      "libelleRessource": "Mathématiques 1re Technologique 2021",
      "debutValidite": "2022-04-03T17:38:48.000+02:00",
      "finValidite": "2023-08-15T00:00:00.000+02:00",
      "anneeFinValidite": "2022-2023",
      "uaiEtab": "9999999P",
      "categorieAffectation": "transferable",
      "typeAffectation": "INDIV",
      "nbLicenceGlobale": "17",
      "publicCible": [
        "ELEVE",
        "ENSEIGNANT",
        "DOCUMENTALISTE"
      ]
    }
  ]
}

Codes d'erreur

  • 401 : erreur d'authentification, probablement du à l'apiKey

NextDéploiement | Applications Lelivrescolaire.fr

Last updated