# API partenaire MonHubImmo — reference d'integration

Document autonome destine a l'equipe (ou a l'agent de code) qui integre MonHubImmo depuis
un logiciel tiers. Il decrit l'**API externe serveur a serveur** : creer des agents,
publier des biens et des recherches acquereurs, recevoir des webhooks, connecter un
utilisateur sans mot de passe.

Source de verite : `server/src/middleware/partnerValidation.ts` (schemas),
`server/src/controllers/externalApiController.ts` (reponses, codes, filtres) et
`server/src/models/Webhook.ts` (evenements). Les pages de documentation web sont des
copies ; en cas de divergence, **ce document et le code gagnent**.

---

## 1. Base et authentification

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

Chaque requete porte la cle API dans un header :

```
X-API-Key: <64 caracteres hexadecimaux>
```

- **Pas de HMAC sur les requetes sortantes** : la signature HMAC ne concerne que les
  webhooks que MonHubImmo vous envoie (§ 6).
- **Pas de scopes, pas d'OAuth.** Les seules dimensions d'autorisation sont :
  - `apiEnabled` sur votre reseau — sinon **403** `API access disabled` ;
  - `isActive` sur votre reseau — un reseau desactive fait echouer le lookup, donc **401** ;
  - le **triplet de propriete** `partnerNetworkId` + `createdViaApi` : vous ne voyez et ne
    modifiez que les agents que vous avez crees via l'API, et les biens / recherches de ces
    agents crees via l'API. En **lecture**, hors perimetre = **404 `Not found`** ; en
    **ecriture**, hors perimetre = **403 `Forbidden`** avec un message qui nomme la
    condition manquante.

### Obtenir et conserver la cle

La cle est **hachee en base (bcrypt)**. Elle n'est donc lisible **qu'une seule fois**, au
retour de sa creation :

- portail partenaire `/partner/api` -> « Generer / Regenerer la cle API » ;
- ou un administrateur MonHubImmo depuis `/admin/partners/<id>`.

Ensuite, seul le prefixe de 8 caracteres reste consultable (`GET /api/partner/api-key`
renvoie `enabled`, `hasKey`, `prefix`, `createdAt` — **jamais** la cle). Cle perdue = cle a
regenerer, ce qui invalide immediatement l'ancienne.

Cote serveur, l'authentification cherche le reseau par le prefixe puis compare la cle
complete en bcrypt. Les trois refus se distinguent par leur `message` :

| Situation | Reponse |
|---|---|
| header absent | **401** `API key required` / `Missing X-API-Key header` |
| prefixe inconnu, ou reseau `isActive: false` | **401** `Invalid API key` / `API key not recognized` |
| prefixe connu, cle fausse | **401** `Invalid API key` / `API key verification failed` |
| reseau `apiEnabled: false` | **403** `API access disabled` |

### Rate limit

**250 requetes par minute et par IP**, applique globalement sur `/api` — ce n'est **pas**
un quota par cle. Au-dela : **429** avec
`{ "success": false, "message": "Trop de requêtes. Veuillez ralentir." }`.
Les headers standard `RateLimit-*` sont renvoyes.

### Verifier la cle

```bash
curl -s https://api.monhubimmo.fr/api/external/v1/health \
  -H "X-API-Key: $MHI_API_KEY"
```

```json
{
  "success": true,
  "partner": { "id": "...", "name": "Mon Reseau", "apiEnabled": true }
}
```

`GET /health` est la sonde de validite de cle : 200 = cle bonne et API ouverte ; 401 = cle
invalide ; 403 = API desactivee sur le reseau. Elle n'echo que le reseau authentifie — pas
de `version`, pas de `timestamp`, pas de verification de base de donnees.

---

## 2. Conventions

### Enveloppe de reponse — il n'y a pas de cle `data`

La ressource est renvoyee **sous son propre nom**, a la racine :

```json
{ "success": true, "users": [ ... ], "pagination": { "page": 1, "limit": 20, "total": 42, "totalPages": 3 } }
{ "success": true, "user": { ... } }
{ "success": true, "property": { ... } }
{ "success": true, "searchAd": { ... } }
```

Les cles possibles sont `user`, `users`, `property`, `properties`, `searchAd`, `searchAds`,
`partner`. Un client qui lit `response.data.users` lira `undefined`.

Enveloppe d'erreur :

```json
{ "success": false, "error": "Not found", "message": "Property not found" }
```

**Les erreurs de validation Zod n'ont pas de champ `message`** — uniquement `details[]` :

```json
{ "success": false, "error": "Validation error",
  "details": [ { "field": "professionalInfo.personalPitch",
                 "message": "La bio doit contenir au moins 250 caractères" } ] }
```

Lisez donc toujours `details[]` en priorite sur un 422, et ne supposez pas `message`
present. Les autres 422 (plan, geocodage, image) portent **a la fois** `message` et,
le plus souvent, `details[]`.

### Identifiants de chemin = ObjectId MongoDB

Tous les `:id` d'URL sont des **ObjectId MongoDB de 24 caracteres hexadecimaux**, ceux
renvoyes dans le champ `id` a la creation. Votre `externalId` **ne fonctionne jamais**
comme identifiant de chemin : chaque `:id` est verifie par `ObjectId.isValid()` avant toute
recherche et repond **400** sinon (`Invalid user ID` / `Invalid property ID` /
`Invalid search ad ID`). Idem pour le champ `userId` du corps a la creation (**422**,
`details: [{ field: "userId", message: "Invalid userId format" }]`) et pour le parametre de
requete `userId` (**400** `Invalid userId`).

