> ## Documentation Index
> Fetch the complete documentation index at: https://developers.avest.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# GET Rental

> Récupère une location par son id Mongo ou son customId métier, avec ses contacts liés.

Récupère une location par son `id` MongoDB ou son `customId` métier, avec ses contacts liés.

## Endpoint

**URL** : `/external-integration/rental`
**Méthode** : `GET`
**Authentification** : Requiert un token LinkedAPI avec scope `externalIntegration` (GET) et `agencyGroup` configuré.
**Clé requise** : toutes les clés (lecture seule suffit). Voir [Types de clé](https://developers.avest.fr/guides/authentification.md).

## Headers

```
Authorization: Bearer {token}
X-Real-IP: {ip_whitelistée}     # Requis uniquement si linkedAPI.secure === true
```

## Query Parameters

| Paramètre | Type | Requis | Description |
| - | - | - | - |
| `id` | ObjectId | ✅ ou ✅\* | Identifiant Mongo de la location (24 chars hex) |
| `customId` | String | ✅\* ou ✅ | Identifiant métier (ex: `L-2025-001`) |

> [!WARNING]
>
> **Exactement un** des deux paramètres doit être fourni. Pas zéro, pas les
> deux.

## Exemple de requête

```bash theme={null}
GET /external-integration/rental?customId=L-2025-001
Authorization: Bearer your-linked-api-token
```

```bash theme={null}
GET /external-integration/rental?id=619b46b47e043165f206db1d
Authorization: Bearer your-linked-api-token
```

## Logique de fonctionnement

1. **Validation des params** : Vérifie qu'un seul des deux paramètres est fourni et valide son format
2. **Recherche scopée** : Filtre sur `agencyGroup === linkedAPI.agencyGroup` ET `agency ∈ linkedAPI.agencies`
3. **Récupération des contacts** : Si location trouvée, fetch des contacts liés (re-scopés sur les mêmes agences)
4. **Sérialisation** : Tous les champs publics renseignés sur la fiche sont retournés. Les champs **non renseignés sont absents de la réponse** (pas `null`). Le contact principal de la location est exposé via `rental.mainContact` (ID), le détail complet du contact est dans la clé `contacts` au top-level.

## Réponse de succès

**Code** : `200`

### Location trouvée

```json theme={null}
{
  "success": true,
  "rental": {
    "id": "69fcb723ac44aa882a150bbc",
    "customId": "REBZJ7515",
    "agency": "6937f7389200187f198aaa07",
    "agencyGroup": "66cc8a8e75c9fac35c6ecd73",
    "step": "RQUL",
    "project": "OTR",
    "type": "longTerm",
    "property": {
      "mainType": "apartment",
      "developmentType": "old",
      "size": 24.79,
      "floor": 2,
      "lastFloor": 2,
      "rooms": 2,
      "bedrooms": 1,
      "kitchenType": "open",
      "isCollectiveOwnership": false,
      "addressData": {
        "streetNumber": "21",
        "route": "Rue des Salines",
        "postalCode": "87500",
        "city": "Saint-Yrieix-la-Perche",
        "country": "France",
        "countryCode": "FR",
        "formattedAddress": "21 Rue Des Salines, 87500 Saint-Yrieix-la-Perche"
      },
      "DPEEnergyValue": 253,
      "DPEEnergyTag": "E",
      "DPEGESValue": 8,
      "DPEGESTag": "B",
      "heatingType": "individual",
      "heatingEnergyType": "electric"
    },
    "owner": {
      "id": "693fd8823b8b4059ba4ea468",
      "firstName": "Imogen",
      "lastName": "RUSSEL"
    },
    "mainContact": "694a6a2fbe34c245521ce681",
    "createdAt": "2026-05-07T16:00:35.683Z"
  },
  "contacts": [
    {
      "id": "694a6a2fbe34c245521ce681",
      "title": "mr",
      "firstName": "Raphael",
      "lastName": "LORENZI",
      "isIndividual": true,
      "contactDetails": [{ "type": "email", "data": "raph.lorenzi@example.fr" }]
    }
  ]
}
```

> [!NOTE]
>
> Note de migration : les champs `customId` et `step` sont retournés à partir du
> déploiement de cette version. Si votre intégration utilisait cette route
> avant, ces deux champs étaient absents — vérifier que vous les récupérez
> désormais.

### Location non trouvée ou hors scope

```json theme={null}
{
  "success": true,
  "rental": null,
  "contacts": []
}
```

> [!NOTE]
>
> Une fiche existant dans une autre `agencyGroup` retourne ce même payload
> (`null`). Pas de différenciation possible côté client entre "n'existe pas" et
> "pas autorisé".

## Champs de la réponse

### Top-level `rental`

Toujours présents (si la location existe) :

| Champ | Type | Description |
| - | - | - |
| `id` | String | ObjectId Mongo de la location |
| `customId` | String | Identifiant métier (ex: `REBZJ7515`) |
| `agency` | String | ObjectId de l'agence propriétaire |
| `agencyGroup` | String | ObjectId du groupe d'agences |
| `step` | String | Étape courante (`RQUL`, `RCNV`, `RVST`, `RBAIL`, `ROCC`, ...) |
| `createdAt` | ISO 8601 | Date de création |
| `owner` | Object \| null | Utilisateur Avest responsable du dossier (`id`, `firstName`, `lastName`, `picture` optionnelle) |
| `mainContact` | String \| null | ObjectId du bailleur principal. À utiliser avec `GET /external-integration/contact` pour récupérer email/téléphone. |

Présents uniquement si renseignés (sinon clé absente, pas `null`) :

| Champ | Type | Description |
| - | - | - |
| `type` | String | `longTerm` (location classique), `furnishedRental`, `seasonal`, ... |
| `project` | String | Projet bailleur (`OTR`, ...) |
| `property` | Object | Bien à louer (voir section dédiée) |
| `mandate` | Object | Mandat de location (renseigné à partir de l'étape `RMDT`) |
| `timeline` | Object | Dates clés (mandat, bail) |
| `fieldValue` | `{ low, high }` | Estimation loyer terrain |
| `onlineValue` | `{ low, high }` | Estimation loyer en ligne |
| `fieldQuote` | `{ low, high }` | Devis loyer terrain |
| `onlineQuote` | `{ low, high }` | Devis loyer en ligne |
| `currentValue` | Number | Loyer effectif actuel |
| `parsingCustomId` | String | Identifiant interne d'import |

> [!WARNING]
>
> **`mandate` et `timeline` sont actuellement renvoyés vides (`{}`)** sur cet
> endpoint, quel que soit l'état de la location. Ne construisez pas
> d'intégration sur leur contenu pour l'instant — un correctif est prévu et
> sera annoncé dans le [changelog](https://developers.avest.fr/changelog.md).

### `property`

`property.addressData` (présent si la fiche a une adresse — adresse splittée) :

| Champ | Description |
| - | - |
| `streetNumber` | Numéro de rue |
| `route` | Voie |
| `city` | Ville |
| `postalCode` | Code postal |
| `country` | Pays |
| `countryCode` | Code pays ISO 3166-1 alpha-2 |
| `formattedAddress` | Adresse concaténée formatée |

Autres champs `property` retournés s'ils sont renseignés (même set que pour [GET Sale](https://developers.avest.fr/endpoints/get-sale.md)) : `mainType` (`apartment`, `house`, `building`, ...), `developmentType` (`old`/`new`), `size`, `floor`, `rooms`, `bedrooms`, `bathrooms`, `toilets`, `kitchenType`, surfaces (`floorSurface`, `livingSurface`, `usefulSurface`, ...), extérieurs (`balconyAmount`, `terraceAmount`, `gardenAmount`, ...), équipements (`hasElevator`, `hasFireplace`, `isAirConditioning`, ...), DPE (`DPENumber`, `DPEEnergyValue`, `DPEEnergyTag`, `DPEGESValue`, `DPEGESTag`, `DPEDate`), copropriété (`isCollectiveOwnership`, `collectiveMonthlyCost`, `numberOfLots`), `availabilityDate`, etc. Biens professionnels : `vatRegime` (`subject` soumis à TVA, `exempt` non soumis) et `propertyTaxResponsibility` (taxe foncière à la charge du bailleur, `owner`, ou du preneur, `tenant`).

### `contacts` (top-level)

Liste des contacts liés à la location. Le **premier élément** correspond au `mainContact` au top-level. Mêmes champs que pour les autres routes externes (cf. [GET Sale](https://developers.avest.fr/endpoints/get-sale.md)).

## Réponses d'erreur

* **Aucun paramètre fourni** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationGetTransaction : Either id or customId is required"
}
```

* **Les deux paramètres fournis** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationGetTransaction : Provide either id or customId, not both"
}
```

* **`id` invalide** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationGetTransaction : Invalid id"
}
```

* **`customId` invalide** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationGetTransaction : Invalid customId"
}
```

* **LinkedAPI agencyGroup manquant** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "LinkedAPI agencyGroup is required"
}
```

* **Header `Authorization` absent, ou IP non whitelistée sur une clé sécurisée** : `403 Not authorized to access this resource`

```json theme={null}
{
  "success": false,
  "message": "Not authorized to access this resource"
}
```

* **Token invalide** : `401 Invalid bearer token`

```json theme={null}
{
  "success": false,
  "message": "Invalid bearer token"
}
```

## Notes importantes

1. **Scope strict** : La fiche n'est retournée que si elle appartient à la `agencyGroup` du token ET à une des `agencies` listées dans le LinkedAPI. Aucune fuite cross-group, même avec un `id` Mongo connu d'une autre agence.
2. **Pas de différenciation 404 vs 403** : Une fiche hors scope retourne le même `null` qu'une fiche inexistante. Choix volontaire pour ne pas leak l'existence de fiches d'autres agences.
3. **Contacts re-scopés** : Les contacts liés sont eux-mêmes filtrés sur `agency ∈ linkedAPI.agencies` pour éviter les fuites cross-group.
4. **Idempotence** : L'endpoint est purement en lecture. Aucune modification d'état.
5. **Cas d'usage typique** : Réception d'une notification de nouveau lead → extraction du `customId` ou `id` du mail → appel GET → récupération email/nom/adresse du bien pour automatisation (Make, Zapier, etc.).
6. **Champs absents vs `null`** : les champs non renseignés sur la fiche n'apparaissent **pas du tout** dans la réponse — ils ne sont pas retournés à `null`. Côté client, traiter chaque champ comme optionnel.
7. **Lien vers le bailleur** : pour récupérer les coordonnées du bailleur principal, faire `GET /external-integration/contact` avec l'ID `mainContact`.

## Rate limits

Cette route est limitée à **500 req / minute par groupe d'agences** (bucket dédié, indépendant des autres routes).

* Headers présents sur **toutes** les réponses : `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` (secondes avant reset).
* Dépassement → `429 Too Many Requests` avec header `Retry-After` (secondes) :

```json theme={null}
{
  "success": false,
  "message": "Rate limit exceeded",
  "retryAfter": 27
}
```

* Si vous atteignez régulièrement la limite, contactez le support pour évaluer un relèvement sur votre token.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.