API REST Ts-Immo

Référence opérationnelle de l'API REST Ts-Immo : ressources disponibles, usages recommandés, filtres et exemples prêts à l'emploi.

URL de base

https://api.ts-immo.org/v1

Authentification

Chaque appel API doit inclure un token Bearer dans l'en-tête Authorization. Générez et gérez vos clés API depuis votre espace Ts-Immo.

# En-tête HTTP requis
Authorization: Bearer <votre-api-key>
Content-Type: application/json
Accept-Language: fr  # fr | en | de | it

Ne partagez jamais votre clé API. Utilisez des variables d'environnement et des secrets côté serveur uniquement.

Points de terminaison

Propriétés

GET/propertiesRetourne une liste paginée de biens, filtrable et triable

POST/propertiesCrée un nouveau bien immobilier avec ses champs métier

GET/properties/:idRetourne le détail complet d'un bien par identifiant

PUT/properties/:idRemplace entièrement une fiche bien existante

PATCH/properties/:idMet à jour uniquement les champs fournis

DELETE/properties/:idSupprime définitivement un bien et ses liens associés

Médias

GET/properties/:id/mediaListe les photos, vidéos et documents d'un bien

POST/properties/:id/mediaAjoute un média à un bien (photo, plan, document...)

DELETE/properties/:id/media/:mediaIdSupprime un média spécifique rattaché au bien

Agents

GET/agentsRetourne la liste des agents disponibles

GET/agents/:idRetourne les informations détaillées d'un agent

GET/agents/:id/propertiesListe les biens gérés par un agent donné

Synchronisation

POST/sync/runDémarre une synchronisation manuelle immédiate

GET/sync/statusRetourne l'état courant et la progression de synchro

GET/sync/logsExpose l'historique des exécutions de synchronisation

Webhooks

GET/webhooksListe les webhooks configurés pour votre compte

POST/webhooksEnregistre un nouveau webhook sortant

DELETE/webhooks/:idSupprime un webhook existant par identifiant

Paramètres de filtrage

Affinez les résultats de GET /properties avec ces paramètres de requête (combinables entre eux) :

GET /properties?type=sale&status=active&minPrice=100000&maxPrice=500000&city=Paris&bedrooms=3&page=1&limit=20&sort=price&order=asc

# Paramètres disponibles
type        string   sale | rent | seasonal | commercial | land
status      string   active | pending | sold | rented | withdrawn | draft
minPrice    number   Prix minimum
maxPrice    number   Prix maximum
city        string   Ville
postalCode  string   Code postal
bedrooms    number   Nombre de chambres (min)
bathrooms   number   Nombre de salles de bain (min)
page        number   Page (défaut: 1)
limit       number   Résultats par page (max: 100, défaut: 20)
sort        string   price | surface | createdAt | updatedAt
order       string   asc | desc

Exemples

Lister des propriétés

curl -X GET "https://api.ts-immo.org/v1/properties?type=sale&city=Paris&limit=5" \
  -H "Authorization: Bearer votre-api-key" \
  -H "Accept-Language: fr"

# Réponse
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Appartement 3 pièces Paris 11e",
      "type": "sale",
      "price": 385000,
      ...
    }
  ],
  "meta": {
    "total": 248,
    "page": 1,
    "perPage": 5,
    "totalPages": 50
  }
}

Créer une propriété

curl -X POST "https://api.ts-immo.org/v1/properties" \
  -H "Authorization: Bearer votre-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Maison 5 pièces avec jardin",
    "type": "sale",
    "status": "active",
    "price": 650000,
    "currency": "EUR",
    "surface": 145,
    "bedrooms": 4,
    "bathrooms": 2,
    "address": {
      "street": "8 allée des Roses",
      "city": "Lyon",
      "postalCode": "69006",
      "country": "FR"
    }
  }'

Codes d'erreur

En cas d'échec, l'API retourne une erreur JSON normalisée avec un code HTTP, un code métier et des détails exploitables.

# Format d'erreur standard
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Property not found",
    "details": null
  }
}

# Codes HTTP
200  OK              Succès
201  Created         Ressource créée
400  Bad Request     Données invalides
401  Unauthorized    Clé API manquante ou invalide
403  Forbidden       Accès refusé
404  Not Found       Ressource introuvable
409  Conflict        Conflit (doublon)
422  Unprocessable   Validation échouée
429  Too Many Req.   Rate limit dépassé (100 req/min)
500  Server Error    Erreur interne

La limite est de 100 requêtes/minute par clé API. Surveillez X-RateLimit-Remaining et X-RateLimit-Reset pour lisser votre charge et éviter les 429.