MonHubImmo

Documentation API Partenaire

Vue d'ensemble fonctionnelle de l'API MonHubImmo pour les réseaux immobiliers.

Introduction

L'API partenaire MonHubImmo permet aux réseaux immobiliers d'intégrer la plateforme directement dans leur système d'information. Toutes les opérations sont disponibles via une API REST standard.

URL de base

https://api.monhubimmo.fr/api/external/v1

Format

JSON (requêtes et réponses)

Rate limiting

250 requêtes / minute

Toutes les réponses sont en JSON avec un champ success (booléen). En cas de succès, la ressource est renvoyée sous son propre nom à la racine (users, property, searchAd…) : il n'y a pas de clé data. En cas d'échec, les champs sont error et message (ou details[] sur une erreur de validation). Les identifiants d'URL sont des ObjectId MongoDB, pas vos externalId.

Authentification

Toutes les requêtes API doivent inclure votre clé API dans le header X-API-Key.

Obtenir vos clés

Contactez notre équipe via le formulaire de contact pour recevoir vos identifiants API (clé API et secret pour les webhooks).

Exemple de requête authentifiée
curl -X GET "https://api.monhubimmo.fr/api/external/v1/users" \
  -H "X-API-Key: votre-cle-api" \
  -H "Content-Type: application/json"
Réponse type
{
  "success": true,
  "users": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "totalPages": 3
  }
}

Gestion des utilisateurs

Créez et gérez les comptes de vos agents directement depuis votre SI. Chaque agent créé via l'API est automatiquement rattaché à votre réseau partenaire.

Créer un agent

Créez un compte pour un nouvel agent de votre réseau. Un email de bienvenue lui sera automatiquement envoyé. La validation automatique du compte et l'abonnement accordé à la création (Découverte, Standard ou Premium, sans paiement) sont définis dans la configuration de votre réseau partenaire. Le champ facultatif planpermet d'accorder un plan inférieur à un agent donné.

POST /users
{
  "email": "agent@monreseau.fr",
  "firstName": "Marie",
  "lastName": "Dupont",
  "phone": "0612345678",
  "externalId": "agent-123",
  "plan": "essentiel",
  "professionalInfo": {
    "city": "Paris",
    "postalCode": "75011",
    "interventionRadius": 25,
    "coveredCities": [
      { "city": "Paris", "postalCode": "75011" }
    ],
    "yearsExperience": 8,
    "personalPitch": "Bio de 250 à 1500 caractères — en dessous de 250, l'appel échoue en 422."
  }
}
professionalInfo est requis en entier à la création, avec au moins une commune dans coveredCities et un personalPitch de 250 à 1500 caractères — l'erreur la plus fréquente. Chaque couple ville / code postal est géocodé : un seul échec fait échouer tout l'appel (422 Geocoding error). Le champ userType n'est pas accepté : l'API ne crée que des agents.

Lister les agents

Récupérez la liste de tous les agents de votre réseau avec pagination.