`externalId` sert **uniquement de filtre de requete**, en egalite exacte, et sur **trois
endpoints seulement** :

- `GET /users?externalId=...`
- `GET /properties/mine?externalId=...`
- `GET /search-ads/mine?externalId=...`

Il n'est **pas** accepte sur les catalogues publics `GET /properties` et `GET /search-ads`.

Le schema de correspondance est donc : `GET /properties/mine?externalId=X` ->
`properties[0].id` -> utilisez cet ObjectId dans `PUT /properties/:id`. Le plus simple
reste de stocker la correspondance `votre reference <-> ObjectId MonHubImmo` des la
creation.

### Aucun DELETE

L'API externe n'expose **aucune methode DELETE**. Pour retirer un bien ou une recherche,
passez son `status` a `archived` via `PUT`/`PATCH`.

### Pagination

`page` (defaut 1) et `limit` (defaut 20, **plafonne a 100**, minimum 1). Les valeurs non
numeriques ou hors bornes sont ramenees silencieusement dans l'intervalle. L'enveloppe est
toujours `pagination: { page, limit, total, totalPages }`.

### Methodes

`PUT` et `PATCH` sont **strictement equivalents** sur cette API : les deux appliquent une
mise a jour partielle (seuls les champs fournis sont ecrits). Un corps vide repond **400
`No data provided`**.

### Bornes de montants

`price` d'un bien et `budget.max` / `budget.ideal` d'une recherche : **1 000 € a
50 000 000 €**. Les montants de cette API sont en euros par contrat — il n'y a pas de champ
devise.

---

## 3. Agents (`/users`)

Un agent cree par l'API a toujours `userType: "agent"` (l'API ne peut creer que des
agents), `isEmailVerified: true` et `profileCompleted: true`.

### `POST /users` — creer un agent

**201** a la creation. `professionalInfo` est **requis** et complet.

| Champ | Type | Contrainte |
|---|---|---|
| `email` | string | email valide, **unique** (409 sinon) ; normalise en minuscules |
| `firstName` | string | 1-50 |
| `lastName` | string | 1-50 |
| `phone` | string | requis ; les espaces sont retires et `+33` devient `0` |
| `externalId` | string | optionnel, max 255 — votre reference |
| `plan` | enum | optionnel : `decouverte` \| `essentiel` \| `premium` (`integral` encore accepte, voir plus bas) |
| `professionalInfo.city` | string | **requis**, 1-100 |
| `professionalInfo.postalCode` | string | **requis**, exactement 5 chiffres |
| `professionalInfo.interventionRadius` | number | **requis**, entier 1-350 (km) |
| `professionalInfo.coveredCities` | array | **requis**, **>= 1** element `{ city, postalCode }` |
| `professionalInfo.yearsExperience` | number | **requis**, entier 0-50 |
| `professionalInfo.personalPitch` | string | **requis**, **250 a 1500 caracteres** |
| `professionalInfo.agentType` | enum | `independent` \| `commercial` \| `employee` |
| `professionalInfo.siretNumber` | string | 14 chiffres exactement |
| `professionalInfo.mandateTypes` | array | `simple` \| `exclusif` \| `co-mandat` |
| `professionalInfo.tCard`, `.network` | string | libres ; `network` prend par defaut le reseau par defaut du partenaire |
| `professionalInfo.collaborateWithAgents`, `.shareCommission` | boolean | |

`userType` **n'existe pas** dans ce schema : l'envoyer n'a aucun effet.

```bash
curl -X POST https://api.monhubimmo.fr/api/external/v1/users \
  -H "X-API-Key: $MHI_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "email": "jean.dupont@exemple.fr",
    "firstName": "Jean", "lastName": "Dupont", "phone": "0612345678",
    "externalId": "crm-4821",
    "professionalInfo": {
      "city": "Lyon", "postalCode": "69001",
      "interventionRadius": 30,
      "coveredCities": [ { "city": "Lyon", "postalCode": "69001" } ],
      "yearsExperience": 8,
      "personalPitch": "<250 caracteres minimum>"
    }
  }'
```

```json
{ "success": true,
  "user": { "id": "507f...", "email": "jean.dupont@exemple.fr",
            "firstName": "Jean", "lastName": "Dupont",
            "isValidated": true, "inviteSent": true } }
```

- `isValidated` suit le reglage `autoValidateUsers` de votre reseau.
- `inviteSent` indique si l'e-mail d'invitation est bien parti. **Un echec d'envoi ne fait
  pas echouer la creation** : vous recevez 201 avec `inviteSent: false`, et l'agent existe.
  Le lien de definition de mot de passe est valable **7 jours**.
