Documentation API Partenaire

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.

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

curl -X GET "https://api.monhubimmo.fr/api/external/v1/users" \
  -H "X-API-Key: votre-cle-api" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "users": [...],
    "total": 42,
    "page": 1,
    "limit": 20
  }
}

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

{
  "email": "agent@monreseau.fr",
  "firstName": "Marie",
  "lastName": "Dupont",
  "phone": "0612345678",
  "city": "Paris",
  "userType": "agent"
}

Lister les agents

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

{
  "success": true,
  "data": {
    "users": [
      {
        "externalId": "agent-123",
        "email": "agent@monreseau.fr",
        "firstName": "Marie",
        "lastName": "Dupont",
        "status": "active"
      }
    ],
    "total": 42,
    "page": 1
  }
}

Activer / Désactiver un agent

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

{
  "active": false
}

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.

{
  "userExternalId": "agent-123",
  "title": "Appartement T3 lumineux — Paris 11e",
  "propertyType": "apartment",
  "transactionType": "sale",
  "price": 450000,
  "surface": 65,
  "rooms": 3,
  "city": "Paris",
  "zipCode": "75011",
  "description": "Bel appartement traversant..."
}

Mettre à jour un bien

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

{
  "price": 440000,
  "status": "active"
}

Consulter et retirer

Consultez les détails d'un bien ou retirez-le de la plateforme.

// Réponse : détails complets du bien avec statistiques

// Le bien est retiré de la plateforme

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.

{
  "userExternalId": "agent-123",
  "title": "Recherche T3/T4 Paris 11e",
  "projectType": "primary",
  "propertyTypes": ["apartment"],
  "budget": { "min": 350000, "max": 500000 },
  "minSurface": 55,
  "location": {
    "cities": ["Paris"],
    "departments": ["75"]
  }
}

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.

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

Événements disponibles

Signature HMAC-SHA256

Chaque webhook inclut un header X-MonHubImmo-Signature contenant une signature HMAC-SHA256 du body, calculée avec votre signing secret. Vérifiez cette signature pour garantir l'authenticité des webhooks.

const crypto = require('crypto');

const signature = req.headers['x-monhubimmo-signature'];
const expected = crypto
  .createHmac('sha256', SIGNING_SECRET)
  .update(JSON.stringify(req.body))
  .digest('hex');

if (signature !== expected) {
  return res.status(401).send('Signature invalide');
}

Retry automatique

En cas d'échec de livraison (erreur HTTP 4xx/5xx ou timeout), MonHubImmo retente automatiquement l'envoi avec un backoff exponentiel (3 tentatives sur 24h).

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.

const jwt = require('jsonwebtoken');

const token = jwt.sign(
  { externalId: 'agent-123' },
  PARTNER_JWT_SECRET,
  { expiresIn: '5m' }
);

// Redirigez l'agent vers :
// https://monhubimmo.fr/auth/partner-login?token={token}

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

{
  "success": false,
  "error": "Validation failed",
  "details": [
    { "field": "email", "message": "Email invalide" },
    { "field": "firstName", "message": "Le prénom est requis" }
  ]
}