API Oeno2cuve

API Oeno2cuve
Documentation

1 - Introduction

L'API de Oeno2cuve permet d'envoyer des demandes d'analyses, de récupérer des résultats d'analyses, de lister des bulletins, de télécharger des bulletins et récupérer le paramétrage. Elle utilise le protocole HTTP, l'architecture AJAX, le format de données JSON ainsi que l'encodage UTF−8. Le maintien des sessions se fait via un Cookie HTTP.

 

Tous les appels se font via une URL sécurisée unique :

 

URL : https://oeno2cuve-service.mydesk.run
Méthode : GET ou POST
Entêtes :

‣ X-Requested-With: XMLHttpRequest

 

Cookie: string

Fournir systématiquement sauf pour la première requête de connexion au service.

Paramètres :

Si méthode GET, les transmettre dans l'URL de la requête HTTP. Exemple :

GET /class/method?field1=value1&field2=value2  HTTP/1.1

 

Si méthode POST, les transmettre dans le corps de la requête HTTP. Exemple :

POST /class/method HTTP/1.1
Host: oeno2cuve-service.mydesk.run
field1=value1&field2=value2

Résultat :

Tous les résultats sont retournés au format JSON. Exemple :

{ "success":boolean [ ,"msg":string ] [ ,"code":integer ] [ ... ]  }

 

Et contiendrons systématiquement les données suivantes :

success=boolean

Réussite du traitement de la requête.

 

msg=string (Seulement si success=false)

Message d'erreur.

 

code=integer (Seulement si success=false)

Code d'erreur.

100=Session expirée

101=Identification échouée

102=Erreur fatale

2 - Connexion et session

Pour utiliser l'API Oeno2cuve, il faut vous connecter au service web. Vous recevrez alors un identifiant de session sous forme de Cookie, dans l'entête de la réponse HTTP, qu'il faudra fournir ultérieurement en tant que Cookie dans l'entête de chaque requête HTTP. Une fois les traitements terminés, il convient de se déconnecter de service web afin de détruire la session sur le serveur.

2.1 - Connexion

S'identifier au service avec le login, le mot de passe et l'identifiant laboratoire d'un utilisateur non-administrateur.

 

Méthode : POST
Chemin : /
Paramètres :

‣ __bootstrap_action=control_login

 

‣ __bootstrap_value={"login":string,"passwd":string,"laboratoire":string}

Résultat : Aucune donnée

2.2 - Vérification et maintien de la session

Appeler cette fonction si la durée est trop longue entre les appels.

 

Méthode : GET
Chemin : /
Paramètres : ‣ __bootstrap_checksession
Résultat :

Aucune donnée

2.3 - Déconnexion

Se déconnecter du service.

 

Méthode : POST
Chemin : /
Paramètres : ‣ __bootstrap_action=control_logout
Résultat : Aucune donnée

3 - Demandes d'analyses

L'API permet d'envoyer des demandes d'analyses.

3.1 - Envoi

Envoyer une demande un fichier de demande d'analyse

 

Méthode : POST
Chemin : /analyse_demandes/upload
Entêtes suppl. : ‣ Content-Type: multipart/form-data
Paramètres :

‣ uploaded_file=file

Fichier à envoyer.

Résultat :

‣ total=integer

Nombre d'enregistrements.

 

‣ rows=array[object]

Tableau des enregistrements.

3.2 - Résultats d'analyses

L'API permet de lister, récupérer et supprimer les fichiers contenant les résultats d'analyses.

3.2.1 - Lecture

Lister les fichiers contenant les résultats d'analyses.

 

Méthode : GET
Chemin : /analyse_resultats/read
Paramètres : Aucun
Résultat :

‣ total=integer

Nombre d'enregistrements.

 

‣ rows=array[object]

Tableau des enregistrements.

3.2.2 - Récupération

Télécharger un fichier résultat parmi les fichiers listé.

Méthode : GET
Chemin : /analyse_resultat/download
Paramètres :

uri=string (facultatif)

Uri du résultat.

Résultat : Fichier

4.3 - Suppression

Supprimer un fichier contenant des résultats.

Méthode : GET
Chemin : /analyse_resultat/delete
Paramètres :

uri=string (facultatif)

Uri du résultat.

Résultat : Aucune donnée