- Le plan accorde (sans Stripe) suit le reglage du reseau : `essentiel`, `premium` et
  `integral` posent un acces paye offert, `decouverte` n'accorde rien. Correspondance
  avec les formules de la grille 2026 :

  | Valeur de `plan` | Formule | Litteral `subscriptionPlan` |
  |---|---|---|
  | `decouverte` | Decouverte | aucun (pas d'acces paye) |
  | `essentiel` | **Standard** | `pro_standard_monthly` |
  | `premium` | Premium | `pro_premium_monthly` |
  | `integral` | Integral (plus vendu) | `pro_hestia_monthly` |

  La cle `essentiel` est historique : elle designe le **premier palier paye**, c'est-a-dire
  **Standard** dans la grille 2026 — et non l'ancienne formule Essentiel. Elle n'est pas
  renommee pour ne pas casser les integrations existantes.

  `integral` n'est plus commercialise : il reste accepte pour les reseaux deja configures
  ainsi, mais n'est plus propose a la configuration d'un nouveau reseau. L'ordre du plafond
  suit la grille : `decouverte` < `essentiel` < `integral` < `premium`.

Ces reglages (validation automatique, acces accorde, plan accorde) sont fixes par un
administrateur MonHubImmo, pas par l'API.

Erreurs : **422** `Validation error` (`details[]`), **409** `Conflict`
(`A user with this email already exists`), **422** `Validation error` sur le plafond de
plan, **422** `Geocoding error`, **500**.

### `GET /users` — lister vos agents

Filtres : `email` (recherche partielle, insensible a la casse), `externalId` (egalite
exacte), `page`, `limit`. Tri fixe par date de creation decroissante — il n'y a pas de
parametre de tri ici. Portee : vos agents crees via l'API uniquement.

```json
{ "success": true,
  "users": [ { "id": "...", "email": "...", "firstName": "...", "lastName": "...",
               "externalId": "crm-4821", "isValidated": true,
               "profileCompleted": true, "createdAt": "..." } ],
  "pagination": { "page": 1, "limit": 20, "total": 42, "totalPages": 3 } }
```

Il n'y a **pas** de champ `status` sur un agent : l'etat se lit dans `isValidated` et
`profileCompleted`.

### `GET /users/:id` — detail d'un agent

Renvoie `{ success, user }` avec `phone` et le bloc `professionalInfo` complet, dont
`coveredCities` sous la forme `[{ city, postalCode }]`. **400** si l'id n'est pas un
ObjectId, **404** `User not found or not accessible` hors de votre perimetre.

### `PUT|PATCH /users/:id` — modifier un agent

Tous les champs sont optionnels, memes contraintes qu'a la creation (dont le pitch
250-1500). `email` n'est **pas** modifiable. Modifier `city`/`postalCode` ou
`coveredCities` **declenche un nouveau geocodage**, qui peut faire echouer l'appel (422
`Geocoding error`). Corps vide -> **400** `No data provided`.

La reponse ne contient **pas** `createdAt` :

```json
{ "success": true,
  "user": { "id": "...", "email": "...", "firstName": "...", "lastName": "...",
            "externalId": "...", "isValidated": true, "profileCompleted": true } }
```

### `POST /users/:id/activate` et `POST /users/:id/deactivate`

Corps **vide**. Bascule la validation du compte.

```json
{ "success": true,
  "user": { "id": "...", "email": "...", "firstName": "...", "lastName": "...",
            "externalId": "...", "isValidated": true },
  "message": "User activated successfully" }
```

**400** `No change needed` si le compte est deja dans l'etat demande.

Il n'existe **pas** de `PATCH /users/:id/status`.

> Aucun evenement webhook n'existe pour les agents : ces trois ecritures n'emettent rien.

---

## 4. Biens (`/properties`)

### `POST /properties` — publier un bien

**201**. Le bien est cree en **`status: "draft"`** : il n'est pas visible tant que vous ne
l'avez pas passe en `active` par un `PUT`. Le schema de creation n'accepte pas de champ
`status` — la publication est forcement un second appel.

| Champ | Type | Contrainte |
|---|---|---|
| `userId` | string | **requis** — ObjectId d'un **de vos** agents, qui doit etre **valide** (non bloque, non supprime) |
| `title` | string | **requis**, 10-200 |
| `description` | string | **requis**, **50**-2000 |
| `price` | number | **requis**, **entier**, 1 000 a 50 000 000 € |
| `surface` | number | **requis**, 1-10 000 m2 |
| `propertyType` | enum | **requis** : `Appartement` \| `Maison` \| `Terrain` \| `Local commercial` \| `Bureaux` |
| `city` | string | **requis**, 1-100 |
| `postalCode` | string | **requis**, 5 chiffres |
| `sector` | string | **requis**, 1-100 — quartier / secteur, souvent oublie |
| `transactionType` | enum | `Vente` (defaut) \| `Location` |
| `externalId` | string | optionnel, max 255 |
| `address` | string | max 200 |
| `mandateNumber` | string | max 50 |
| `rooms` / `bedrooms` / `bathrooms` / `showerRooms` | number | entiers 1-50 / 0-20 / 0-10 / 0-10 |
| `floor` / `totalFloors` / `levels` | number | entiers -5..100 / 1..200 / 1..20 |
| `yearBuilt` | number | entier 1800 .. annee courante + 5 |
| `hasParking`, `hasGarden`, `hasElevator`, `hasBalcony`, `hasTerrace`, `hasGarage` | boolean | defaut `false` |
| `energyRating`, `gasEmissionClass` | enum | `A`..`G` \| `Non soumis au DPE` |
| `condition` | enum | `new` \| `good` \| `refresh` \| `renovate` |
| `orientation` | enum | `Nord` \| `Sud` \| `Est` \| `Ouest` \| `Nord-Est` \| `Nord-Ouest` \| `Sud-Est` \| `Sud-Ouest` |
| `exterior` | array | `garden` \| `balcony` \| `terrace` \| `courtyard` \| `none` |
| `heatingType` | string | max 100 |
| `annualCondoFees` | number | 0-100 000 |
| `agencyFeesAmount`, `priceIncludingFees` | number | >= 0 |
| `landArea` | number | 1-1 000 000 m2 |
| `parkingSpaces` | number | entier 0-50 |
| `availableFromDate` | string | **format `MM/AAAA`** exactement |
| `mainImage` | `{ url }` | URL publique |
| `galleryImages` | array de `{ url }` | **max 10** |

