API Webmandat

API Webmandat
Documentation

1 - Introduction

L'API de WebMandat permet de gérer les mandats et utilisateurs de votre registre des mandats. 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 (v0.0.1) :

https://webmandat-service.mydesk.run

URL beta (v0.0.4) : https://beta-webmandat-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: webmandat-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)

Liste des codes d'erreur globaux :
CODES D'ERREUR D'IDENTIFICATION ET DE SESSION (BOOTSTRAP) :
ERROR_SESSION_EXPIRED 100 Session expirée
ERROR_IDENTIFICATION_FAILED 101 Identification échouée
ERROR_FATAL 102 Erreur fatale
ERROR_INTERNET_DISCONNECTED 103 Internet déconnecté
ERROR_BAD_REQUEST 104 Mauvaise requête

CODES D'ERREUR DE TRAITEMENT DE LA REQUETE (MVC) :

ERROR_FATAL 200 Erreur fatale
ERROR_BAD_REQUEST 201 Mauvaise requête
ERROR_BAD_RESPONSE 202 Mauvaise réponse du service
ERROR_BAD_CONFIGURATION 203 Mauvaise configuration du service
ERROR_REQUEST_FAILED 204 Requête échouée

2 - Connexion et session

Pour utiliser l'API WebMandat, 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 code et le mot de passe d'un administrateur de votre registre.

 

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

‣ __bootstrap_action=control_login

 

‣ __bootstrap_value={"code":string,"password":string}

Pour tester l'API sur notre registre de test :

Accès Administrateur : code=230233, password=123
Accès Utilisateur : code=230351, password=123

Résultat :

‣ isAdmin=boolean 

L'utilisateur est un administrateur du registre.

2.2 - Vérification et maintien de la session

Appeler si durée 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 - Gestion des mandats

L'API permet de lire et modifier des mandats. La liste des différents champs est disponible en fin de documentation.

3.1 - Lecture

Lister les mandats de l'utilisateur connecté (ou de tous les utilisateurs, si connecté en administrateur).

 

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

nochrono=integer (facultatif)

Filtrer par numéro de mandat.

 

util_ref=integer (facultatif)

Filtrer par utilisateur.

 

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. Défaut : 100.

 

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

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

Résultat :

‣ total=integer

Nombre d'enregistrements.

 

‣ rows=array[object]

Tableau des enregistrements.

3.2 - Création

Créer un mandat. Une fois le mandat crée, il doit être confirmé maximum 3 minutes après la date/heure renvoyée, avec le méthode prévu à cet effet. Le cas échéant, le numéro ne sera plus confirmable et sera redistribué.

 

Méthode : POST
Chemin : /mandat/create
Paramètres : Aucun
Résultat :

‣ nochrono=integer

Numéro de mandat.

 

‣ dateheure=date

Date de prise du mandat.

 

code=integer (Seulement si success=false)

Liste des codes d'erreur supplémentaires :
CODES D'ERREUR UTILISATEUR :
9100 Vous n'avez pas renvoyé un ou plusieurs mandats dans les délais
9101 Vous avez dépassé votre quota de mandats non renvoyés

3.3 - Confirmation

Confirme un mandat et le récupère.

 

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

nochrono=chaîne

Numéro de mandat à confirmer.

Résultat :

‣ total=integer

Nombre d'enregistrements.

 

‣ rows=array[object]

Tableau des enregistrements modifiés.

 

code=integer (Seulement si success=false)

Liste des codes d'erreur supplémentaires :
CODES D'ERREUR UTILISATEUR :
9103 Ce mandat ne vous appartient pas
9112 Le délai pour la confirmation, de 3 minutes après la prise du mandat, est dépassé
9115 Le numéro de mandat est obligatoire
9116 Ce mandat ne peut pas être confirmé
9117 La confirmation doit être effectuée le même jour que la prise du mandat

3.4 - Modification

Modifier un mandat.

 

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

nochrono=chaîne

Numéro de mandat à modifier.

 

date_signature=date

Date de signature pour contrôle.

 

‣ [...]
Champs à modifier.

Résultat :

‣ total=integer

Nombre d'enregistrements.

 

‣ rows=array[object]

Tableau des enregistrements modifiés.

 

code=integer (Seulement si success=false)

