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

# GET Transaction Search

> Recherche paginée de transactions (sale, acquisition, rental) avec leurs contacts associés.

Recherche paginée de transactions (`sale`, `acquisition`, `rental`) avec leurs contacts associés.

## Endpoint

**URL** : `/external-integration/{transaction}/search`
**Méthode** : `GET`
**Authentification** : Requiert un token LinkedAPI avec scope `externalIntegration` (GET).
**Clé requise** : toutes les clés (lecture seule suffit). Voir [Types de clé](https://avest.mintlify.site/guides/authentification.md).

`{transaction}` ∈ `sale` | `acquisition` | `rental`.

## Headers

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

## Query Parameters

| Paramètre | Type | Requis | Description |
| - | - | - | - |
| `search` | String | ❌ | Texte libre. **Minimum 3 caractères**. Recherche sur nom / téléphone / email / adresse / customId. Le n° de mandat (`mandate.referenceNumber`) n'est **pas** indexé pour l'instant — passer par GET `/external-integration/sale?customId=...` si vous avez le customId métier. |
| `page` | Integer | ❌ | Page 1-indexée. Défaut `1`. Max `100` |
| `sortField` | String | ❌ | Tri. Valeurs autorisées : `createdAt`, `updatedAt`, `stepUpdatedAt`. Défaut `createdAt` |
| `sortOrder` | String | ❌ | `asc` ou `desc`. Défaut `desc`. S'envoie avec `sortField` : seul, il est refusé (`400 Invalid sortField`). |
| `step` | String | ❌ | Filtre sur l'étape. Valeurs autorisées **selon le type** (voir ci-dessous). Répétable (`?step=MND&step=OFR`) → résultats dans l'une des étapes. |
| `owner` | ObjectId | ❌ | Filtre sur l'utilisateur Avest responsable du dossier. Répétable. |
| `tags` | ObjectId | ❌ | Filtre sur un tag de la fiche. **`acquisition` et `rental` uniquement** (non supporté sur `sale`). Répétable. |

> [!WARNING]
>
> **Aucun autre paramètre** n'est accepté. Toute clé non listée (ou un filtre non
> supporté pour le type, ex. `tags` sur `sale`) → `400`. Si `search` est fourni
> sans `sortField`, les résultats sont triés par pertinence (pas par
> `createdAt`).

Les filtres se combinent avec `search` et entre eux (logique « ET »). Un filtre répété (ex. plusieurs `step`) applique une logique « OU » sur ce filtre.

> [!TIP]
>
> **Synchronisation incrémentale.** Chaque résultat porte `updatedAt` et
> `stepUpdatedAt`. Triez par `sortField=updatedAt&sortOrder=desc` et arrêtez de
> paginer dès que `updatedAt` passe sous la date de votre dernier passage : vous
> ne rapatriez que ce qui a changé, au lieu de tout repomper à chaque cycle.

### Valeurs autorisées pour `step`

| Type | Valeurs |
| - | - |
| `sale` | `STK`, `TRN`, `ARC`, `PQUL`, `QUL`, `CNV`, `RDV`, `DLV`, `MND`, `TARC`, `OFR`, `AGT`, `MTG`, `SLD` |
| `acquisition` | `AQUL`, `ASRC`, `ANGT`, `AOFR`, `ACLS`, `AARC` |
| `rental` | `RQUL`, `RCNV`, `RRDV`, `RDLV`, `RMDT`, `RARC`, `RMAR`, `RRTD`, `RRTM` |

## Pagination

* Taille de page fixe : **100 documents**.
* Pas de `total` retourné. Itérez jusqu'à `hasMore: false`.
* `page` max : **100** (= 10 000 documents cumulés). Au-delà, raffiner via `search`.
* Le champ de taille de page de la réponse s'appelle ici **`limit`** — mais **`pageSize`** sur [GET Activities](https://avest.mintlify.site/endpoints/get-activities.md) et [GET Ad Search](https://avest.mintlify.site/endpoints/get-ad-search.md). Même sens, deux noms : lisez celui de la route que vous appelez.