**Attention aux enums** : les biens utilisent un vocabulaire **francais capitalise**
(`Appartement`, `Vente`), alors que les recherches acquereurs utilisent un vocabulaire
**anglais minuscule** (`apartment`, `house`). Les deux ne sont pas interchangeables (§ 5).

Reponse :

```json
{ "success": true,
  "property": { "id": "...", "externalId": "...", "title": "...", "status": "draft",
                "owner": { "id": "...", "firstName": "...", "lastName": "...",
                           "userType": "agent", "network": "...", "externalId": "..." },
                "createdAt": "..." } }
```

**Le geocodage d'un bien n'est pas bloquant** : si l'adresse et la ville ne se resolvent
pas, le bien est cree quand meme (201) simplement sans coordonnees. C'est l'inverse du
comportement sur un agent.

Erreurs : **422** `Validation error`, **404** `Not found`
(`User not found, not accessible, or not validated`), **403** `Trial ended` (code
`TRIAL_ENDED`, voir § 9 piege 22), **422** `Image upload error`, **500**.

### `GET /properties` — catalogue public

Lecture du catalogue MonHubImmo, **pas seulement vos biens** : filtre a `status: "active"`,
aux proprietaires valides (non bloques, non supprimes, valides) et aux biens visibles sur
la place de marche.

Filtres : `city` (partiel), `postalCode` (liste separee par des virgules),
`propertyType`, `transactionType`, `minPrice`, `maxPrice`, `minSurface`, `maxSurface`,
`rooms` (**minimum**, pas egalite), `userId` (ObjectId), `search` (recherche plein texte),
`sortBy` parmi `createdAt` \| `price` \| `surface` (defaut `createdAt`),
`sortOrder` `asc` \| `desc` (defaut `desc`), `page`, `limit`.

Renvoie `{ success, properties, pagination }`. Cette liste ne contient **ni `externalId` ni
`galleryImages`** — utilisez `/properties/mine` ou `/properties/:id` pour ces champs.

### `GET /properties/mine` — vos biens

Vos biens crees via l'API, **tous statuts confondus** (brouillons et archives compris).
Filtres : `status`, `userId` (**403 `Forbidden`** si l'agent n'est pas du reseau),
`externalId`, `sortBy` parmi `createdAt` \| `updatedAt` \| `price` \| `surface`,
`sortOrder`, `page`, `limit`. Renvoie `externalId`, `galleryImages` (avec leurs cles) et
`updatedAt`.

> Route declaree **avant** `/properties/:id` : `mine` n'est jamais pris pour un id.

### `GET /properties/:id`

Detail d'un bien. La reponse depend de la propriete :