GET /users?page=1&limit=20
{
  "success": true,
  "users": [
    {
      "id": "507f1f77bcf86cd799439011",
      "externalId": "agent-123",
      "email": "agent@monreseau.fr",
      "firstName": "Marie",
      "lastName": "Dupont",
      "isValidated": true,
      "profileCompleted": true,
      "createdAt": "2026-11-10T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "totalPages": 3
  }
}

Un agent n'a pas de champ status : son état se lit dans isValidated et profileCompleted. Filtres disponibles : email (partiel), externalId (exact), page, limit (défaut 20, maximum 100).

Activer / Désactiver un agent

Gérez le statut de vos agents. Un agent désactivé ne peut plus se connecter.

POST /users/:id/activate
// Corps vide. :id est l'ObjectId renvoyé à la création.
{
  "success": true,
  "user": {
    "id": "507f1f77bcf86cd799439011",
    "email": "agent@monreseau.fr",
    "firstName": "Marie",
    "lastName": "Dupont",
    "externalId": "agent-123",
    "isValidated": true
  },
  "message": "User activated successfully"
}
POST /users/:id/deactivate
// Corps vide. Répond 400 « No change needed » si le compte
// est déjà dans l'état demandé.

Gestion des biens immobiliers

Synchronisez automatiquement les biens de vos agents avec MonHubImmo. Publiez, mettez à jour et retirez des annonces programmatiquement.

Publier un bien

Créez une annonce pour un bien immobilier au nom d'un de vos agents.

POST /properties
{
  "userId": "507f1f77bcf86cd799439011",
  "externalId": "bien-456",
  "title": "Appartement T3 lumineux — Paris 11e",
  "propertyType": "Appartement",
  "transactionType": "Vente",
  "price": 450000,
  "surface": 65,
  "rooms": 3,
  "city": "Paris",
  "postalCode": "75011",
  "sector": "Quartier Saint-Ambroise",
  "description": "Bel appartement traversant de 50 caractères minimum, sinon l'appel échoue."
}
userId est l'ObjectId de l'agent (pas son externalId), sector est requis, et la description fait au moins 50 caractères. Les énumérations d'un bien sont en français capitalisé : Appartement, Maison, Terrain, Local commercial, Bureaux et Vente / Location — à ne pas confondre avec le vocabulaire anglais des recherches acquéreurs. Le bien est créé en status: "draft" : un second appel est nécessaire pour le publier.

Mettre à jour un bien

Modifiez les informations d'un bien existant (prix, description, statut...).

PUT /properties/:id (ou PATCH, équivalent)
{
  "price": 440000,
  "status": "active"
}

Statuts écrivables par le partenaire : draft, active, archived — ni sold ni rented. Modifier le prix d'un bien engagé dans une collaboration en cours répond 409 Conflict.

Essai gratuit terminé (403 TRIAL_ENDED) : pour un agent inscrit après l'activation de l'essai (14 jours, droits Standard) dont l'essai est terminé sans abonnement ni plan accordé par votre réseau, la création d'un bien ou d'une recherche et la mise en ligne (status: "active") d'un brouillon, d'une archive ou d'une recherche en pause sont refusées.

Restent acceptés : la modification et l'archivage de ses annonces, qui restent en ligne (une synchronisation peut toujours retirer un bien vendu), et toutes les lectures. Un agent à qui votre réseau accorde un plan n'est jamais concerné. Le refus n'est pas transitoire : il cesse quand l'agent s'abonne.

Consulter et retirer

Consultez les détails d'un bien, ou listez vos propres biens tous statuts confondus. Pour retirer un bien, archivez-le : l'API externe n'expose aucune méthode DELETE.

GET /properties/:id
// Réponse : { "success": true, "property": { ... } }
GET /properties/mine?externalId=bien-456
// Vos biens créés via l'API, brouillons et archivés compris.
// C'est le chemin pour retrouver l'ObjectId à partir de votre
// propre référence : properties[0].id
PATCH /properties/:id — retirer un bien
{
  "status": "archived"
}

Recherches acquéreurs

Diffusez les critères de recherche de vos acquéreurs sur MonHubImmo. Le système de matching automatique rapproche les recherches avec les biens disponibles.

Diffuser une recherche

Créez une annonce de recherche acquéreur pour un de vos agents.

POST /search-ads
{
  "userId": "507f1f77bcf86cd799439011",
  "externalId": "recherche-789",
  "title": "Recherche T3/T4 Paris 11e",
  "description": "Description de 10 à 2000 caractères, requise.",
  "projectType": "primary",
  "propertyTypes": ["apartment"],
  "budget": { "max": 500000, "ideal": 460000, "financingType": "loan" },
  "minSurface": 55,
  "location": {
    "cities": ["Paris"],
    "postalCodes": ["75011"],
    "maxDistance": 10
  }
}
Trois pièges ici : description est requise (10 à 2000 caractères) ; budget n'a pas de min (seulement max, ideal, financingType…) ; et location.departments n'existe pas — utilisez cities, postalCodes et maxDistance. Les types de bien d'une recherche sont en anglais minuscule : house, apartment, land, building, commercial. Contrairement à un bien, une recherche est créée directement en status: "active". Statuts écrivables : active, paused, archived.

Matching automatique

Lorsqu'un bien correspond aux critères d'une recherche (ou inversement),MonHubImmo génère automatiquement une proposition de collaboration. Vous pouvez être notifié de ces matchings via webhooks.

Le matching prend en compte le type de bien, le budget, la surface, la localisation et d'autres critères pour proposer les correspondances les plus pertinentes.

Webhooks & Notifications

Configurez des webhooks pour recevoir des notifications en temps réel lorsque des événements importants se produisent sur MonHubImmo.

Événements disponibles

ÉvénementDescription
property.createdUn bien a été publié
property.updatedUn bien a été modifié
property.deletedUn bien a été supprimé
property.status_changedLe statut d'un bien a changé
search_ad.createdUne recherche acquéreur a été diffusée
search_ad.updatedUne recherche a été modifiée
search_ad.deletedUne recherche a été supprimée
search_ad.status_changedLe statut d'une recherche a changé
lead.createdUn lead a été créé par un apporteur d'affaires
lead.updatedUn lead a été modifié
lead.deletedUn lead a été supprimé
lead.status_changedLe statut d'un lead a changé

Enveloppe : { event, timestamp, data }. L'API externe elle-même n'émet que property.created, property.updated, search_ad.created et search_ad.updated — les autres proviennent du parcours applicatif. En particulier, un PUT /properties/:id qui change le statut émet property.updated, jamais property.status_changed : abonnez-vous aux deux si vous suivez les statuts.

Signature HMAC-SHA256

Chaque webhook inclut un header X-Webhook-Signature de la forme sha256=<hex>, calculé en HMAC-SHA256 sur le corps brut de la requête avec votre signing secret. Signez bien le corps brut : re-sérialiser le JSON déjà analysé produit d'autres octets, donc une autre signature. Comparez en temps constant.

Vérification de la signature (Node.js)
const crypto = require('crypto');

// Conserver le corps brut (Buffer), pas l'objet analysé
app.use('/webhooks/mhi', express.raw({ type: 'application/json' }));

app.post('/webhooks/mhi', (req, res) => {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', SIGNING_SECRET)
    .update(req.body)
    .digest('hex');

  const a = Buffer.from(expected);
  const b = Buffer.from(req.get('X-Webhook-Signature') || '');

  // timingSafeEqual exige des longueurs égales : les comparer d'abord
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.status(401).send('Signature invalide');
  }

  const { event, timestamp, data } = JSON.parse(req.body.toString('utf8'));
  res.status(200).end(); // répondre vite, traiter ensuite
});