Liste des codes d'erreur supplémentaires :
CODES D'ERREUR UTILISATEUR :
9002 La modification de certains champs fournis est interdite
9102 La date de signature et le numéro de mandat sont obligatoires
9103 Ce mandat ne vous appartient pas
9104 L'original a déjà été reçu. La mandat n'est plus modifiable
9105 Le champs "papierrecu" n'est modifiable que par les administrateurs
9106 Le champs "date_recu_original" n'est modifiable que par les administrateurs
9107 Le champs "datebutoir" n'est modifiable que par les administrateurs
9108 Valeur incorrecte pour le champs "papierrecu"
9109 Vous ne pouvez pas marquer l'original comme reçu sans fournir de date de réception
9110 Vous ne pouvez noter la date de réception sans marquer l'original comme reçu
9111 La date de signature fournie ne correspond pas à la date de prise du mandat
9113 La raison sociale est obligatoire pour ce type de mandat
9114 Les coordonnées du bien sont obligatoires pour ce type de mandat 
9118 Le mandat n'est pas modifiable car il n'a pas été confirmé

4 - Gestion des utilisateurs (réservé aux administrateurs)

L'API permet de récupérer le quota et de lire, modifier, activer et désactiver des utilisateurs. La liste des différents champs est disponible en fin de documentation.

4.1 - Récupération du quota

Récupérer le quota.

 

Méthode : GET
Chemin : /user/getQuota
Paramètres : Aucun
Résultat :

‣ max=integer

Nombre maximum d'utilisateurs actifs autorisés.

 

‣ current=integer

Nombre d'utilisateurs actifs actuels.

 

code=integer (Seulement si success=false)

Liste des codes d'erreur supplémentaires :
CODES D'ERREUR UTILISATEUR :
9001 Cette fonction est réservée aux administrateurs

4.2 - Lecture

Lister les utilisateurs.

 

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

util_ref=integer (facultatif)

Filtrer par utilisateur.

 

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. Défaut : 100.

 

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

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

 

Résultat :

‣ total=integer

Nombre d'enregistrements.

 

‣ rows=array[object]

Tableau des enregistrements.

 

code=integer (Seulement si success=false)

Liste des codes d'erreur supplémentaires :
CODES D'ERREUR UTILISATEUR :
9001 Cette fonction est réservée aux administrateurs

4.3 - Création

Créer un utilisateur. L'utilisateur est crée inactif à partir d'un code postal à fournir et nommé "Nouvelle fiche".

 

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

cp=string

Code postal.

Résultat :

‣ total=integer

Nombre d'enregistrements.

 

‣ rows=array[object]

Tableau des enregistrements crées.

 

code=integer (Seulement si success=false)

Liste des codes d'erreur supplémentaires :
CODES D'ERREUR UTILISATEUR :
9001 Cette fonction est réservée aux administrateurs
9200 Seul le champ "cp" est à fournir
9201 Le champ "cp" est obligatoire
9202 Le champ "cp" est doit être au format "01234"

4.4 - Modification

Modifier un utilisateur. Seuls les utilisateurs actifs peuvent être modifiés.

 

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

util_ref=integer

Référence.

 

‣ [...]
Champs à modifier.

Résultat :

‣ total=integer

Nombre d'enregistrements.

 

‣ rows=array[object]

Tableau des enregistrements modifiés.

 

code=integer (Seulement si success=false)

Liste des codes d'erreur supplémentaires :
CODES D'ERREUR UTILISATEUR :
9001 Cette fonction est réservée aux administrateurs
9002 La modification de certains champs fournis est interdite
9203 Les utilisateurs inactifs ne peuvent pas être modifiés
9204 Le champs "code" n'est pas modifiable
9205 Le mot de passe doit être un entier positif

4.5 - Activation

Activer un utilisateur.

 

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

util_ref=integer

Référence.

Résultat : Aucune donnée

 

code=integer (Seulement si success=false)

Liste des codes d'erreur supplémentaires :
CODES D'ERREUR UTILISATEUR :
9001 Cette fonction est réservée aux administrateurs
9206 Le champ "util_ref" est obligatoire
9207 L'utilisateur est déjà actif
9208 Le nombre d'utilisateurs actifs maximum est déjà atteint

4.6 - Désactivation

Désactiver un utilisateur.

 

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

util_ref=integer

Référence.

Résultat : Aucune donnée

 

code=integer (Seulement si success=false)