- **un bien a vous** (cree via l'API, agent de votre reseau) : tous statuts accessibles,
  `externalId` present, `galleryImages` sous la forme `[{ url, key }]` ;
- **un bien du catalogue** : accessible seulement si `status: "active"` et proprietaire
  valide ; `externalId` **absent**, et `galleryImages` est un **tableau de chaines** (URLs
  CDN), pas d'objets.

Tout ce qui ne vous appartient pas et n'est pas publiquement visible repond **404
`Not found`** (jamais 403, en lecture). Cet appel n'incremente pas le compteur de vues.

### `PUT|PATCH /properties/:id` — modifier un bien

Tous les champs ci-dessus en optionnel, **plus** :

| Champ | Contrainte |
|---|---|
| `status` | `draft` \| `active` \| `archived` **uniquement** |
| `mainImage` | `{ url }` — remplace l'image principale |
| `removeMainImage` | boolean — **prioritaire** sur `mainImage` si les deux sont envoyes |
| `addGalleryImages` | array de `{ url }`, max 10 **par appel**, et max 10 au total |
| `removeGalleryImages` | array de cles d'images a retirer |

Les retraits sont appliques **avant** les ajouts, et le plafond de 10 est verifie sur la
galerie resultante : depasser repond **422** `Validation error` avec
`Cannot add N images. Current: C, Maximum: 10`.

`sold` et `rented` ne sont **pas** ecrivables par le partenaire : ces statuts sont poses
par le parcours applicatif MonHubImmo.

**403 `Trial ended`** (code `TRIAL_ENDED`) si vous passez en `active` un bien en
`draft` ou `archived` alors que l'essai gratuit de l'agent est termine sans abonnement
(§ 9 piege 22). Les autres modifications et l'archivage restent acceptes.

**403 `Forbidden`** (et non 404) si le bien existe mais sort de votre perimetre — le
`message` nomme la condition manquante (`owner network mismatch`,
`owner not created via API`, `property not created via API`).

**409 `Conflict`** si vous modifiez `price` **ou** `agencyFeesAmount` alors que le bien est
engage dans au moins une collaboration de statut `pending`, `negotiating`, `accepted` ou
`active` :

```json
{ "success": false, "error": "Conflict",
  "message": "Impossible de modifier le prix : 2 collaboration(s) en cours." }
```

Le prix engage les collaborateurs : il faut attendre la fin ou l'annulation des
collaborations. Renvoyer la valeur **identique** a l'actuelle n'est pas considere comme une
modification et ne declenche pas le 409.

Le re-geocodage declenche par un changement de `city`, `postalCode` ou `address` est
**silencieux** : un echec laisse simplement les coordonnees inchangees, sans erreur.

---

## 5. Recherches acquereurs (`/search-ads`)

### `POST /search-ads` — publier une recherche

**201**. La recherche est creee en **`status: "active"`** — immediatement visible,
contrairement aux biens.

| Champ | Type | Contrainte |
|---|---|---|
| `userId` | string | **requis** — ObjectId d'un de vos agents (la validation du compte n'est **pas** exigee ici, contrairement aux biens) |
| `title` | string | **requis**, 10-200 |
| `description` | string | **requis**, **10**-2000 (et non 50 comme pour un bien) |
| `propertyTypes` | array | **requis**, **>= 1** : `house` \| `apartment` \| `land` \| `building` \| `commercial` |
| `location.cities` | array | **requis**, **>= 1** nom de ville (1-100) |
| `location.postalCodes` | array | optionnel, 5 chiffres chacun |
| `location.maxDistance` | number | 1-500 km |
| `location.openToOtherAreas` | boolean | |
| `externalId` | string | max 255 |
| `budget.max` | number | 1 000 a 50 000 000 € |
| `budget.ideal` | number | memes bornes |
| `budget.financingType` | enum | `loan` \| `cash` \| `pending` |
| `budget.isSaleInProgress`, `budget.hasBankApproval` | boolean | |
| `propertyState` | array | `new` \| `old` |
| `projectType` | enum | `primary` \| `secondary` \| `investment` |
| `minRooms` / `minBedrooms` / `minSurface` | number | 1-50 / 0-20 / 1-10 000 |
| `hasExterior`, `hasParking` | boolean | |
| `acceptedFloors` | string | max 200 |
| `desiredState` | array | `new` \| `good` \| `refresh` \| `renovate` |
| `priorities.mustHaves` / `.niceToHaves` / `.dealBreakers` | array | max 10 chaines de 200 |

**`budget` n'a pas de `min`.** Les seules cles acceptees sont `max`, `ideal`,
`financingType`, `isSaleInProgress`, `hasBankApproval`. De meme,
`location.departments` n'existe pas : utilisez `cities`, `postalCodes`, `maxDistance`.

**Vocabulaire anglais minuscule** pour `propertyTypes` — `Appartement` est rejete ici,
`apartment` est rejete sur un bien.

```json
{ "success": true,
  "searchAd": { "id": "...", "externalId": "...", "title": "...", "status": "active",
                "author": { "id": "...", "firstName": "...", "lastName": "...",
                            "userType": "agent", "externalId": "..." },
                "createdAt": "..." } }
```

### `GET /search-ads` — catalogue public

Filtre a `status: "active"` et aux auteurs valides. Filtres : `city` (liste virgulee),
`postalCode` (liste virgulee), `propertyType`, `minBudget`, `maxBudget` (appliques sur
`budget.max`), `authorType`, `search` (titre, description, villes), `sortBy` parmi
`createdAt` \| `budget.max`, `sortOrder`, `page`, `limit`. Renvoie
`{ success, searchAds, pagination }`, sans `externalId` ni `updatedAt`.

Il n'y a **pas** de filtre `userId` sur ce catalogue (contrairement aux biens).

### `GET /search-ads/mine`

Vos recherches creees via l'API, tous statuts (y compris `paused` et `archived`). Filtres :
`status`, `userId`, `externalId`, `sortBy` parmi `createdAt` \| `updatedAt` \|
`budget.max`, `sortOrder`, `page`, `limit`.

### `GET /search-ads/:id`

Detail, avec `acceptedFloors`. `externalId` n'est present que si la recherche est la votre.
**404 `Not found`** hors de votre perimetre.

### `PUT|PATCH /search-ads/:id`

Tous les champs en optionnel, **plus** `status` parmi `active` \| `paused` \| `archived`
**uniquement** — `fulfilled` n'est pas ecrivable par le partenaire. Les memes quatre
refus **403 `Forbidden`** que pour un bien s'appliquent. Pas de verrou de prix ici.
Comme pour un bien, `POST /search-ads` et le passage en `active` d'une recherche
`paused` ou `archived` repondent **403 `Trial ended`** (code `TRIAL_ENDED`) pour un
agent dont l'essai est termine sans abonnement.

---

## 6. Webhooks

Configures depuis le portail partenaire (`/partner/api`, bloc « Webhooks ») : URL HTTPS,
evenements souscrits, et l'option **« exclure mes propres evenements API »** qui evite de
recevoir l'echo de vos propres ecritures.