Retry automatique

En cas d'échec de livraison (réponse non-2xx ou timeout), MonHubImmo retente automatiquement : 3 tentatives au maximum, avec des délais de 0 s, 10 s puis 60 s — l'ensemble se termine donc en ~70 s. Chaque tentative a un timeout de 10 s : répondez 2xx immédiatement et traitez l'événement en arrière-plan, sinon la livraison est comptée en échec. Le signing secret n'est affiché qu'une seule fois, à la création du webhook, et ne se renouvelle pas en place : pour le changer, supprimez le webhook et recréez-le.

Connexion SSO

Permettez à vos agents de se connecter à MonHubImmo directement depuis votre plateforme, sans ressaisir leurs identifiants.

JWT partenaire

Générez un JWT côté serveur avec votre secret partenaire et redirigez l'agent vers MonHubImmo. Le token est vérifié et l'agent est connecté automatiquement.

Génération du token (Node.js)
const jwt = require('jsonwebtoken');

// Les claims sont userId + partnerId, tous deux obligatoires.
// Ce sont des ObjectId MonHubImmo, pas des externalId.
const token = jwt.sign(
  {
    userId: '507f1f77bcf86cd799439011',   // l'agent
    partnerId: '507f1f77bcf86cd799439022' // votre réseau
  },
  PARTNER_JWT_SECRET,
  { algorithm: 'HS256', expiresIn: '5m' }
);

// Puis, côté serveur :
// POST https://api.monhubimmo.fr/api/auth/partner-login
// { "token": "<jwt>" }
// La réponse pose les cookies de session ; redirigez ensuite
// le navigateur vers https://app.monhubimmo.fr
Le token JWT a une durée de vie courte (5 minutes recommandé) et ne peut être utilisé qu'une seule fois : un rejeu répond 401 Token has already been used. Votre JWT secret est différent de votre clé API. Contrairement à la clé API, qui est hachée et n'est lisible qu'à sa création, le JWT secret reste lisible dans votre portail partenaire puisque vous devez signer avec lui.

Codes d'erreur

L'API utilise les codes HTTP standards pour indiquer le succès ou l'échec d'une requête.

CodeStatutDescription
200OKRequête réussie
201CreatedRessource créée avec succès
400Bad RequestParamètres invalides ou manquants
401UnauthorizedClé API manquante ou invalide
403ForbiddenAccès refusé à cette ressource
403Trial endedCode TRIAL_ENDED : essai gratuit de l'agent terminé sans abonnement, création ou mise en ligne d'une annonce refusée (modification et archivage restent acceptés)
404Not FoundRessource non trouvée
409ConflictEmail déjà utilisé, ou prix modifié sur un bien engagé dans une collaboration en cours
422UnprocessableErreur de validation des données
429Too Many RequestsLimite de requêtes dépassée (250/min)
500Server ErrorErreur interne du serveur
Exemple de réponse d'erreur (validation)
{
  "success": false,
  "error": "Validation error",
  "details": [
    { "field": "email", "message": "Email invalide" },
    {
      "field": "professionalInfo.personalPitch",
      "message": "La bio doit contenir au moins 250 caractères"
    }
  ]
}

Une erreur de validation n'a pas de champ message : lisez details[], qui nomme chaque champ fautif. Les autres erreurs (404, 409, géocodage, image) portent bien un message.

Cette page est un aperçu. La référence complète — les 19 endpoints avec leurs contraintes exactes, les 12 événements webhook, les pièges à l'origine des 422 et une recette de démarrage — tient dans un seul document Markdown, à déposer dans le dépôt de votre logiciel : télécharger PARTNER_API.md.

Prêt à intégrer votre réseau ?

Contactez notre équipe pour obtenir vos clés API et démarrer l'intégration de votre réseau.

Nous contacter