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

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

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

## Endpoint

**URL** : `/external-integration/acquisition`
**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 l'acquisition (24 chars hex) |
| `customId` | String | ✅\* ou ✅ | Identifiant métier (ex: `A-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/acquisition?customId=A-2025-001
Authorization: Bearer your-linked-api-token
```

```bash theme={null}
GET /external-integration/acquisition?id=619b46b47e043165f206db1c
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 acquisition 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 l'acquisition est exposé via `acquisition.mainContact` (ID), le détail complet du contact est dans la clé `contacts` au top-level.

## Réponse de succès

**Code** : `200`

### Acquisition trouvée

```json theme={null}
{
  "success": true,
  "acquisition": {
    "id": "6a04a0aed4948142783f8cdf",
    "customId": "AABZJ7515",
    "agency": "66cc92295f84c9b212dab7ef",
    "agencyGroup": "66cc8a8e75c9fac35c6ecd73",
    "step": "AQUL",
    "project": "buyer",
    "activityLevel": "hot",
    "propertiesTypes": ["apartment"],
    "priceRange": { "high": 197000 },
    "sizeRange": { "low": 51 },
    "roomRange": { "low": 2 },
    "purpose": "secondaryResidence",
    "areas": [
      { "type": "postalCode", "postalCode": "31000", "countryCode": "FR" },
      { "type": "postalCode", "postalCode": "31400", "countryCode": "FR" }
    ],
    "createdAt": "2026-05-13T16:02:54.888Z",
    "owner": null,
    "mainContact": "6a04a0acd4948142783f8909"
  },
  "contacts": [
    {
      "id": "6a04a0acd4948142783f8909",
      "firstName": "Yannick",
      "lastName": "BERGOUGNOUX",
      "isIndividual": true,
      "contactDetails": [
        { "type": "phone", "data": "+33670567683" },
        { "type": "email", "data": "yan.bergou@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.

### Acquisition non trouvée ou hors scope

```json theme={null}
{
  "success": true,
  "acquisition": 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 `acquisition`

Toujours présents (si l'acquisition existe) :

| Champ | Type | Description |
| - | - | - |
| `id` | String | ObjectId Mongo de l'acquisition |
| `customId` | String | Identifiant métier (ex: `AABZJ7515`) |
| `agency` | String | ObjectId de l'agence propriétaire |
| `agencyGroup` | String | ObjectId du groupe d'agences |
| `step` | String | Étape courante : `AQUL` (à qualifier), `ASRC` (en recherche), `ANGT` (en négociation), `AOFR` (offre acceptée), `ACLS` (achat signé), `AARC` (archivée) |
| `createdAt` | ISO 8601 | Date de création |
| `owner` | Object \| null | Utilisateur Avest responsable du dossier (`id`, `firstName`, `lastName`, `picture` optionnelle) |
| `mainContact` | String \| null | ObjectId de l'acquéreur 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 |
| - | - | - |
| `project` | String | Projet (`buyer`, `buyerSeller`, `buyerOwner`, ...) |
| `activityLevel` | String | Niveau d'activité (`hot`, `warm`, `cold`, `mandate`) |
| `propertiesTypes` | `Array<String>` | Types de biens recherchés (`apartment`, `house`, `field`, ...) |
| `areas` | `Array<Object>` | Zones recherchées (voir section dédiée) |
| `priceRange` | `{ low?, high? }` | Fourchette budget |
| `sizeRange` | `{ low?, high? }` | Fourchette surface (m²) |
| `roomRange` | `{ low?, high? }` | Nombre de pièces souhaité |
| `bedroomRange` | `{ low?, high? }` | Nombre de chambres souhaité |
| `floorRange` | `{ low?, high? }` | Étage souhaité |
| `fieldRange` | `{ low?, high? }` | Surface terrain (terrain / maison) |
| `elevator` | String | Ascenseur (`unnecessary`, `preferable`, `essential`, `excluded`). Mêmes valeurs pour les critères suivants. |
| `outdoor` | String | Extérieur : jardin, terrasse, balcon, loggia, piscine ou toit-terrasse. |
| `parking` | String | Parking |
| `pool` | String | Piscine |
| `lastFloor` | String | Dernier étage |
| `groundFloor` | String | Rez-de-chaussée |
| `singleStorey` | String | Plain-pied |
| `bikeShed` | Boolean | Local vélo |
| `mortgageType` | String | Type de financement (`relay`, `standard`, `none`) |
| `mortgage` | Boolean | Crédit en cours |
| `purpose` | String | Usage prévu (`primaryResidence`, `secondaryResidence`, `businessPremise`, `investment`, `propertyTrade`) |
| `mandate` | Object | Mandat de recherche (si signé) |
| `parsingCustomId` | String | Identifiant interne d'import |

### `areas`

Chaque area peut contenir :

| Champ | Description |
| - | - |
| `type` | `postalCode`, `inseeCode`, `departmentCode`, `geometry` |
| `postalCode` | Code postal (si `type === 'postalCode'`) |
| `inseeCode` | Code INSEE (si `type === 'inseeCode'`) |
| `countryCode` | Code pays ISO 3166-1 alpha-2 |
| `geometry` | Polygone GeoJSON (si `type === 'geometry'`) |
| `center` | Centre d'une zone tracée en cercle dans Avest, GeoJSON `Point` (si `type === 'geometry'`) |
| `radius` | Rayon de ce cercle, en km |
| `addresses` | Array d'adresses contextuelles (peut être vide) |

### `contacts` (top-level)

Liste des contacts liés à l'acquisition. Le **premier élément** correspond au `mainContact` au top-level (= acquéreur principal). Mêmes champs que pour les autres routes externes :

| Champ | Description |
| - | - |
| `id` | ObjectId du contact |
| `firstName`, `lastName` | Si `isIndividual: true` |
| `commercialName`, `corporateName` | Si entreprise |
| `title` | `mr` / `mme` |
| `isIndividual` | `true` (particulier) ou `false` (entreprise) |
| `contactDetails[]` | Array de `{ type: 'email' \| 'phone', data: string }` |

## 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/zone de recherche 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 l'acquéreur** : pour récupérer les coordonnées de l'acquéreur 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.