Liste des codes d'erreur supplémentaires :
CODES D'ERREUR UTILISATEUR :
9001 Cette fonction est réservée aux administrateurs
9206 Le champ "util_ref" est obligatoire
9209 L'utilisateur est déjà inactif

5 - Description de la base de données

Vous trouverez ci-dessous le liste des champs de chaques tables.

5.1 - Champs de la table mandat

Champs Type Modifiable Description
nochrono integer   Numéro de mandat
util_ref string   Référence de l'utilisateur
dateheure date ('YYYY-MM-DD HH-II-SS')   Date de prise du mandat
status string  

Status du mandat :

"L" : Libre

"E" : En cours

"C" : Confirmé

saisi_par_web string   Saisie sur Webmandat

"O" : Oui

"N" : Non

date_saisie_web date ('YYYY-MM-DD HH-II-SS')   Date de saisie sur Webmandat
num_page integer   Numéro de page dans page
num_repertoire integer   Numéro du Registre Répertoire
avant_avenant string   Historique du mandat
location_charges float   Obsolète
papierrecu string  

Papier reçu :

"N" : Non
"F" : Fax 
"I" : Original sans saisie Web
"O" : Original reçu

date_recu_original date ('YYYY-MM-DD')   Date de réception de l'original
datebutoir date ('YYYY-MM-DD HH-II-SS')   Date butoir de réception de l'original
date_signature date ('YYYY-MM-DD')   Date de signature pour contrôle
date_expiration date ('YYYY-MM-DD') Date d'expiration
a_la_charge string A la charge de :

"V": Vendeur

"A": Acquéreur

"D": Les deux

civilite_mandant string

Civilité du mandant :

"Mr"
"Mme"
"Melle"
"Mr&Mme"
"Mr&Melle"
"Mme&Melle"
"Mr&Mr"
"Mme&Mme"
"Melle&Melle"
"SARL"
"SA"
"SAS"
"SCA"
"SCEA"
"SCCV"
"SCI"
"SNC"
"EURL"
"EARL"
"INDIVISION"
"GFA"
"SOCIETE"

nom_mandant string Nom du mandant
adresse_mandant string Adresse du mandant
cp_mandant string Code postal du mandant
ville_mandant string Ville du mandant
tel_mandant string Téléphone du mandant
email_mandant string Email du mandat
type_mandat string

Type de mandat

"V": Vente

"L": Location

"R": Recherche

"D": Délégation

forme_mandat string

Forme du mandat :

"S": Simple

"M": Semi-exclusif

"E": Exclusif

"P": Partenaire

adresse_bien string Adresse du bien
cp_bien string Code postal du bien
ville_bien string Ville du bien
nature string Nature du bien
prix_vente float Prix de vente
param_prix string

Commission :

"C": Commission comprise

"N": Net vendeur

"H": Hors Taxes

commentaire string Message destiné au secrétariat
commission_agence float Commission
raison_sociale string

Raison sociale d'une SARL / Représentant d'une indivision

(A remplir en cas d'indivision ou SARL)

nombre_lots integer Nombre de lots
observation string Observations sur le registre
location_caution float Dépôt de garantie
location_meublee string

Meublée :

"O": Oui

"N": Non

autres_mandant string Autres mandants
is_avenant bool Est un avenant
nomandat_origine integer Si avenant, numéro du mandat d'origine
prix_vendu float Prix vendu (Fin de mandat)
date_vendu date ('YYYY-MM-DD') Date de la vente (Fin de mandat)
vendu_par string

Type de vente (Fin de mandat) :

"n": Vendu par nous

"p": Vendu par un autre professionnel

"r": Vendu par le propriétaire

"v": Retiré de la vente

surface_hab_vendu float Surface habitable (Fin de mandat)
surface_ter_vendu float Surface terrain (Fin de mandat)

5.1 - Champs de la table utilisateur

Champs Type Modifiable Description
util_ref integer   Référence
code string   Code utilisateur
password integer Mot de passe
droit string

Type d'utilisateur

"A": Administrateur

"U": Utilisateur

nbmandatmax integer Nombre de mandat maximum
contact_civilite string Civilité
contact_nom string Nom
contact_tel string Téléphone
contact_fax string Fax
contact_mobile string Mobile (reconnu par Mandavox)
contact_e_mail string Email
contact_obs string Observations