6 - Paramétrage du XML

L'API permet récupérer le paramétrage du laboratoire pour l'échange de données.

6.1 - Récupération

Télécharger le paramétrage.

Méthode : GET
Chemin : /parametrage/download
Paramètres : Aucun
Résultat : Fichier

7 - Bulletins

L'API permet de lister les bulletins selon quelques critères, ensuite il faut exploiter cette liste pour récupérer les Identifiants de bulletins permettant leur téléchargement.

5.1 - Liste des bulletins selon certains critères

permet de retrouver les uid de bulletins pour le téléchargement du bulletin en pdf lors de la fonction download.

 

Méthode : GET
Chemin : /bulletins/read
Paramètres :

date_bulletin_min=date ('YYYY-MM-DD HH-II-SS') (facultatif)

Filtrer par date de bulletin minimum.

Si non fourni, égale à la date du jour.

 

date_bulletin_max=date ('YYYY-MM-DD HH-II-SS') (facultatif)

Filtrer par date de bulletin maximum

 

id_externe=integer (facultatif)

Filtrer par identifiant externe de l'échantillon.(Identifiant fourni par le client lors de la préidentification)

 

id_bulletin=integer (facultatif)

Filtrer par identifiant du bulletin. on n'obtient qu'un seul bulletin qui porte cet UID.


no_cofrac=integer (facultatif)

Filtrer par n° COFRAC, numéro unique donc un seul bulletin..


dom_chtx=string (facultatif)

Filtrer par nom de domaine et/ou chateau


noechantillon=integer (facultatif)

Filtrer par N° d'échantillon, liste tous les bulletins sur lesquels figurent cet échantillon.


nomanalyses=string (facultatif)

Filtrer par type de bilan analytique


no_lot=string (facultatif)

Filtrer par n° de lot indiqué à l'enregistrement


millesime=string (facultatif)

Filtrer par millesime


novin=string (facultatif)

Filtrer par n° de vin


nocuve=string (facultatif)

Filtrer par ...


appellation=string (facultatif)

Filtrer par n° de cuve ou identification de contenant

 

sort=string (facultatif)

Nom du champ dont le contenu déterminera l'ordre de tri des résultats.

 

dir=string (facultatif) 

Direction du tri des résultats.

asc=Ascendant

desc=Descendant

 

limit=integer (facultatif) (indissociable du paramètre start)

Limite le nombre d'enregistrements.

 

start=integer (facultatif) (indissociable du paramètre limit)

Récupère les enregistrements à partir du {start}ième.

Résultat :

‣ total=integer

Nombre d'enregistrements.

 

‣ rows=array[object]

Tableau des enregistrements.

5.2 - Récupération d'un bulletin au format pdf

Télécharger un bulletin d'après son UID (récupéré dans la liste des bulletibns)

Méthode : GET
Chemin : /bulletin/download
Paramètres :

id_bulletin=integer

Identifiant du bulletin.

Résultat : Fichier

5 - Description de tables bulletins et échantillons (version en ligne)

Vous trouverez ci-dessous le liste des champs de chaque table utile pour l'interrogation de la liste des bulletins selon certains critères.

5.1 - Champs de la table bulletin

Champs Type Description
id_bulletin integer Identifiant unique d'un bulletin
date_bulletin date ('YYYY-MM-DD HH-II-SS')  
date_envoi date ('YYYY-MM-DD HH-II-SS')  
ent_ref integer code client dans le laboratoire
     
no_cofrac integer N° COFRAC du bulletin (optionnel)
no_export integer N°Export du bulletin (optionnel)
nom_fichier string  
type_doc string nom du format de bulletin correspondant

5.2 - Champs de la table bulletin-échantillon

Champs Type Description
dom_chtx string  

5.3 - Champs de la table échantillon

Champs Type Description
id_externe string Identifiant fourni par le client pour identifier l'échantillon dans son réferentiel.
noechantillon integer n° d'échantillon tel que connu dans le laboratoire
nomanalyses string bilan analytique appliqué à l'échantillon
no_lot string n° de lot 
millesime string  
novin string n°vin identifiant permettant la traçabilité l'exploitation est par laboratoire par client
nocuve string champ identifiant le contenant (cuve, fut, parcelle, ...)
appellation string