### Les 12 evenements

| Evenement | Declencheur |
|---|---|
| `property.created` | bien cree |
| `property.updated` | bien modifie |
| `property.deleted` | bien supprime |
| `property.status_changed` | statut d'un bien change |
| `search_ad.created` | recherche creee |
| `search_ad.updated` | recherche modifiee |
| `search_ad.deleted` | recherche supprimee |
| `search_ad.status_changed` | statut d'une recherche change |
| `lead.created` | lead cree par un apporteur d'affaires |
| `lead.updated` | lead modifie |
| `lead.deleted` | lead supprime |
| `lead.status_changed` | statut d'un lead change |

> **Important** : l'API externe n'emet que **4** de ces evenements —
> `property.created`, `property.updated`, `search_ad.created`, `search_ad.updated`. Les
> autres proviennent du parcours applicatif MonHubImmo (interface web, apporteurs
> d'affaires). En particulier, **un `PUT /properties/:id` qui change le `status` emet
> `property.updated`, jamais `property.status_changed`** : si vous suivez les changements
> de statut, abonnez-vous aux deux.

### Enveloppe

```json
{ "event": "property.created", "timestamp": "2026-11-10T12:00:00.000Z", "data": { } }
```

Champs de `data`, tels qu'ils sont **reellement** emis :

- **`property.*`** : `id`, `title`, `status`, `propertyType`, `transactionType`, `city`,
  `postalCode`, `price`, `surface`, `externalId` (ou `null`), `createdViaApi`, `createdAt`,
  `updatedAt` — plus `previousStatus` sur `property.status_changed`.
- **`search_ad.*`** : `id`, `title`, `status`, `propertyTypes`, `authorType`, `location`,
  `budget`, `externalId`, `createdViaApi`, `createdAt`, `updatedAt` — plus
  `previousStatus` sur `search_ad.status_changed`.
- **`lead.*`** : `id`, `title`, `leadType`, `status`, `propertyTypes`, `location`,
  `budgetMax`, `estimatedSurface`, `estimatedPrice`, `createdAt`, `updatedAt` — plus
  `previousStatus` sur `lead.status_changed`.

Il n'y a **ni `rooms` ni objet `owner{}`** dans un payload de webhook : pour ces details,
appelez `GET /properties/:id` avec l'`id` recu.

### Headers

| Header | Valeur |
|---|---|
| `Content-Type` | `application/json` |
| `X-Webhook-Signature` | `sha256=<hex>` |
| `X-Webhook-Event` | nom de l'evenement |
| `User-Agent` | `MonHubImmo-Webhooks/1.0` |

### Verifier la signature

La signature est un **HMAC-SHA256 du corps brut** de la requete, avec votre
`signingSecret`, prefixe de `sha256=`. Signez le **corps brut** : re-serialiser le JSON
parse donne d'autres octets, donc une autre signature.

```js
const crypto = require('crypto');

// Express : conserver le corps brut
app.use('/webhooks/mhi', express.raw({ type: 'application/json' }));

app.post('/webhooks/mhi', (req, res) => {
	const expected = 'sha256=' + crypto
		.createHmac('sha256', process.env.MHI_WEBHOOK_SECRET)
		.update(req.body)              // Buffer brut, pas JSON.stringify(req.body)
		.digest('hex');

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

	// Comparaison a temps constant. timingSafeEqual jette si les longueurs
	// different : on les compare d'abord.
	if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
		return res.status(401).end();
	}

	const { event, timestamp, data } = JSON.parse(req.body.toString('utf8'));
	// Repondre 2xx rapidement, traiter en arriere-plan
	res.status(200).end();
});
```

### Livraison et retries

- **Timeout 10 s** par tentative.
- **3 tentatives maximum**, delais **0 s / 10 s / 60 s** (immediat, puis 10 s, puis 60 s) —
  l'ensemble se termine donc en ~70 s, et non sur 24 h.
- Toute reponse 2xx vaut succes ; tout le reste declenche la tentative suivante.
- Chaque tentative est journalisee (consultable dans le portail partenaire).
- Repondez **2xx immediatement** et traitez en file : un traitement de plus de 10 s compte
  comme un echec.
- L'emission est asynchrone cote MonHubImmo : un webhook en echec n'affecte jamais le code
  de reponse de l'appel API qui l'a declenche.

### Secret de signature

Genere **a la creation du webhook** et affiche **une seule fois**. Il n'est pas rotatable
en place : pour le changer, supprimez le webhook et recreez-le (nouveau secret).

---

## 7. Connexion sans mot de passe (SSO)

Permet d'ouvrir une session MonHubImmo pour un de vos agents depuis votre logiciel.

1. Signez un JWT **HS256** avec le `jwtSecret` de votre reseau (lisible dans
   `/partner/api` — contrairement a la cle API, il **reste en clair**, puisque vous devez
   signer avec lui) :

   ```js
   const jwt = require('jsonwebtoken');
   const token = jwt.sign(
   	{ userId: '<ObjectId MonHubImmo de l_agent>', partnerId: '<ObjectId de votre reseau>' },
   	process.env.MHI_JWT_SECRET,
   	{ algorithm: 'HS256', expiresIn: '5m' },
   );
   ```

   Les claims sont **`userId` et `partnerId`**, tous deux obligatoires. Un claim
   `externalId` serait ignore et le token rejete.

2. Postez-le :

   ```
   POST https://api.monhubimmo.fr/api/auth/partner-login
   { "token": "<jwt>" }
   ```

3. La reponse pose les cookies de session et renvoie `{ success, message, user }`.
   Redirigez ensuite le navigateur vers `https://app.monhubimmo.fr`.

**Usage unique** : le token est mis sur liste noire des sa premiere utilisation (TTL =
`exp`, au minimum 60 s). Un rejeu repond **401 `Token has already been used`**. Generez un
token par connexion, avec une duree de vie courte.

Erreurs : **400** `Token is required` ; **401** `Invalid or expired login token` (signature,
expiration, reseau inactif, agent inconnu, ou agent n'appartenant pas a votre reseau) ;
**403** avec `code` `ACCOUNT_UNVALIDATED` \| `ACCOUNT_BLOCKED` \| `ACCOUNT_DELETED`.

---

## 8. Codes d'erreur

| Code | `error` | Quand |
|---|---|---|
| **400** | `Invalid user ID` / `Invalid property ID` / `Invalid search ad ID` | `:id` n'est pas un ObjectId |
| **400** | `No data provided` | corps de mise a jour vide |
| **400** | `No change needed` | activate/deactivate sur un compte deja dans cet etat |
| **400** | `Invalid userId` | filtre de requete `userId` mal forme |
| **401** | `API key required` | header `X-API-Key` absent |
| **401** | `Invalid API key` | prefixe inconnu (`API key not recognized`) ou mauvaise cle (`API key verification failed`) |
| **403** | `API access disabled` | `apiEnabled: false` sur le reseau |
| **403** | `Forbidden` | **ecriture** hors perimetre, ou filtre `userId` sur un agent hors reseau |
| **403** | `Trial ended` (code `TRIAL_ENDED`) | creation ou mise en ligne d'une annonce pour un agent dont l'essai gratuit est termine sans abonnement |
| **404** | `Not found` | **lecture** : ressource inexistante ou hors de votre perimetre |
| **409** | `Conflict` | e-mail deja utilise ; ou prix modifie sous collaboration active |
| **422** | `Validation error` | schema invalide (**`details[]` seul, sans `message`**) ; aussi le plafond de plan et le depassement de galerie (avec `message`) |
| **422** | `Geocoding error` | ville ou commune couverte introuvable (**agents uniquement**) |
| **422** | `Image upload error` | image non telechargeable, non-image, ou > 10 Mo |
| **429** | — | 250 req/min/IP depasse |
| **500** | `Internal server error` | erreur serveur |

---

## 9. Pieges — a lire avant le premier appel

Chaque point ci-dessous correspond a une erreur observee en integration.

1. **`personalPitch` : 250 a 1500 caracteres.** C'est l'erreur la plus frequente. Un pitch
   de 100 caracteres fait echouer toute la creation d'agent en 422. Comptez les caracteres.

2. **`professionalInfo` est requis en entier a la creation**, avec `coveredCities` d'au
   moins un element.

3. **Sur un agent, tout echec de geocodage fait echouer l'appel entier** (422
   `Geocoding error`) — y compris l'echec d'**une seule** commune couverte. Les echecs sont
   tous collectes puis renvoyes ensemble ; rien n'est cree ni modifie. Un couple ville /
   code postal incoherent (`Lyon` / `75001`) suffit. **Sur un bien, c'est l'inverse** : le
   geocodage est silencieux, le bien est cree sans coordonnees. Ne supposez pas un
   comportement unique.

4. **Il n'y a pas de cle `data`.** Lisez `response.users`, `response.property`, etc.

5. **Un 422 de validation n'a pas de champ `message`** — seulement `details[]`. Un client
   qui n'affiche que `message` montrera « undefined » sur l'erreur la plus courante.

6. **Les `:id` sont des ObjectId MongoDB, pas vos `externalId`.** Stockez la
   correspondance a la creation. `externalId` ne sert que de filtre, et seulement sur
   `/users`, `/properties/mine` et `/search-ads/mine`.

7. **Aucun DELETE.** Archivez (`status: "archived"`).

8. **Vocabulaires divergents.** Biens : `Appartement|Maison|Terrain|Local commercial|Bureaux`
   et `Vente|Location` (francais, capitalise). Recherches :
   `house|apartment|land|building|commercial` (anglais, minuscule). Ne partagez pas une
   table de correspondance unique entre les deux.

9. **Statuts a la creation differents** : un bien nait en `draft` (invisible — il faut un
   second appel pour le passer en `active`), une recherche nait en `active`.

10. **Statuts ecrivables limites** : biens `draft|active|archived`, recherches
    `active|paused|archived`. Ni `sold`, ni `rented`, ni `fulfilled`.

11. **409 sur le prix sous collaboration.** Modifier `price` ou `agencyFeesAmount` pendant
    une collaboration `pending|negotiating|accepted|active` est refuse. Prevoyez ce cas
    dans votre synchronisation : il n'est pas transitoire.

12. **Plafond de plan.** Demander un `plan` superieur au plan accorde a votre reseau repond
    **422** avec le message qui nomme le plafond — il n'y a **pas** de rabattement
    silencieux. Et si le reseau n'a pas l'« acces accorde », le plafond est `decouverte`
    quel que soit le plan configure.

13. **Images : URLs publiques, telechargees cote serveur.** MonHubImmo fait un `GET` sur
    chaque URL : elle doit etre accessible sans authentification, repondre un
    `Content-Type: image/*`, et peser **10 Mo au maximum**. Maximum **10 images de
    galerie**. L'echec d'une seule image **annule tout l'appel** (422 `Image upload
    error`), les images deja montees etant nettoyees. L'index dans le `message` est
    1-base, celui dans `details[].field` est 0-base.

14. **`budget` n'a pas de `min`** (`max`, `ideal`, `financingType`,
    `isSaleInProgress`, `hasBankApproval`), et `location.departments` n'existe pas.

15. **`sector` est requis sur un bien** et manque dans la plupart des exemples recopies.

16. **`availableFromDate` est au format `MM/AAAA`**, pas une date ISO.

17. **`description` : 50 caracteres minimum sur un bien, 10 sur une recherche.** Les deux
    seuils ne sont pas les memes.

18. **Un bien exige un agent valide, une recherche non.** `POST /properties` refuse en 404
    si l'agent n'est pas `isValidated` ; `POST /search-ads` l'accepte. Si votre reseau n'a
    pas la validation automatique, publiez d'abord via `/search-ads` ou activez l'agent.

19. **`property.status_changed` n'est pas emis par l'API externe** : vos changements de
    statut arrivent en `property.updated`.

20. **Rate limit par IP, pas par cle** : 250 req/min partagees avec tout ce qui sort de
    votre IP. Sequencez les imports en masse.

21. **La cle API n'est lisible qu'a sa creation.** Stockez-la a ce moment-la dans votre
    gestionnaire de secrets.

22. **Essai gratuit termine = mode limite.** Un agent inscrit apres la date d'activation
    de l'essai (14 jours, droits Standard) qui n'a ni abonnement ni plan accorde par
    votre reseau passe en mode limite a la fin de l'essai : `POST /properties`,
    `POST /search-ads` et la mise en ligne (`status: "active"`) d'un brouillon, d'une
    archive ou d'une recherche en pause repondent **403** avec `code: "TRIAL_ENDED"`.
    Ses annonces deja en ligne restent visibles et se modifient et s'archivent
    normalement : une synchronisation peut toujours retirer un bien vendu. Un agent
    a qui votre reseau accorde un plan (`essentiel`, `premium`, `integral`) n'est
    jamais concerne. Ce refus n'est pas transitoire : il cesse quand l'agent s'abonne.

---

## 10. Recette de demarrage

```bash
export MHI_API="https://api.monhubimmo.fr/api/external/v1"
export MHI_API_KEY="<votre cle>"
```

**1. Verifier la cle**

```bash
curl -s "$MHI_API/health" -H "X-API-Key: $MHI_API_KEY"
# attendu : { "success": true, "partner": { ... } }
```

**2. Creer un agent** — notez bien le `user.id` renvoye, c'est votre `userId` pour la suite.

```bash
curl -s -X POST "$MHI_API/users" \
  -H "X-API-Key: $MHI_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "email": "agent.test@exemple.fr",
    "firstName": "Agent", "lastName": "Test", "phone": "0612345678",
    "externalId": "recette-1",
    "professionalInfo": {
      "city": "Lyon", "postalCode": "69001",
      "interventionRadius": 25,
      "coveredCities": [{ "city": "Lyon", "postalCode": "69001" }],
      "yearsExperience": 5,
      "personalPitch": "Agent immobilier a Lyon depuis cinq ans, specialise dans l accompagnement des primo-accedants sur les 1er et 2e arrondissements. Je connais finement le marche du centre, les coproprietes anciennes et les delais reels de transaction. Mon approche repose sur une estimation argumentee par les ventes comparables, une communication hebdomadaire et une disponibilite reelle en soiree comme le samedi."
    }
  }'
