Référence API
Migrer de la v3.3 vers la v3.4
La version 3.4 de l'API MLS CONNECT est servie sous le préfixe
/api/v3.4/. Les préfixes /api/v3/, /api/v3.1/, /api/v3.2/ et /api/v3.3/ continuent de servir les versions 3.0 à 3.3, sans aucun changement de forme. Vous migrez donc quand vous le décidez : rien ne change pour vous tant que vous n'avez pas modifié vos URLs.La 3.4 ne retire ni ne renomme aucun champ. Elle ajoute de nouvelles clés, des routes pour les groupes et sections du board et un paramètre d'écriture pour les passerelles d'agence. Elle garde aussi le montant des honoraires que vous envoyez sans taux, et refuse en
422 une rétrocession hors du barème du MLS comme des honoraires qui mêlent montant et taux. Tout cela ne vaut que sous le nouveau préfixe. La description complète de chaque route et de chaque champ est dans la documentation de référence, qui décrit la version 3.4.Ce qui change
| Point | 3.0 à 3.3 | 3.4 |
|---|---|---|
width, length et irregular d'une pièce |
absents, ignorés à l'écriture | servis et écrits |
deleted_at d'un message de connect |
absent, le message supprimé est servi au texte vide | servi |
fee_repartition_type dans le détail d'un bien |
absent | servi |
| Honoraires envoyés en montant, sans taux | montant recalculé à partir du taux | montant gardé, taux déduit |
| Un montant pour un payeur et un taux pour l'autre | accepté | refusé en 422
|
| Routes des groupes et sections du board | 404 |
servies |
send_request d'une passerelle d'agence |
ignoré | appliqué |
Les dimensions des pièces
Chaque pièce de
rooms_details porte width et length, sa largeur et sa longueur, dans l'unité du bien : mètres pour un bien en m², pieds pour un bien en pieds carrés. irregular indique une pièce de forme irrégulière. Ces clés se lisent et s'écrivent sous /api/v3.4/ ; sous un préfixe antérieur, elles sont absentes des réponses et ignorées à l'écriture. La surface area de la pièce reste servie sous tous les préfixes.
À faire : accepter ces clés, et envoyer les dimensions dans l'unité du bien.
La date de suppression d'un message de connect
Chaque message d'un connect, dans
messages comme dans last_message, porte deleted_at : la date à laquelle son auteur l'a supprimé, null sinon. Sous un préfixe antérieur, un message supprimé reste servi, avec un texte vide.
À faire : vous fier à
deleted_at pour reconnaître un message supprimé, plutôt qu'à un texte vide.La rétrocession
Le détail d'un bien sert
fee_repartition_type : la part des honoraires reversée à l'agence collaboratrice, en %. "50" correspond à un partage 50/50, "40" à un partage 60/40. Elle vaut null tant qu'elle n'est pas renseignée, ou quand le partage n'est pas en pourcentage. Le taux servi est celui retenu par le MLS, qui peut l'ajuster à la validation du bien.fee_repartition_type se pose à la création, avec une valeur du barème du MLS (60, 50, 40, voire 30 et 20 selon le MLS) : une autre valeur est refusée en 422, avec la liste des valeurs admises. Renvoyer la valeur déjà enregistrée sur le bien passe toujours, et une valeur différente envoyée pour un bien qui en a déjà une est ignorée.
À faire : traiter le
422, et n'envoyer que les valeurs du barème.Les honoraires : montant ou taux
La méthode de calcul des honoraires se déduit de
financial.honorary :-
un montant sans aucun taux (
honorary_buyer,honorary_seller, ou les deux pouracquereur-et-vendeur) : le MLS garde exactement ce montant et en déduit le pourcentage ; -
un taux (
honorary_rate_buyer,honorary_rate_seller) : le montant est recalculé à partir du taux et du prix à la mise en ligne, même si un montant l'accompagne. Le taux globalhonorary_ratene compte pas ; - aucun honoraire dans l'envoi : la méthode du bien ne change pas.
Un montant pour un payeur et un taux pour l'autre est refusé en
422. Sous un préfixe antérieur, le montant est toujours recalculé à partir du taux.
À faire : si vous voulez que le MLS garde votre commission au centime, envoyez le montant sans taux.
Les groupes et sections du board
Les routes Groupes et sections du board listent les groupes du board et leurs sections : ce sont les valeurs qu'acceptent
mls_board_group et mls_board_section à l'écriture d'une agence. D'autres routes les créent, les renomment et les suppriment, avec des droits supplémentaires. Sous un préfixe antérieur, ces routes répondent 404.La demande d'activation d'une passerelle d'agence
La création et la mise à jour d'une passerelle d'agence acceptent
send_request: true, qui envoie au logiciel la demande d'activation de la passerelle. Sous un préfixe antérieur, send_request est ignoré et rien ne part.Marche à suivre
-
Mettre à jour vos référentiels : les dimensions des pièces,
deleted_atetfee_repartition_type. -
Traiter les refus en
422de la 3.4 : une rétrocession hors barème, un montant pour un payeur avec un taux pour l'autre. - Revoir l'envoi des honoraires : un montant envoyé sans taux est désormais gardé tel quel.
-
Tester sur
/api/v3.4/avec vos clés habituelles. Les mêmes clésapiKeyetapiTokenservent tous les préfixes, sur les mêmes boards. -
Contrôler l'en-tête
X-Api-Versionde vos réponses réussies : il vaut3.4sur le nouveau préfixe. Les réponses d'erreur ne le portent pas. - Basculer le préfixe dans votre configuration. Aucune autre modification d'URL n'est nécessaire : les routes existantes sont identiques.
# avant GET https://app.mls-connect.com/fr/api/v3.3/properties/search?mls_board=xxx # après GET https://app.mls-connect.com/fr/api/v3.4/properties/search?mls_board=xxx
Si vous êtes sur un préfixe plus ancien, passez directement à la 3.4 en appliquant aussi les changements décrits dans Migrer de la v3 vers la v3.1, Migrer de la v3.1 vers la v3.2 et Migrer de la v3.2 vers la v3.3.
Ce qui ne change pas
- La forme des réponses : aucun champ n'est retiré, renommé ni retypé
- Les routes existantes et leurs paramètres
- Les filtres de recherche et leur sens
- L'authentification par
apiKeyetapiToken, et les droits par board - La pagination et les curseurs
- Les codes HTTP des erreurs, tels que la 3.2 les a fixés, en dehors des deux refus en
422décrits plus haut