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

> Récupère une annonce par son id ou sa référence, avec contact, localisation et médias.

Récupère une annonce (publication d'un bien) par son `id` MongoDB ou sa `reference` métier, avec le contact rattaché, la localisation et les médias.

## Endpoint

**URL** : `/external-integration/ad`
**Méthode** : `GET`
**Authentification** : Requiert un token LinkedAPI avec scope `externalIntegration` et une clé rattachée à un groupe d'agences.
**Clé requise** : toutes les clés (lecture seule suffit). Voir [Types de clé](https://developers.avest.fr/guides/authentification.md).

## Headers

```
Authorization: Bearer {token}
```

## Query Parameters

Exactement **un** des deux paramètres suivants doit être fourni :

| Paramètre | Type | Description |
| - | - | - |
| `id` | ObjectId | Identifiant Mongo de l'annonce. |
| `reference` | String | Référence métier de l'annonce. |

> [!WARNING]
>
> `id` et `reference` sont **mutuellement exclusifs**. Zéro ou plus d'un →
> `400`.

## Exemples de requête

```bash theme={null}
GET /external-integration/ad?id=6a044cba8db14b3fbd015208
Authorization: Bearer your-linked-api-token
```

```bash theme={null}
GET /external-integration/ad?reference=REF-2025-001
Authorization: Bearer your-linked-api-token
```

## Réponse de succès

**Code** : `200`

### Annonce trouvée

```json theme={null}
{
  "success": true,
  "ad": {
    "id": "6a044cba8db14b3fbd015208",
    "reference": "REF-2025-001",
    "status": "online",
    "adType": "sale",
    "adSaleType": "classic",
    "title": "Bel appartement 3 pièces - Paris 14e",
    "description": "Appartement lumineux au 3e étage avec ascenseur...",
    "propertyType": "residential",
    "propertyHousingType": "apartment",
    "propertyCommercialType": null,
    "surface": 65,
    "mandateNumber": "1729",
    "mandateType": "exclusive",
    "isPriceDisplayed": true,
    "salePrice": 252000,
    "buyerSaleFee": 12000,
    "sellerSaleFee": 0,
    "contact": {
      "firstName": "Olivier",
      "lastName": "BOYER",
      "email": "olivier.boyer@example.fr",
      "phone": "+33660598726"
    },
    "location": {
      "number": "3",
      "route": "Avenue Reille",
      "postalCode": "75014",
      "city": "Paris",
      "country": "France",
      "isLocationDisplayed": true
    },
    "pictures": [
      "https://d1234.cloudfront.net/ad/6a044cba8db14b3fbd015208/photo-1.jpg",
      "https://d1234.cloudfront.net/ad/6a044cba8db14b3fbd015208/photo-2.jpg"
    ],
    "urlAgencyAd": "https://agence.example.fr/annonce/REF-2025-001",
    "urlVirtualVisit": "https://my.matterport.com/show/?m=abc123",
    "urlVideo": "https://youtu.be/abc123",
    "urlOtherMedia": "https://drive.example.fr/dossier",
    "transactionType": "sale",
    "transactionModel": "Sale",
    "transactionStep": "MND",
    "owner": "6939530d9200187f19a2707d",
    "firstPublicationDate": "2026-05-13T10:04:42.139Z",
    "lastPublicationDate": "2026-05-20T08:00:00.000Z",
    "createdAt": "2026-05-13T10:04:42.139Z"
  }
}
```

### Annonce non trouvée ou hors scope

```json theme={null}
{
  "success": true,
  "ad": null
}
```

## Champs de la réponse

| Champ | Type | Description |
| - | - | - |
| `id` | String | ObjectId Mongo de l'annonce. |
| `reference` | String | Référence métier de l'annonce. |
| `status` | String | Statut de publication (`online`, `offline`, `archived`). |
| `adType` | String | Type d'annonce. |
| `adSaleType` | String | Sous-type de vente. |
| `title` | String | Titre de l'annonce. |
| `description` | String | Description de l'annonce. |
| `propertyType` | String | Type de bien. |
| `propertyHousingType` | String | Type de logement. |
| `propertyCommercialType` | String | Type de bien commercial. |
| `surface` | Number | Surface (m²). |
| `mandateNumber` | String | Numéro de mandat. |
| `mandateType` | String | Type de mandat. |
| `isPriceDisplayed` | Boolean | Le prix est affiché publiquement. |
| `salePrice` | Number | Prix de vente. |
| `buyerSaleFee` | Number | Honoraires à charge acquéreur. |
| `sellerSaleFee` | Number | Honoraires à charge vendeur. |
| `rentalNetMonthlyRent` | Number | Loyer net mensuel (location). |
| `rentalMonthlyMaintenanceCost` | Number | Charges mensuelles (location). |
| `rentalFee` | Number | Honoraires de location. |
| `rentalDeposit` | Number | Dépôt de garantie (location). |
| `contact` | Object | Contact rattaché : `{ firstName, lastName, email, phone }`. |
| `location` | Object | Localisation (voir ci-dessous). |
| `pictures` | Array | URLs CloudFront publiques des photos. |
| `urlAgencyAd` | String | URL de l'annonce sur le site de l'agence. |
| `urlVirtualVisit` | String | URL de la visite virtuelle. |
| `urlVideo` | String | URL de la vidéo. |
| `urlOtherMedia` | String | URL d'autres médias. |
| `transactionType` | String | Type de transaction source (`sale`, `rental`). |
| `transactionModel` | String | Modèle de la transaction source (`Sale`, `Rental`). |
| `transactionStep` | String | Étape de la transaction source. |
| `owner` | String | ObjectId de l'utilisateur responsable. |
| `firstPublicationDate` | ISO 8601 | Date de première publication. |
| `lastPublicationDate` | ISO 8601 | Date de dernière publication. |
| `createdAt` | ISO 8601 | Date de création. |

### `location`

| Champ | Description |
| - | - |
| `number` | Numéro de rue. Présent uniquement si `isLocationDisplayed` vaut `true`. |
| `route` | Voie. Présent uniquement si `isLocationDisplayed` vaut `true`. |
| `postalCode` | Code postal. |
| `city` | Ville. |
| `country` | Pays. |
| `isLocationDisplayed` | Indique si l'adresse précise (numéro + voie) est affichée publiquement. |

> [!NOTE]
>
> Les champs non renseignés sont absents de la réponse (pas retournés à `null`).
> Quand `isLocationDisplayed` vaut `false`, `number` et `route` ne sont pas
> exposés.

## Réponses d'erreur

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

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

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

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

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

1. **Scope** : une annonce hors de votre périmètre autorisé ne sera jamais retournée (`ad: null`).
2. **Médias** : les `pictures` sont des URLs CloudFront publiques (pas de lien signé temporaire).
3. **Localisation** : `number` et `route` ne sont exposés que si `isLocationDisplayed` vaut `true`.
4. **Champs location/honoraires** : les champs de location (`rental*`) ne sont renseignés que pour les annonces de location ; les champs de vente (`sale*`) pour les annonces de vente.
5. Endpoint en lecture seule.

## Rate limits

Cette route est limitée à **500 req / minute par groupe d'agences** (bucket dédié).

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

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