```

**3. Publier un bien** — il nait en `draft`.

```bash
curl -s -X POST "$MHI_API/properties" \
  -H "X-API-Key: $MHI_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "userId": "<user.id de l etape 2>",
    "externalId": "bien-recette-1",
    "title": "Appartement T3 lumineux centre Lyon",
    "description": "Appartement de trois pieces au coeur du 1er arrondissement, traversant, au troisieme etage avec ascenseur. Cuisine equipee, parquet, double vitrage.",
    "price": 320000, "surface": 72,
    "propertyType": "Appartement", "transactionType": "Vente",
    "city": "Lyon", "postalCode": "69001", "sector": "Pentes de la Croix-Rousse",
    "rooms": 3, "bedrooms": 2, "hasElevator": true
  }'
```

**4. Le passer en ligne**

```bash
curl -s -X PATCH "$MHI_API/properties/<property.id>" \
  -H "X-API-Key: $MHI_API_KEY" -H "Content-Type: application/json" \
  -d '{ "status": "active" }'
```

**5. Verifier, par votre propre reference**

```bash
curl -s "$MHI_API/properties/mine?externalId=bien-recette-1" -H "X-API-Key: $MHI_API_KEY"
```

Si ces cinq appels passent, l'integration est bonne : le reste n'est que du remplissage de
champs. En cas de 422, lisez `details[]` — il nomme le champ fautif.
