Documentation
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 pour acquereur-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 global honorary_rate ne 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

  1. Mettre à jour vos référentiels : les dimensions des pièces, deleted_at et fee_repartition_type.
  2. Traiter les refus en 422 de la 3.4 : une rétrocession hors barème, un montant pour un payeur avec un taux pour l'autre.
  3. Revoir l'envoi des honoraires : un montant envoyé sans taux est désormais gardé tel quel.
  4. Tester sur /api/v3.4/ avec vos clés habituelles. Les mêmes clés apiKey et apiToken servent tous les préfixes, sur les mêmes boards.
  5. Contrôler l'en-tête X-Api-Version de vos réponses réussies : il vaut 3.4 sur le nouveau préfixe. Les réponses d'erreur ne le portent pas.
  6. 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 apiKey et apiToken, 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 422 décrits plus haut