Stream Estate Documentation

Breaking changes entre la v1 (docs.stream.estate) et la v2 (https://api-v2.stream.estate).

Cette migration change la plupart des URLs, le format de recherche (querystring → body structuré), renomme Search en Alert, et introduit un vrai système de destinations (EventDestination). Prévoyez une refonte du client.

TL;DR

Base URL — api-v2.stream.estate
Auth — même en-tête X-API-Key, mais nouvelle clé à générer (les clés v1 ne fonctionnent pas en v2)
Recherche — GET /documents/properties?... → POST /properties avec body JSON (modes classic / advanced, pagination page / cursor)
Renommage — Search → Alert (+ AlertEvents dédiés)
Webhooks — système complet via EventDestination + signingKey + EventNotification (journal de livraison)
Indicateurs — /cities remplacé par /geo/administrative-divisions ; de nouveaux endpoints d'estimation (prix au m², POI, comparables) arrivent pour remplacer les anciens /indicators/*

Table de correspondance des endpoints

Propriétés

v1	v2	Commentaire
`GET /documents/properties` (70+ params querystring)	`POST /properties` (body JSON, mode `classic` ou `advanced`)	Voir Filtrage
`GET /documents/properties/{id}`	`GET /properties/{uuid}`	Path simplifié
`GET /documents/properties/{id}/similar-properties`	🆕 Nouveaux endpoints d'estimation à venir
—	`GET /properties/search-by-url?url=…`	Nouveau : retrouver une property depuis une URL d'annonce

Searches → Alerts

v1	v2	Commentaire
`GET /searches`	`GET /alerts`
`GET /searches/{id}`	`GET /alerts/{uuid}`
`POST /searches`	`POST /alerts`	Body remanié, `searchMode: CLASSIC \| ADVANCED`
`PUT /searches/{id}`	`PUT /alerts/{uuid}`
`DELETE /searches/{id}`	`DELETE /alerts/{uuid}`
(N/A)	`GET /alerts/{alertUuid}/events`	Historique des matches
(N/A)	`GET /alerts/{alertUuid}/events/{uuid}`	Détail d'un event

Webhooks & notifications

v1	v2	Commentaire
URL webhook dans le Search	`EventDestination` (CRUD sur `/account/event-destinations`) + `signingKey` HMAC	Destinations réutilisables entre alertes
`GET /webhook-tester`	→ intégré à `EventDestination` + `EventNotification`	Plus besoin d'endpoint dédié
Événements `ad.update.`, `property.ad.`	Nouveaux types: `NEW_MATCH`, `ADDITIONAL_LISTING`, `PRICE_CHANGED`, `ANY_ATTRIBUTE_CHANGED`, `LISTING_EXPIRED`	Voir Alert
(N/A)	`GET /event-notifications`	Journal complet des tentatives de livraison
(N/A)	`POST /account/webhook-signing-key/rotate`	Rotation de la clé de signature
(N/A)	`POST /account/event-destinations/{uuid}/reactivate`	Reprise après circuit breaker

Cities / Géo

v1	v2	Commentaire
`GET /cities`	`GET /geo/administrative-divisions/{uuid}` (lookup par UUID)	Pas de collection pour l'instant
`GET /public/location-autocomplete`	`GET /geo/autocomplete`

Indicateurs & divers

v1	v2	Commentaire
`GET /indicators/points_of_interest`	🆕 Nouveaux endpoints d'estimation à venir
`GET /indicators/price_per_meter`	🆕 Nouveaux endpoints d'estimation à venir

Nouveautés v2

Endpoint	Description
`GET /account/api-usage`	Quotas et usage consommés
`GET /analytics/listings`	Statistiques agrégées sur les listings
`GET/POST /favorite-properties`	Favoris (CRUD, path kebab-case)
`GET /event-notifications[/{uuid}]`	Journal de livraison des notifications

Changements de modèle

Property

En v1, PropertyDocument contient adverts[] inlined avec tous les détails. En v2, Property est plus légère :

{
  "uuid": "...",
  "listings": [/* ListingSearchResultDTO[] */],
  "minPrice": 280000,
  "maxPrice": 310000,
  "createdAt": "...",
  "updatedAt": "..."
}

Les détails (surface, rooms, photos, features) vivent sur les listings.

Alert (ex-Search)

Body remanié :

{
  "name": "...",
  "active": true,
  "searchMode": "CLASSIC",
  "criteria": { /* CriteriaNodeDTO récursif */ },
  "notificationConfig": {
    "rules": [
      { "eventType": "NEW_MATCH", "enabled": true },
      { "eventType": "PRICE_CHANGED", "thresholdPercentage": 5, "thresholdDirection": "DECREASE", "enabled": true }
    ]
  },
  "destinationWebhookUrl": "https://your.app/hook",
  "destinationEmail": null
}

La réponse POST renvoie un signingKey HMAC une seule fois — conservez-le.

Format de réponse

v1	v2
Collection classique	JSON (`application/json`) ou JSON:API (`application/vnd.api+json`) via `Accept`
Pagination query `?page=N`	`POST /properties` avec `paginationType: "page" \| "cursor"` (voir Pagination)

Checklist de migration

🔑 Générer une nouvelle clé API v2 (les clés v1 sont incompatibles) et l'envoyer dans X-API-Key
🔄 Remplacer GET /documents/properties?... par POST /properties avec body JSON et searchMode: "CLASSIC"
🔄 Adapter la pagination (choisir page ou cursor via paginationType)
🔄 Renommer Search* → Alert* dans le code client
🔄 Créer des EventDestination explicites (CRUD sur /account/event-destinations) plutôt que de passer l'URL webhook sur chaque Search
🔐 Stocker signingKey renvoyé par POST (alert ou event-destination) et vérifier la signature HMAC côté réception
🔄 Migrer les consumers de PropertyDocument.adverts[] vers Property.listings[]
🔄 Remplacer les noms d'événements v1 par les enums v2 (NEW_MATCH, ADDITIONAL_LISTING, PRICE_CHANGED, ANY_ATTRIBUTE_CHANGED, LISTING_EXPIRED)
⚠️ Retirer temporairement les appels à /indicators/* — une nouvelle suite d'endpoints dédiée à l'estimation arrive
✨ Optionnellement intégrer /event-notifications (journal de livraison) et /analytics/listings

Migration v1 → v2