## Clé de réponse selon le type

La clé contenant les résultats varie selon `{transaction}` :

| Endpoint | Clé de réponse |
| - | - |
| `/external-integration/sale/search` | `sales` |
| `/external-integration/acquisition/search` | `acquisitions` |
| `/external-integration/rental/search` | `rentals` |

## Exemples de requête

```bash theme={null}
GET /external-integration/sale/search?search=dupont&page=1
Authorization: Bearer your-linked-api-token
```

```bash theme={null}
GET /external-integration/acquisition/search?search=lyon+3&page=1
Authorization: Bearer your-linked-api-token
```

```bash theme={null}
GET /external-integration/rental/search?page=2&sortField=updatedAt&sortOrder=desc
Authorization: Bearer your-linked-api-token
```

```bash theme={null}
GET /external-integration/sale/search?step=MND&owner=6939530d9200187f19a2707d
Authorization: Bearer your-linked-api-token
```

```bash theme={null}
GET /external-integration/acquisition/search?search=lyon&step=AQUL&step=ASRC&tags=66cc8a8e75c9fac35c6ecd99
Authorization: Bearer your-linked-api-token
```

## Réponse de succès

**Code** : `200`

> [!WARNING]
>
> **Champs absents vs `null`** : les champs non renseignés sur la fiche ne sont
> **pas** retournés (pas même à `null`). Côté client, traiter chaque champ comme
> optionnel sauf indication contraire. Le détail exhaustif des champs
> `property`, `mandate`, etc. est dans [GET Sale](https://avest.mintlify.site/endpoints/get-sale.md).

### Sale

```json theme={null}
{
  "success": true,
  "sales": [
    {
      "id": "6a044cba8db14b3fbd015208",
      "customId": "BCOU2162",
      "agency": "66cc91d475c9fac35c86ed80",
      "agencyGroup": "66cc8a8e75c9fac35c6ecd73",
      "step": "MND",
      "status": "awaitingLaunch",
      "project": "B",
      "property": {
        "mainType": "apartment",
        "developmentType": "old",
        "size": 65,
        "floor": 3,
        "isCollectiveOwnership": true,
        "addressData": {
          "streetNumber": "3",
          "route": "Avenue Reille",
          "postalCode": "75014",
          "city": "Paris",
          "country": "France",
          "countryCode": "FR",
          "formattedAddress": "3 Av. Reille, 75014 Paris, France"
        }
      },
      "mandate": {
        "price": 252000,
        "sellPrice": 240000,
        "agencyCommission": 12000,
        "type": "notExclusive",
        "referenceNumber": "1729",
        "feeResponsibility": "seller",
        "commissionPercentage": 4.76,
        "commissionType": "value",
        "mandateDuration": 3,
        "maxMandateDuration": 12
      },
      "timeline": { "mandateSignatureDate": "2026-05-13T14:59:03.596Z" },
      "owner": {
        "id": "6939530d9200187f19a2707d",
        "firstName": "Florian",
        "lastName": "PUJO",
        "picture": "https://cdn.avest.fr/attachment/user/696e2f1adff893e4465d15b3"
      },
      "mainContact": "6a044cadd494814278d1fb84",
      "contacts": [
        {
          "id": "6a044cadd494814278d1fb84",
          "firstName": "Olivier",
          "lastName": "BOYER",
          "title": "mr",
          "isIndividual": true,
          "contactDetails": [
            { "type": "email", "data": "olivier.boyer@example.fr" },
            { "type": "phone", "data": "+33660598726" }
          ]
        }
      ],
      "createdAt": "2026-05-13T10:04:42.139Z",
      "updatedAt": "2026-05-14T09:12:30.004Z",
      "stepUpdatedAt": "2026-05-13T14:59:03.596Z"
    }
  ],
  "page": 1,
  "limit": 100,
  "hasMore": true
}
```

### Acquisition

```json theme={null}
{
  "success": true,
  "acquisitions": [
    {
      "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" }
      ],
      "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" }
          ]
        }
      ],
      "createdAt": "2026-05-13T16:02:54.888Z",
      "updatedAt": "2026-05-15T11:40:02.117Z",
      "stepUpdatedAt": "2026-05-14T08:03:11.902Z"
    }
  ],
  "page": 1,
  "limit": 100,
  "hasMore": true
}
```

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

### Rental

```json theme={null}
{
  "success": true,
  "rentals": [
    {
      "id": "69fcb723ac44aa882a150bbc",
      "customId": "REBZJ7515",
      "agency": "6937f7389200187f198aaa07",
      "agencyGroup": "66cc8a8e75c9fac35c6ecd73",
      "step": "RQUL",
      "project": "OTR",
      "type": "longTerm",
      "property": {
        "mainType": "apartment",
        "developmentType": "old",
        "size": 24.79,
        "floor": 2,
        "rooms": 2,
        "bedrooms": 1,
        "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"
        }
      },
      "owner": {
        "id": "693fd8823b8b4059ba4ea468",
        "firstName": "Imogen",
        "lastName": "RUSSEL"
      },
      "mainContact": "694a6a2fbe34c245521ce681",
      "contacts": [
        {
          "id": "694a6a2fbe34c245521ce681",
          "firstName": "Raphael",
          "lastName": "LORENZI",
          "isIndividual": true,
          "contactDetails": [
            { "type": "email", "data": "raph.lorenzi@example.fr" }
          ]
        }
      ],
      "createdAt": "2026-05-07T16:00:35.683Z",
      "updatedAt": "2026-05-09T07:21:44.658Z",
      "stepUpdatedAt": "2026-05-08T15:12:09.330Z"
    }
  ],
  "page": 1,
  "limit": 100,
  "hasMore": true
}
```

### Aucun résultat

```json theme={null}
{
  "success": true,
  "sales": [],
  "page": 1,
  "limit": 100,
  "hasMore": false
}
```

(La clé varie selon le type : `sales` / `acquisitions` / `rentals`.)

## Réponses d'erreur

* **`search` \< 3 caractères** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationSearchTransaction : search must be at least 3 characters"
}
```

* **Paramètre inconnu** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationSearchTransaction : Unsupported query parameter: foo"
}
```

