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

> Crée ou met à jour une acquisition avec déduplication et matching optionnel d'une vente.

Crée ou met à jour une acquisition (fiche acquéreur) avec déduplication automatique du contact et de la transaction, et possibilité de créer un match avec une vente existante.

## Endpoint

**URL** : `/external-integration/acquisition`
**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 d'une acquisition de ce contact, quelle que soit son étape (voir [Déduplication](https://developers.avest.fr/guides/deduplication.md))
* Si trouvée : mise à jour de l'acquisition existante
* Si non trouvée : création d'une nouvelle acquisition

### 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 acquisition via `settings.step`. Sur une acquisition retrouvée, l'étape ne change pas : passez par [Qualifier un acquéreur](https://developers.avest.fr/endpoints/post-acquisition-qualify.md)

### 5. Matching (Optionnel)

* Création automatique d'un match entre l'acquisition et une vente existante
* Via référence d'annonce (`ref`) ou ID de vente (`saleId`)

## 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)
        matching?: {                         // Optional - ACQUISITION ONLY - Crée un match
            ref?: string;                    // Référence annonce (mutuellement exclusif avec saleId)
            saleId?: string;                 // ID vente (mutuellement exclusif avec ref)
        };
    };
    note?: {                                 // Optional - Crée une note
        title: string;                       // Required si note - Titre
        content?: string;                    // Optional - Contenu
    };
    transactionType: "acquisition";          // Required
    contact?: {
        firstName?: string;
        lastName?: string;
        email?: string;
        isEmailVerified?: boolean;
        phone?: string;
        isPhoneVerified?: boolean;
    };
    transaction: TransactionAcquisition;     // Required - Données de l'acquisition
}
```

## 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 « nouvel acquéreur » n'est pas envoyé (défaut: `false`) |

### settings.step

| Valeur | Description |
| - | - |
| `AQUL` | À qualifier |
| `ASRC` | En recherche |
| `ANGT` | En négociation |
| `AOFR` | Offre acceptée |
| `ACLS` | Achat signé |
| `AARC` | Archive |

### settings.matching (ACQUISITION ONLY)

Permet de créer automatiquement un match entre l'acquisition et une vente existante.

| Champ | Type | Requis | Description |
| - | - | - | - |
| `ref` | String | ❌ | Référence de l'annonce à matcher |
| `saleId` | ObjectId | ❌ | ID de la vente à matcher |

> [!WARNING]
>
> **Important** : `ref` et `saleId` sont **mutuellement exclusifs**. Utilisez
> l'un OU l'autre, jamais les deux.

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

## transaction (TransactionAcquisition)

### Projet et identifiant

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

| Valeur | Description |
| - | - |
| `buyer` | Acheteur simple |
| `buyerOwner` | Acheteur déjà propriétaire |
| `buyerSeller` | Acheteur qui doit d'abord vendre |

### Niveau d'activité et but

```typescript theme={null}
{
    activityLevel?: "hot" | "warm" | "cold" | "mandate";
    purpose?: "primaryResidence" | "secondaryResidence" | "businessPremise" | "investment" | "propertyTrade";
}
```

### Types de biens recherchés

```typescript theme={null}
{
    propertiesTypes?: ("house" | "apartment" | "building" | "field" | "parking" | "cellar" | "office" | "shop" | "industry" | "business_assets" | "lease_transfer")[];
}
```

### Zones de recherche

```typescript theme={null}
{
    areas?: Array<{
        type: "postalCode" | "inseeCode" | "departmentCode" | "geometry";  // Required - Type de zone
        postalCode?: string;        // Code postal (requis si type = "postalCode")
        inseeCode?: string;         // Code INSEE (requis si type = "inseeCode")
        departmentCode?: string;    // Code département (requis si type = "departmentCode")
        name?: string;              // Nom de la zone
        countryCode?: string;       // Code pays ISO (défaut: "FR")
        geometry?: {                // Géométrie GeoJSON (requis si type = "geometry")
            type: "Polygon";
            coordinates: number[][][];
        };
        center?: {                  // Centre d'une zone tracée en cercle (type = "geometry")
            type: "Point";
            coordinates: [number, number];  // [longitude, latitude]
        };
        radius?: number;            // Rayon de ce cercle, en km (> 0)
    }>;
}
```

`geometry` est le polygone qui sert à la recherche et à l'attribution. `center` et `radius` décrivent le cercle tracé, pour qu'Avest le rouvre comme tel : transmettez-les avec le polygone de ce cercle, jamais seuls. Un `center` qui n'est pas un `Point`, ou un `radius` nul ou négatif, est refusé (`400`).

### Critères de recherche (RangeValue)

Tous ces champs acceptent un objet `{ low?: number, high?: number }` :

```typescript theme={null}
{
    priceRange?: { low?: number; high?: number };    // Budget en €
    sizeRange?: { low?: number; high?: number };     // Surface en m²
    fieldRange?: { low?: number; high?: number };    // Surface terrain en m²
    roomRange?: { low?: number; high?: number };     // Nombre de pièces
    bedroomRange?: { low?: number; high?: number };  // Nombre de chambres
    floorRange?: { low?: number; high?: number };    // Étage
}
```

### Critères de nécessité

Ces champs acceptent les valeurs : `unnecessary`, `preferable`, `essential` ou `excluded` (critère éliminatoire : le bien ne doit pas en avoir, pris en compte par le rapprochement)

```typescript theme={null}
{
    elevator?: "unnecessary" | "preferable" | "essential" | "excluded";
    outdoor?: "unnecessary" | "preferable" | "essential" | "excluded";
    parking?: "unnecessary" | "preferable" | "essential" | "excluded";
    pool?: "unnecessary" | "preferable" | "essential" | "excluded";
    bikeShed?: boolean;
}
```

### Financement

```typescript theme={null}
{
    mortgageType?: "relay" | "standard" | "none";
    mortgage?: boolean;
}
```

### Mandat de recherche

```typescript theme={null}
{
    mandate?: {
        signatureDate?: string;                  // Date de signature (format ISO)
        type?: "exclusive" | "notExclusive";     // Type de mandat
        commission?: number;                     // Commission en €
    };
}
```

## Exemple complet

```json theme={null}
{
  "settings": {
    "allocation": {
      "agencyGroupId": "66cc8a8e75c9fac35c6ecd73",
      "agencyId": "66cc91d475c9fac35c86ed80",
      "userId": "66cc91f05f84c9b212d9ec24",
      "disableDeduplication": false
    },
    "step": "AQUL",
    "matching": {
      "ref": "REF-2025-001"
    }
  },
  "note": {
    "title": "Demande sur annonce",
    "content": "Client intéressé par l'annonce REF-2025-001"
  },
  "transactionType": "acquisition",
  "contact": {
    "firstName": "Jean",
    "lastName": "Dupont",
    "email": "jean.dupont@email.com",
    "phone": "+33612345678"
  },
  "transaction": {
    "project": "buyer",
    "activityLevel": "hot",
    "propertiesTypes": ["apartment", "house"],
    "priceRange": {
      "low": 200000,
      "high": 350000
    },
    "sizeRange": {
      "low": 60,
      "high": 120
    },
    "bedroomRange": {
      "low": 2,
      "high": 4
    },
    "elevator": "preferable",
    "outdoor": "essential",
    "parking": "unnecessary",
    "mortgageType": "standard",
    "purpose": "primaryResidence",
    "areas": [
      {
        "type": "postalCode",
        "postalCode": "75001",
        "name": "Paris",
        "countryCode": "FR"
      }
    ],
    "parsingCustomId": "EXT-ACQ-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": "A-2025-001",
  "user": {
    "id": "66cc91f05f84c9b212d9ec24",
    "firstName": "Marie",
    "lastName": "Martin",
    "jobTitle": "Agent immobilier",
    "email": "marie.martin@agence.com",
    "phone": "+33601020304"
  },
  "contact": {
    "id": "618a35a36d932054e195ca0a",
    "firstName": "Jean",
    "lastName": "Dupont"
  },
  "transaction": {
    "id": "619b46b47e043165f206db1c",
    "customId": "A-2025-001",
    "step": "AQUL",
    "project": "buyer"
  }
}
```

## Réponses d'erreur

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

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

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

```json theme={null}
{
  "success": false,
  "message": "LeadGenerationExternalAcquisition : Settings allocation 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": "LeadGenerationExternalAcquisition : 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": "LeadGenerationExternalAcquisition : Agency is not in the authorized scope of this LinkedAPI"
}
```

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

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

* **Matching mutuellement exclusif** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "LeadGenerationExternalAcquisition : matching: ref and saleId are mutually exclusive"
}
```

* **Matching uniquement pour acquisitions** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "LeadGenerationExternalAcquisition : matching is only available for acquisitions"
}
```

## Fonctionnalité Matching

Le matching permet de lier automatiquement une acquisition à une vente existante, créant ainsi un "match" entre l'acquéreur et le bien.

### Par référence d'annonce (ref)

```json theme={null}
{
  "settings": {
    "matching": {
      "ref": "REF-2025-001"
    }
  }
}
```

**Processus** :

1. Recherche de l'annonce par référence dans le groupe d'agences
2. Si trouvée, récupération de la vente associée
3. Création d'un match entre l'acquisition et la vente avec étape `MRQT`

### Par ID de vente (saleId)

```json theme={null}
{
  "settings": {
    "matching": {
      "saleId": "66cc91d475c9fac35c86ed80"
    }
  }
}
```

**Processus** :

1. Recherche directe de la vente par ID
2. Si trouvée, création d'un match avec étape `MRQT`

### Match créé

Lorsqu'un match est créé, il est initialisé avec :

* **step** : `MRQT` (Match Request)
* **owner** : L'utilisateur alloué
* **agency** : L'agence allouée
* Liens vers l'acquisition et la vente

> [!NOTE]
>
> Si un match existe déjà entre l'acquisition et la vente, il n'est **pas
> recréé** : le match existant est réutilisé.

> [!WARNING]
>
> **Un match existant peut être remis à l'étape `MRQT`.** Si le match trouvé se
> situe à une étape *antérieure* à `MRQT` — c'est-à-dire `MSND` (simple
> proposition) ou **n'importe quelle étape « sans suite » `_NF`** — il est
> **remonté** à `MRQT` (nouvelle demande), car la requête est traitée comme une
> demande entrante de l'acquéreur.
>
> Conséquence : reposter une acquisition avec `settings.matching` sur une mise
> en relation classée sans suite la **rouvre**. Un match déjà plus avancé
> (`MCNV`, `MVST`, `MNGT`, `MOFF`, `MOFA`) n'est **jamais** régressé.
>
> Voir [Étapes du match](https://developers.avest.fr/endpoints/get-match.md).

## Notes importantes

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

2. **Allocation automatique** : Sans `agencyId`/`userId`, le système alloue selon :
   * Priorité contact : le lead va d'abord au responsable de la fiche la plus récente du contact réellement travaillée par un collaborateur (créée, avancée ou annotée à la main), puis au responsable du contact, sauf s'il ne le détient que par des fiches automatiques jamais touchées
   * Zones de recherche (`areas`)
   * Shifts configurés
   * Allocation par défaut/random

3. **Matching** : Le match est créé uniquement si la vente est trouvée. En cas d'échec, l'acquisition est quand même créée (tracé dans les steps).

4. **Steps** : Si `settings.step` n'est pas fourni, l'étape est calculée automatiquement selon le `project`. Sans owner attribué, l'étape est forcée à `AQUL`.

5. **Areas** : Les zones de recherche sont utilisées pour l'allocation par zone et les alertes de matching automatique.

6. **Identifiant externe** : `parsingCustomId` est enregistré sur la fiche et renvoyé en lecture, mais il ne sert pas au dédoublonnage. Pour mettre à jour une acquisition déjà créée, conservez l'`id` renvoyé à la création et passez par [PATCH Acquisition](https://developers.avest.fr/endpoints/patch-acquisition.md).

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