Principes REST appliqués à l'immobilier
- Chaque ressource a une URL canonique : /v1/properties, /v1/properties/{id}.
- Les verbes HTTP expriment l'intention : GET, POST, PATCH, DELETE.
- Les statuts HTTP signalent le résultat : 200, 201, 400, 401, 404, 429, 500.
- JSON est le format pivot, UTF-8 obligatoire.
- Idempotence garantie sur GET, PUT, DELETE.
Endpoints principaux
| Endpoint | Méthode | Rôle |
|---|---|---|
| /v1/properties | GET | Lister les biens |
| /v1/properties/{id} | GET | Détail d'un bien |
| /v1/properties/{id}/medias | GET | Photos et plans |
| /v1/agencies | GET | Liste des agences |
| /v1/leads | POST | Envoyer un lead |
| /v1/webhooks | POST | Configurer un webhook |
Authentification
L'API Ts-Immo accepte deux modes : clé API en Bearer token (le plus simple), et OAuth2 client credentials pour les intégrations partenaires. La clé API se gère depuis app.ts-immo.org et peut être rotée à tout moment.
Exemple de requête curl
curl -X GET 'https://api.ts-immo.org/v1/properties?city=Lyon&limit=20' \
-H 'Authorization: Bearer ts_live_a1b2c3d4e5f6...' \
-H 'Accept: application/json'Filtrage
Les paramètres de query supportés couvrent les critères usuels de recherche immobilière.
- city, postal_code, department.
- transaction_type : sale, rent, vacation.
- property_type : apartment, house, land, commercial.
- min_price, max_price, min_surface, max_surface.
- min_rooms, max_rooms.
- updated_since (timestamp ISO 8601).
Pagination
Deux modes : page+limit (simple, jusqu'à quelques centaines de résultats) et cursor (recommandé pour les exports complets).
Réponse paginée typique
{
"data": [ /* ... 20 biens ... */ ],
"meta": {
"total": 487,
"limit": 20,
"next_cursor": "eyJpZCI6InRzLTEyMzQ1In0",
"prev_cursor": null
}
}Gestion d'erreurs
Chaque erreur retourne un payload structuré avec un code lisible et un message. Les codes 4xx sont causés par le client, les 5xx par le serveur.
Format d'erreur standardisé
{
"error": {
"code": "invalid_filter",
"message": "Le filtre min_price doit être un nombre positif.",
"field": "min_price",
"request_id": "req_a1b2c3"
}
}Bonnes pratiques côté client
- Utiliser le filtre updated_since pour les synchronisations incrémentales.
- Implémenter un retry avec backoff exponentiel sur les 5xx et 429.
- Logger le request_id renvoyé pour les tickets support.
- Mettre en cache local les réponses qui ne changent pas (agencies, types de biens).