Référence API
Vue d'ensemble de l'écosystème
mlsconnect se positionne comme un hub central entre les logiciels métier (CRM) des agences immobilières, le portail consommateur Melsia.immo, les partenaires du board MLS, et les sites web des agences. La plateforme reçoit les biens des CRM (FTP/API) et redistribue la totalité du portefeuille MLS via API sortante.
Principe de symétrie — L'agent travaille indifféremment depuis mlsconnect ou son CRM. Même résultat pour le consommateur, même historique dans le suivi d'activité.
Les acteurs de l'écosystème
| Acteur | Rôle | Flux |
|---|---|---|
| CRM métier | Pousse les biens via FTP/API. Récupère le portefeuille MLS complet via API sortante. | Bidirectionnel |
| mlsconnect | Hub central. Compile, stocke, redistribue. Génère les emails Melsia. | Hub |
| Melsia.immo | Portail consommateur couplé en temps réel. Espaces personnels des prospects. | Bidirectionnel avec mlsconnect |
| Consommateur | Reçoit les propositions par email. Interagit via Melsia (Favorite, Refused, Connect). | Toujours via Melsia |
| Partenaires du board MLS | Accès au flux global (biens disponibles uniquement). Contrat RGPD obligatoire. | Lecture seule |
| Sites web agences | Alimentés soit par mlsconnect (API flux web) soit par le CRM (avec autorisations de diffusion). | Double source |
API sortante : deux types d'accès
Accès global — dépend du niveau de credentials :
- Credentials CRM : accès aux biens des agences clientes du CRM uniquement (celles avec passerelle entrante). Pour chaque agence, accès complet : mandats + biens sélectionnés + vendus + retirés.
- Credentials Partenaire (contrat RGPD) : accès à tout le portefeuille MLS de toutes les agences du board — uniquement les biens disponibles (sans vendus, sans retirés, sauf options activées).
Flux logiciel — panier alimenté manuellement par chaque agence dans mlsconnect :
- L'agence y ajoute des biens d'autres agences pour effectuer des adéquations dans son CRM.
- Ne contient que des biens disponibles.
- Ne doit pas être diffusé sur le site web de l'agence.
- Ne nécessite pas d'autorisation de diffusion active.
3 niveaux de credentials
| Niveau | Périmètre | Accès contacts/alertes |
|---|---|---|
| Agence Web | Données d'une agence identifiée (mandats + flux logiciel + flux web + vendus + retirés) | Oui |
| CRM | Agence Web automatique pour toutes les agences clientes (passerelle entrante) | Oui |
| Partenaire | Flux global d'un board MLS — biens disponibles uniquement (contrat RGPD) | Non |
Combinaison recommandée : CRM (pour accéder aux contacts, alertes et mandats) + Partenaire (pour le portefeuille MLS complet).
Couplage Melsia.immo et MonCourtier
Lorsqu'un agent envoie une proposition, le consommateur reçoit un email (template Melsia) avec un lien. À la première connexion, un espace personnel est auto-créé. Le consommateur peut interagir (J'aime, Refuse) ou engager un dialogue Connect (messagerie : demande de visite, d'information, tout échange) avec son courtier. Grâce à MonCourtier, toute navigation sur Melsia renvoie vers son agent. Le consommateur n'a aucun lien direct avec mlsconnect.
Sites web agences : double alimentation
-
Option A — mlsconnect alimente le site via l'API
Flux web
(biens avec autorisation de diffusion active). - Option B — Le CRM alimente le site. mlsconnect fournit les routes API d'Autorisation de diffusion pour les biens confrères.
Cycle de vie d'un bien immobilier
Point clé —
transaction_type est le champ unique portant type + statut. Pas de champ "status" séparé (property_status = null en production).Statuts hors ligne (non visibles dans les recherches API sauf exceptions)
| Slug API | Nom | Description | Accès API |
|---|---|---|---|
draft |
Brouillon | Mandat en création | Interne uniquement |
estimate |
Estimation | Évaluation en cours | Interne uniquement |
validation |
Attente de validation | Revue avant publication | Interne uniquement |
mandate-withdrawal |
Retiré | Retiré par mandant, passerelle ou échéance | Visible par référence. Option Partenaire : inclus dans le flux global si activée |
Statuts en ligne (visibles dans les flux API)
| Slug API | Nom | Description | is_on_portal |
is_mls |
|---|---|---|---|---|
for-sale |
À vendre | Bien actif sur le marché | true |
true * |
rent |
À louer | Bien actif en location | true |
true * |
under-offer |
Sous offre acceptée | Offre en cours | false |
true |
under-agreement |
Sous compromis | Vente en finalisation | variable | true |
sold |
Vendu | Transaction finalisée | false |
false |
to-rent |
Loué | Location finalisée | false |
false |
* Si mandat exclusif/open/co-exclusif + agence MLS + date de partage atteinte.
Observation API confirmée —
under-offer : is_on_portal=false mais is_mls=true. Retiré du portail consommateur, reste visible entre agents MLS.
Flags de visibilité
| Flag | Description | Conditions |
|---|---|---|
is_mls |
Partageable entre agences MLS | En ligne + mandat exclu/open/co-exclu + agence MLS + date partage atteinte |
is_on_portal |
Visible B-to-C (Melsia) |
for-sale ou rent + mandat partageable. False pour under-offer
|
is_private |
Privé à l'agence | Mandat simple, off-market, ou retiré. Option Partenaire : visible dans le flux global si activée |
online |
Bien publié et en ligne |
true = en ligne, false = hors ligne |
Options Partenaire (activables par board MLS)
Options Partenaire (configurables par board) : 1. Retirés visibles —
mandate-withdrawal inclus dans le flux global. 2. Privés visibles — is_private=true inclus dans le flux global.Types de mandat
| Slug | Nom | Partageable MLS |
|---|---|---|
exclusive |
Exclusif | Oui |
co-exclusive |
Co-exclusivité | Oui |
open |
Open | Oui |
simple |
Simple | Non (sauf option board). Option Partenaire possible |
off-market |
Off-market | Non (toujours privé). Option Partenaire possible |
Définition Biens actifs
pour les CRM
| Usage | Flag | Ce que ça inclut |
|---|---|---|
| Biens actifs B-to-B (CRM) | is_mls = true |
Biens à reprendre dans le CRM pour le travail inter-agences. Inclut : for-sale, rent, under-offer, under-agreement. |
| Biens visibles B-to-C (Portails) | is_on_portal = true |
Biens à afficher aux consommateurs. Exclut automatiquement under-offer. Inclut : for-sale, rent (mandats partageables). |
| Vendus / Loués (analyse) | transaction_type = sold, to-rent |
Réservé aux analyses : prix au m², comparables, historique marché. |
Principe — Les flags
is_mls et is_on_portal font la synthèse de toutes les conditions. Un CRM n'a pas besoin de combiner manuellement les slugs transaction_type.Flux Contacts, Propositions et Melsia
Phase A — Préparation (optionnelle)
Optionnel — La route de proposition (Phase B) crée le contact et le projet automatiquement s'ils n'existent pas. Les étapes 1-3 sont utiles pour les CRM qui veulent un contrôle fin.
Étape 1 — Synchroniser ou créer le contact en amont.
GET /contacts (sync différentielle) ou POST /contacts (à créer — optionnel).
Étape 2 — Créer un projet (alerte) en amont.
POST /alerts (à créer — optionnel).
Étape 3 — Sélectionner les biens à proposer parmi le portefeuille MLS.
| Workflow détaillé | Workflow simplifié |
|---|---|
| Étapes 1-2-3 puis la route propose. Contrôle fin sur chaque entité. 3 appels API puis la route propose. | Directement la route propose avec les coordonnées du contact et les property_ids. 1 seul appel API. |
Phase B — Envoi de la proposition (route clé)
Route clé :
POST /alerts/{id}/propose — L'envoi de propositions par email existe déjà dans mlsconnect (bouton "Email"). La route API permet au CRM de déclencher exactement la même action.
Étape 4 — Pousser un email de proposition au consommateur via mlsconnect.
Traitement par mlsconnect :
1. Crée le contact s'il n'existe pas
2. Crée le projet (alerte) s'il n'existe pas
3. Ajoute les biens dans
properties[] avec statut suggested
4. Génère l'email avec template Melsia
5. Envoie au consommateur depuis l'adresse de l'agence (SMTP configuré)
6. Enregistre dans le suivi d'activité (identique à un envoi depuis l'interface)
7. Auto-création de l'espace Melsia si première proposition
8. Activation MonCourtier
Symétrie — Identique à un envoi depuis l'interface mlsconnect. Même historique dans le suivi d'activité.
Phase C — Interactions du consommateur via Melsia
Étape 5 — Le consommateur reçoit l'email et ouvre le lien. Espace personnel auto-créé à la première connexion.
Étape 6 — Le consommateur interagit avec les biens :
| Interaction | Description | Impact |
|---|---|---|
| Favorite | J'aime ce bien | Statut → favorite
|
| Refused | Je n'aime pas | Statut → refused
|
| Connect | Messagerie : demande de visite, d'information, tout échange | Dialogue bidirectionnel temps réel |
Étape 6b — MonCourtier : toute la navigation du consommateur sur Melsia renvoie vers son courtier.
Phase D — Récupération des feedbacks par le CRM
Préconisation : ne pas synchroniser les conversations Connect dans le CRM. Statuts propositions = données à synchroniser (polling). Conversations = expérience à déléguer (fenêtre native mlsconnect).
Étape 7a — Statuts des propositions (polling)
Le CRM interroge
GET /alerts/{id} périodiquement. Les statuts passent de suggested à favorite ou refused. Le champ updated_at change à chaque interaction.
Étape 7b — Conversations Connect (auto-connect en fenêtre native)
L'API fournit une URL d'auto-connect dans la réponse de
GET /connects. Le CRM ouvre cette URL dans une nouvelle fenêtre du navigateur. L'agent est automatiquement authentifié. Pas de polling des messages.
Chemin unique : CRM → mlsconnect → Melsia → Consommateur → Melsia → mlsconnect → CRM.
Catalogue des routes API
Principe — La route
POST /alerts/{id}/propose est autonome : elle crée le contact et le projet s'ils n'existent pas. Un CRM peut envoyer une proposition en 1 seul appel.Biens (portefeuille MLS)
| Méthode | Route | Statut | Description |
|---|---|---|---|
| GET | /properties |
Existant | Recherche biens. Portefeuille MLS selon credentials. |
| GET | /properties/{id} |
Existant | Détail complet d'un bien. |
Agences et agents
| Méthode | Route | Statut | Description |
|---|---|---|---|
| GET | /agencies |
Existant | Agences du board + agents (nested). |
| GET | /users/{id} |
Existant | Détail agent. |
Contacts
| Méthode | Route | Statut | Description |
|---|---|---|---|
| GET | /contacts |
Existant | Contacts de l'agence. Sync différentielle. |
| GET | /contacts/{id} |
Existant | Détail contact. |
| POST | /contacts |
À créer — optionnel | Créer un contact. La route propose le crée automatiquement. |
| PUT | /contacts/{id} |
À créer — optionnel | Mettre à jour un contact. |
Projets / alertes
| Méthode | Route | Statut | Description |
|---|---|---|---|
| GET | /alerts |
Existant | Projets d'un contact avec propositions et statuts. |
| GET | /alerts/{id} |
Existant | Route de polling principale pour les feedbacks. |
| POST | /alerts |
À créer — optionnel | Créer un projet. La route propose le crée automatiquement. |
Envoi de propositions (route clé)
| Méthode | Route | Statut | Description |
|---|---|---|---|
| POST | /alerts/{id}/propose |
★ À créer — route clé | Email de proposition via mlsconnect. Autonome : crée contact et projet si nécessaire. |
Body :
{ "property_ids": [...], "contact": {...} (si nouveau), "message": "..." (optionnel) }
Conversations (connects)
| Méthode | Route | Statut | Description |
|---|---|---|---|
| GET | /connects?contact={id} |
Existant — usage corrigé | Récupérer l'URL auto-connect. Pas de polling des messages. |
| GET | /connects/{id} |
Existant — usage corrigé | Détail fil → URL auto-connect en fenêtre native. |
Les conversations sont une expérience à déléguer : le CRM ouvre la fenêtre mlsconnect native via URL auto-connect.
Refus de collaboration (flux global uniquement)
| Méthode | Route | Statut | Description |
|---|---|---|---|
| GET | /agencies/{id}/collaboration_refusal |
Existant | Refus de collaboration entre agences. Spécifique aux groupements qui limitent le partage. Ne s'utilise qu'avec le flux global Partenaire. |
Synthèse
| Catégorie | Nombre |
|---|---|
| Routes existantes | 11 |
| Route clé à créer | 1 (POST /alerts/{id}/propose) |
| Routes optionnelles à créer | 3 (POST /contacts, PUT /contacts/{id}, POST /alerts) |
| Usages corrigés | 2 (GET /connects → auto-connect) |
| Total | 15 routes |
Diagramme de séquence
| # | Émetteur | Récepteur | Action | Route API |
|---|---|---|---|---|
| 1 | CRM | mlsconnect | Créer/synchroniser contact (optionnel) | POST /contacts |
| 2 | CRM | mlsconnect | Créer projet (optionnel) | POST /alerts |
| 3 | CRM | (local) | Sélectionner biens (optionnel) | GET /properties |
| 4 | CRM | mlsconnect | Envoyer proposition (route clé) | POST /alerts/{id}/propose |
| 5 | mlsconnect | Melsia | Sync biens + générer email Melsia | (couplage interne) |
| 6 | Melsia | Consommateur | Email + lien (auto-création espace) | (email template) |
| 7 | Consommateur | Melsia | Ouvrir, consulter biens | (navigation) |
| 8 | Consommateur | Melsia | Favorite / Refused / Connect (messagerie) | (actions) |
| 9 | Melsia | mlsconnect | Sync feedbacks temps réel | (couplage interne) |
| 10 | CRM | mlsconnect | Récupérer statuts propositions (polling) | GET /alerts/{id} |
| 11 | CRM | mlsconnect | Afficher conversations (auto-connect) |
GET /connects → URL |
Workflow simplifié (1 seul appel) — Un CRM peut sauter directement à l'étape 4. La route de proposition crée le contact et le projet automatiquement. Les étapes 1-3 ne sont utiles que pour un contrôle fin.
Boucle continue — Le CRM répète l'étape 10 en polling périodique (sync différentielle par
updated_at). L'étape 11 est déclenchée à la demande de l'agent.Règles de synchronisation
Synchronisation des biens
1. Sync par différentiel temporel —
updated_at_gte = timestamp dernière sync. Ne jamais télécharger le fichier complet.
2. Rate limit : 350 requêtes / 10 secondes. Fréquence : 1x/heure, 8h-19h (Paris), minute aléatoire. Backoff HTTP 429.
3. Pagination max 10 biens/page — ~200 KB/propriété. Paramètres :
per_page = nombre de biens par page, page = page courante. Comptages : per_page: 1 (le total est dans les métadonnées de pagination).
4. Photos : respecter le cache — Comparer hash/URL avant téléchargement. Ne pas re-télécharger à chaque sync.
Filtrage des biens
5. Biens actifs B-to-B :
is_mls = true. Biens visibles B-to-C : is_on_portal = true. Les flags font la synthèse — pas besoin de combiner les slugs.
6. Flags de visibilité :
is_mls, is_on_portal (false pour under-offer), is_private. Le CRM doit respecter ces restrictions.
7. Retirés exclus des flux actifs —
mandate-withdrawal hors recherches générales. Visible par référence uniquement, sauf option Partenaire.Contacts et feedbacks
8. Polling statuts —
GET /alerts/{id} : suggested → favorite / refused. Le updated_at change à chaque interaction.
9. Conversations : auto-connect, pas de polling. URL auto-connect en fenêtre native mlsconnect.
Contraintes d'intégrité
10. Archivage contact = inactivation projets. Ne pas proposer à un contact archivé.
11. Bien retiré/privé = supprimé de tous paniers sauf mandataire. Vérifier le statut avant affichage.
12. Agence inactive = cascade (autorisations refusées, biens retirés, contacts archivés). Détecter via
agency.active=false.Symétrie CRM / mlsconnect
13. Toute action API = même résultat que l'interface. Suivi d'activité identique.
Glossaire
Plateforme et écosystème
| Terme | Définition |
|---|---|
| mlsconnect | Hub central de partage de mandats exclusifs entre agences immobilières. |
| MLS | Multiple Listing Service — réseau de partage de mandats. |
| Board MLS | Groupement régional d'agences (ex: MLS Côte d'Azur, id: Yv68Wm). Peut configurer des options spécifiques. |
| Melsia.immo | Portail consommateur couplé en temps réel avec mlsconnect. Espaces personnels et MonCourtier. |
| MonCourtier | Affiliation automatique consommateur-agent sur Melsia. Navigation toujours liée au courtier. |
| Partenaires du board | CRM/plateformes autorisées au flux global (contrat RGPD). Biens disponibles, sauf options activées. |
| Principe de symétrie | Action API = même résultat que l'interface mlsconnect. Même historique dans le suivi d'activité. |
Slugs API — transaction_type
| Terme | Définition |
|---|---|
for-sale |
À vendre — bien actif sur le marché. |
rent |
À louer — bien actif en location. |
under-offer |
Sous offre acceptée. is_on_portal=false, is_mls=true. |
under-agreement |
Sous compromis — vente en finalisation. |
sold |
Vendu — réservé aux analyses. |
to-rent |
Loué — inclus dans la définition Locationactive. |
mandate-withdrawal |
Retiré. Exclu des recherches. Option Partenaire : inclus si activée. |
Slugs API — mandate
| Terme | Définition |
|---|---|
exclusive |
Mandat exclusif — partageable MLS. |
co-exclusive |
Co-exclusivité — partageable MLS. |
open |
Mandat open — partageable MLS. |
simple |
Simple — privé sauf option board. Option Partenaire possible. |
off-market |
Off-market — toujours privé. Option Partenaire possible. |
Flags de visibilité
| Terme | Définition |
|---|---|
is_mls |
Partageable entre agences MLS. |
is_on_portal |
Visible sur Melsia (B-to-C). False pour under-offer. |
is_private |
Privé à l'agence. Simple, off-market, ou retiré. Option Partenaire possible. |
online |
Bien publié et en ligne (true/false). |
Flux et accès
| Terme | Définition |
|---|---|
| Passerelle | Connecteur CRM ↔ mlsconnect (entrante FTP/API ou sortante API). |
| Flux logiciel | Panier alimenté manuellement par agence pour adéquations CRM. Biens disponibles. Ne pas diffuser sur le site web. |
| Flux site web | Biens autorisés pour diffusion internet (autorisation requise). |
| Flux global | Flux Partenaire : toutes les propriétés disponibles du board. Contrat RGPD. |
| Autorisation de diffusion | Accord entre agences pour diffuser les biens confrères. Individuelle ou permanente. |
| Refus de collaboration | Mécanisme de groupement limitant le partage entre agences identifiées. Flux global uniquement. |
| Options Partenaire | Options configurables par board : retirés visibles et privés visibles dans le flux global. |
Concepts techniques
| Terme | Définition |
|---|---|
| Sync différentielle | Par timestamp updated_at_gte. Uniquement les modifications. |
| Rate limit | 350 requêtes / 10 secondes. HTTP 429 en cas de dépassement. |
| Template Melsia | Email généré par mlsconnect pour les propositions. Dépend de l'abonnement. |
| Espace personnel | Espace consommateur sur Melsia, auto-créé à la 1ère connexion. |
| Connect | Fil de discussion agent-prospect. Le CRM ne synchronise pas les messages : auto-connect en fenêtre native. |
| URL auto-connect | URL fournie par l'API pour ouvrir une page mlsconnect en fenêtre native avec authentification automatique. |
| Suivi d'activité | Historique des actions sur un bien. Les actions API y apparaissent comme les actions interface (symétrie). |