API Webmandat






Documentation 
API Webmandat

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 : https://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)

Code d'erreur.

100=Session expirée

101=Identification échouée

102=Erreur fatale

 

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 effectuer des tests, vous pouvez utiliser les identifiants suivants :

code=55555

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.

 

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

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

Résultat :

‣ total=integer

Nombre d'enregistrements.

 

‣ rows=array[object]

Tableau des enregistrements.

 

 

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

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.

4.2 - Lecture

Lister les utilisateurs.

 

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

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

Résultat :

‣ total=integer

Nombre d'enregistrements.

 

‣ rows=array[object]

Tableau des enregistrements.

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.

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.

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

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

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
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 integer 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 integer 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 integer 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 integer Surface habitable (Fin de mandat)
surface_ter_vendu integer 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