* **`sortField` invalide** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationSearchTransaction : Invalid sortField. Allowed: createdAt, updatedAt, stepUpdatedAt"
}
```

* **`page` invalide ou hors limites** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationSearchTransaction : page must be <= 100"
}
```

* **`step` invalide pour le type** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationSearchTransaction : Invalid step. Allowed: AQUL, ASRC, ANGT, AOFR, ACLS, AARC"
}
```

* **`owner` / `tags` non ObjectId valide** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationSearchTransaction : owner must be a valid ObjectId"
}
```

* **Filtre non supporté pour le type** (ex. `tags` sur `sale`) : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationSearchTransaction : Unsupported query parameter: tags"
}
```

* **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

1. Les résultats sont limités à votre périmètre autorisé. Une fiche hors périmètre n'apparaîtra jamais dans la réponse.
2. Recherche minimum 3 caractères. Les mots vides FR (`de`, `la`, `le`...) ne sont pas pris en compte.
3. Lorsque `search` est fourni sans `sortField`, l'ordre par défaut est la pertinence. Pour un ordre déterministe, passer `sortField` explicitement.
4. Les contacts inclus reflètent l'état au moment de la dernière mise à jour de la transaction.
5. Endpoint en lecture seule.

## Rate limits

Chaque route est limitée à **200 req / minute par groupe d'agences** (un compteur par groupe d'agences × route : `sale/search`, `acquisition/search` et `rental/search` ont chacun leur propre compteur).

* Headers : `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` (secondes).
* Dépassement → `429 Too Many Requests` :

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


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