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

# POST Rental

> Crée ou met à jour une location avec déduplication automatique du contact et de la transaction.

Crée ou met à jour une location (fiche bailleur / gestion locative) avec déduplication automatique du contact et de la transaction.

## Endpoint

**URL** : `/external-integration/rental`
**Méthode** : `POST`
**Authentification** : Requiert un token LinkedAPI.
**Clé requise** : lecture-écriture. Une clé en lecture seule reçoit `403`. Voir [Types de clé](https://developers.avest.fr/guides/authentification.md).

## Headers

```
Content-Type: application/json
Authorization: Bearer {token}
```

## Logique de fonctionnement

### 1. Déduplication Contact

* Recherche d'un contact existant par téléphone ou email dans le groupe d'agences
* Si trouvé : mise à jour des informations
* Si non trouvé : création d'un nouveau contact

### 2. Déduplication Transaction

* Si contact existant, recherche de la location la plus récente de ce contact à la même adresse, quelle que soit son étape (voir [Déduplication](https://developers.avest.fr/guides/deduplication.md))
* Si trouvée : mise à jour de la location existante
* Si non trouvée : création d'une nouvelle location

### 3. Allocation

* Attribution automatique d'un utilisateur et d'une agence selon les règles configurées
* Possibilité de forcer l'allocation via `settings.allocation`

### 4. Routing Step

* Calcul automatique de l'étape selon le projet et la configuration de l'agence
* Possibilité de forcer l'étape d'une nouvelle location via `settings.step`. Sur une location retrouvée, l'étape ne change pas, sauf une location archivée (`RARC`), rouverte à l'étape calculée ou à `settings.step`

### 5. Activités optionnelles

* **Appointment** : Crée une activité de type "meeting" avec date, heures et note
* **Note** : Crée une activité de type "note" avec titre et contenu

## Body Parameters

### Structure complète

```typescript theme={null}
{
    settings: {
        allocation: {
            agencyGroupId: string;           // Required - Groupe d'agences de votre clé (GET Agencies)
            agencyId?: string;               // Optional - Force l'agence (une agence de GET Agencies)
            userId?: string;                 // Optional - Force l'utilisateur (requiert agencyId)
            disableDeduplication?: boolean;  // Optional - Désactive la déduplication (défaut: false)
        };
        step?: string;                       // Optional - Force l'étape
        disableAlerts?: boolean;             // Optional - Désactive l'envoi de l'email d'alerte nouveau lead (défaut: false)
    };
    appointment?: {                          // Optional - Crée un RDV
        date: string;                        // Required - Date ISO du RDV (ne peut pas être dans le passé)
        startAt?: string;                    // Optional - Heure de début ISO
        endAt?: string;                      // Optional - Heure de fin ISO
        note?: string;                       // Optional - Note du RDV
    };
    note?: {                                 // Optional - Crée une note
        title: string;                       // Required si note - Titre
        content?: string;                    // Optional - Contenu
    };
    transactionType: "rental";               // Required
    contact?: {
        firstName?: string;
        lastName?: string;
        email?: string;
        isEmailVerified?: boolean;
        phone?: string;
        isPhoneVerified?: boolean;
    };
    address: string;                         // Required - Adresse complète du bien
    transaction: TransactionRental;          // Required - Données de la location
}
```

## Détail des paramètres

### settings.allocation

| Champ | Type | Requis | Description |
| - | - | - | - |
| `agencyGroupId` | ObjectId | ✅ | Groupe d'agences **de votre clé** : `agencyGroup.id` de [GET Agencies](https://developers.avest.fr/endpoints/get-agencies.md). Un autre groupe est refusé (`400`). |
| `agencyId` | ObjectId | ❌ | Agence à qui attribuer le lead (force l'allocation). Doit figurer dans les `agencies` de [GET Agencies](https://developers.avest.fr/endpoints/get-agencies.md) : une agence que votre clé ne couvre pas, ou désactivée, est refusée (`400`). |
| `userId` | ObjectId | ❌ | ID de l'utilisateur (force l'allocation, requiert agencyId) |
| `disableDeduplication` | Boolean | ❌ | Désactive la déduplication de transaction (défaut: false) |

Sans `agencyId`, l'attribution est automatique, parmi les agences du groupe.

### settings.disableAlerts

| Type | Requis | Description |
| - | - | - |
| Boolean | ❌ | Si `true`, l'email d'alerte « nouveau lead bailleur » n'est pas envoyé (défaut: `false`) |

### settings.step

#### Étapes prospects bailleurs

| Valeur | Description |
| - | - |
| `RQUL` | Nouveau |
| `RCNV` | Relance |
| `RRDV` | Estimation (R1) |
| `RDLV` | Remise (R2) |
| `RARC` | Archive |

#### Étapes mandats de gestion (après signature mandat)

| Valeur | Description |
| - | - |
| `RMDT` | À louer |
| `RRTM` | Loué avec gestion |
| `RRTD` | Loué sans gestion |
| `RMAR` | Mandat archivé |

### appointment

Crée une activité de type "meeting" (rendez-vous) liée à la transaction.

| Champ | Type | Requis | Description |
| - | - | - | - |
| `date` | String | ✅ (si appointment) | Date ISO du RDV (ne peut pas être passée) |
| `startAt` | String | ❌ | Heure de début ISO |
| `endAt` | String | ❌ | Heure de fin ISO |
| `note` | String | ❌ | Note associée au RDV (dans `data.content`) |

> [!NOTE]
>
> Le titre de l'activité sera automatiquement défini comme "Rendez-vous
> estimation".

### note

Crée une activité de type "note" liée à la transaction.

| Champ | Type | Requis | Description |
| - | - | - | - |
| `title` | String | ✅ (si note) | Titre de la note |
| `content` | String | ❌ | Contenu de la note |

### contact

| Champ | Type | Description |
| - | - | - |
| `firstName` | String | Prénom du contact |
| `lastName` | String | Nom du contact |
| `email` | String | Email du contact |
| `isEmailVerified` | Boolean | Email vérifié |
| `phone` | String | Téléphone au format international |
| `isPhoneVerified` | Boolean | Téléphone vérifié |

### address

| Type | Description |
| - | - |
| String | Adresse complète du bien (ex: "11 rue de Paris, 75001 Paris, France") |

## transaction (TransactionRental)

### Projet et identifiant

| Champ | Type | Requis | Description |
| - | - | - | - |
| `project` | String | ✅\* | Type de projet. \*Requis si `settings.step` non fourni |
| `parsingCustomId` | String | ❌ | Identifiant personnalisé externe |
| `type` | String | ❌ | Type de location (voir valeurs ci-dessous) |

| Valeur | Description |
| - | - |
| `empty` | Vide |
| `furnished` | Meublé |
| `mobility` | Mobilité |
| `professional` | Professionnel |
| `student` | Étudiant |
| `commercial` | Commercial |

### Valeurs de project

| Valeur | Description |
| - | - |
| `RAPT` | Demande de rendez-vous |
| `Q` | Demande de devis |
| `OR` | Bien actuellement loué |
| `OTR` | Bien prochainement loué |
| `O!R` | Pas de projet déclaré |
| `BTR` | Investisseur locatif |
| `R` | Locataire |

### Propriété (transaction.property)

```typescript theme={null}
{
    mainType?: "house" | "apartment" | "building" | "field" | "parking" | "cellar" | "office" | "shop" | "industry" | "business_assets" | "lease_transfer";
    developmentType?: "old" | "new";
    generalCondition?: "toRenovate" | "standard" | "renovated";
    size?: number;                    // Surface en m²
    carrezSurface?: number;           // Surface Carrez en m²
    livingSurface?: number;           // Surface habitable en m²
    buildingYear?: number;            // Année de construction
    renovationYear?: number;          // Année de rénovation
    floor?: number;                   // Étage
    totalFloors?: number;             // Nombre total d'étages
    rooms?: number;                   // Nombre de pièces
    bedrooms?: number;                // Nombre de chambres
    bathrooms?: number;               // Nombre de salles de bain
    showerRooms?: number;             // Nombre de salles d'eau
    toilets?: number;                 // Nombre de WC
    kitchenType?: "open" | "independent";
    isKitchenEquipped?: boolean;      // Cuisine équipée
    balconyAmount?: number;           // Nombre de balcons
    balconySurface?: number;          // Surface balcons en m²
    loggiaAmount?: number;            // Nombre de loggias
    loggiaSurface?: number;           // Surface loggias en m²
    terraceAmount?: number;           // Nombre de terrasses
    terraceSurface?: number;          // Surface terrasses en m²
    gardenAmount?: number;            // Nombre de jardins
    gardenSurface?: number;           // Surface jardin en m²
    cellarAmount?: number;            // Nombre de caves
    cellarSurface?: number;           // Surface caves en m²
    parkingType?: "outdoor" | "covered" | "garage";
    parkingAmount?: number;           // Nombre de places
    hasElevator?: boolean;            // Ascenseur
    hasPool?: boolean;                // Piscine
    DPEEnergyValue?: number;          // Valeur énergie DPE
    DPEEnergyTag?: "A" | "B" | "C" | "D" | "E" | "F" | "G";
    DPEGESValue?: number;             // Valeur GES
    DPEGESTag?: "A" | "B" | "C" | "D" | "E" | "F" | "G";
    propertyTaxResponsibility?: "owner" | "tenant"; // Taxe foncière à la charge du bailleur ou du preneur (bien professionnel)
    vatRegime?: "subject" | "exempt";               // Bien professionnel soumis ou non à la TVA
    // ... autres champs property identiques à sale
}
```

La règle du DPE d'un bien professionnel est celle de [POST Sale](https://developers.avest.fr/endpoints/post-sale.md) : les étiquettes transmises sont gardées telles quelles.

### Estimations et valeurs

```typescript theme={null}
{
    fieldValue?: {                    // Estimation location - Sur place
        low?: number;
        high?: number;
    };
    onlineValue?: {                   // Estimation location - En ligne
        low?: number;
        high?: number;
    };
    fieldQuote?: number;              // Devis gestion - Sur place
    onlineQuote?: number;             // Devis gestion - En ligne
    currentValue?: number;            // Loyer actuel
}
```

### Mandat (transaction.mandate)

```typescript theme={null}
{
    mandate?: {
        // Informations du mandat de gestion locative
    };
}
```

### Timeline (transaction.timeline)

```typescript theme={null}
{
    timeline?: {
        // Dates importantes de la location
    };
}
```

## Exemple complet

```json theme={null}
{
  "settings": {
    "allocation": {
      "agencyGroupId": "66cc8a8e75c9fac35c6ecd73",
      "agencyId": "66cc91d475c9fac35c86ed80",
      "userId": "66cc91f05f84c9b212d9ec24",
      "disableDeduplication": false
    },
    "step": "RQUL"
  },
  "appointment": {
    "date": "2025-01-20T00:00:00.000Z",
    "startAt": "2025-01-20T10:00:00.000Z",
    "endAt": "2025-01-20T11:00:00.000Z",
    "note": "RDV visite du bien pour estimation"
  },
  "note": {
    "title": "Nouveau bailleur",
    "content": "Client souhaite mettre son bien en gestion"
  },
  "transactionType": "rental",
  "contact": {
    "firstName": "Jean",
    "lastName": "Dupont",
    "email": "jean.dupont@email.com",
    "phone": "+33612345678"
  },
  "address": "11 rue de Paris, 75001 Paris, France",
  "transaction": {
    "project": "OR",
    "type": "empty",
    "property": {
      "mainType": "apartment",
      "size": 45,
      "rooms": 2,
      "bedrooms": 1,
      "hasElevator": true,
      "floor": 2,
      "DPEEnergyTag": "C"
    },
    "fieldValue": {
      "low": 900,
      "high": 1100
    },
    "currentValue": 950,
    "parsingCustomId": "EXT-RENTAL-2025-001"
  }
}
```

Les `agencyGroupId` et `agencyId` de l'exemple sont ceux de l'exemple de [GET Agencies](https://developers.avest.fr/endpoints/get-agencies.md) : remplacez-les par ceux que GET Agencies renvoie pour votre clé, et `userId` par un collaborateur de cette agence ([GET Users](https://developers.avest.fr/endpoints/get-users.md) liste ceux du groupe).

## Réponse de succès

**Code** : `200`

```json theme={null}
{
  "success": true,
  "avestId": "L-2025-001",
  "user": {
    "id": "66cc91f05f84c9b212d9ec24",
    "firstName": "Marie",
    "lastName": "Martin",
    "jobTitle": "Gestionnaire locatif",
    "email": "marie.martin@agence.com",
    "phone": "+33601020304"
  },
  "contact": {
    "id": "618a35a36d932054e195ca0a",
    "firstName": "Jean",
    "lastName": "Dupont"
  },
  "transaction": {
    "id": "619b46b47e043165f206db1d",
    "customId": "L-2025-001",
    "step": "RQUL",
    "project": "OR",
    "property": {
      "addressData": {
        "streetNumber": "11",
        "route": "Rue de Paris",
        "postalCode": "75001",
        "city": "Paris",
        "country": "France",
        "countryCode": "FR",
        "formattedAddress": "11 Rue de Paris, 75001 Paris, France"
      },
      "addresses": [
        {
          "streetNumber": "11",
          "route": "Rue de Paris",
          "postalCode": "75001",
          "city": "Paris",
          "country": "France",
          "countryCode": "FR",
          "formattedAddress": "11 Rue de Paris, 75001 Paris, France"
        }
      ]
    }
  }
}
```

`transaction.property.addressData` est l'adresse reconnue et enregistrée sur le bien, au format de [GET Rental](https://developers.avest.fr/endpoints/get-rental.md) ; `transaction.property.addresses` la contient aussi. Comparez-la à l'`address` envoyée pour repérer une adresse mal reconnue. Elle n'est pas renvoyée si la fiche est attribuée à une agence que votre clé ne couvre pas, comme sur GET.

## Réponses d'erreur

* **Settings manquants** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "LeadGenerationExternalRental : Settings is required"
}
```

* **Allocation manquante** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "LeadGenerationExternalRental : Settings allocation is required"
}
```

* **AgencyGroupId manquant** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "LeadGenerationExternalRental : Agency group ID is required"
}
```

* **Groupe d'agences hors du périmètre de votre clé** : `400 Bad Request`, aucun lead créé

```json theme={null}
{
  "success": false,
  "message": "LeadGenerationExternalRental : Agency group is not in the authorized scope of this LinkedAPI"
}
```

* **Agence de votre groupe que votre clé ne couvre pas, ou désactivée** : `400 Bad Request`, aucun lead créé (une agence d'un autre groupe reçoit, avec le même préfixe, `Agency group ID is not the same as the agency group ID`)

```json theme={null}
{
  "success": false,
  "message": "LeadGenerationExternalRental : Agency is not in the authorized scope of this LinkedAPI"
}
```

* **Adresse manquante** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "LeadGenerationExternalRental : Invalid body : address required"
}
```

* **Property manquant** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "LeadGenerationExternalRental : Invalid transaction : property required"
}
```

* **Project manquant** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "LeadGenerationExternalRental : transaction.project is required if settings.step is not provided"
}
```

## Notes importantes

1. **Déduplication** : Par défaut, si un contact existe avec le même téléphone/email, la location existante à la même adresse sera mise à jour plutôt que d'en créer une nouvelle.

2. **Allocation automatique** : Sans `agencyId`/`userId`, le système alloue automatiquement selon les règles configurées (zones, shifts, priorité contact, etc.)

3. **Activités** : `appointment` et `note` créent des activités séparées liées à la transaction. En cas d'erreur sur ces créations, la transaction est quand même créée (notification Slack envoyée).

4. **Steps** : Si `settings.step` n'est pas fourni, l'étape est calculée automatiquement selon le `project` et la configuration de l'agence.

5. **Identifiant externe** : `parsingCustomId` est enregistré sur la fiche et renvoyé en lecture, mais il ne sert pas au dédoublonnage. Deux envois avec le même `parsingCustomId` peuvent créer deux locations. Conservez l'`id` renvoyé à la création pour retrouver la fiche.

## Rate limits

Cette route est limitée à **100 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.