API REST Ts-Immo

URL de base

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

Tous les endpoints de l'API Client sont servis sous le préfixe /v1/gateway/. Les réponses sont au format JSON, les identifiants sont des UUID v4 et les dates suivent le format ISO 8601.

Authentification

Chaque appel doit porter un token actif. L'API Client accepte indifféremment un bearer OAuth2 (flux utilisateur) ou un API Token (usage programmatique, ex. le plugin WordPress).

# OAuth2 Bearer (user flow)
Authorization: Bearer <access_token>

# API Token (programmatic, e.g. WordPress plugin)
Authorization: Bearer <api_token>
# or:
X-TS-IMMO-KEY: <api_token>

Les deux formats sont introspectés par ts-identity. Aucune contrainte de scope n'est imposée : tout token actif est accepté. Le filtrage des ressources s'appuie sur les item_ids et le client_id portés par le token — une requête dont le token ne porte aucun item_id ne matche aucune annonce.

Conventions

Tous les noms de champs JSON (requêtes et réponses) sont en snake_case. Les paramètres de requête (query) restent en camelCase (ex. ?crmReference=…, ?gatewayId=…). Les champs null sont omis des réponses. Les dates sont en ISO 8601 (ex. 2026-01-15T10:00:00Z).

Endpoints

Détail des endpoints clés

Les endpoints les plus utilisés sont détaillés ci-dessous avec leurs paramètres, corps de requête et exemples de réponse.

POST/v1/gateway/gateways

Crée une passerelle pour le client authentifié. L'item_id fourni doit faire partie des item_ids du token. Le plan est automatiquement extrait du token.

Corps de la requête

{
  "item_id": "item-123",
  "name": "Apimo -> WordPress",
  "market": "fr",
  "category": "professional",
  "mode": "PROD",
  "input_connector": {
    "connector_type": "APIMO",
    "connector_id": "770e8400-e29b-41d4-a716-446655440000",
    "config": { "api_key": "apimo-api-key", "provider": "12345" }
  },
  "output_connectors": [
    {
      "connector_type": "TS_SYNC",
      "connector_id": "880e8400-e29b-41d4-a716-446655440000",
      "config": {
        "url": "https://www.your-agency.com",
        "plugin_auth_key": "your-plugin-auth-key"
      }
    }
  ]
}

Réponse 201 Created — la passerelle créée et un API Token généré pour usage programmatique (ex. plugin WordPress), nullable :

{
  "gateway": { "id": "660e8400-...", "item_id": "item-123", "status": "DRAFT", "...": "..." },
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...."
}

POST/v1/gateway/gateways/{id}/sync-jobs

Crée et démarre immédiatement un job de synchronisation. La passerelle doit être en statut ACTIVE.

# Full sync
curl -X POST "https://api.ts-immo.org/v1/gateway/gateways/GATEWAY_ID/sync-jobs" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Single-property sync
curl -X POST "https://api.ts-immo.org/v1/gateway/gateways/GATEWAY_ID/sync-jobs?crmReference=REF-12345" \
  -H "X-TS-IMMO-KEY: your-api-token"

GET/v1/gateway/properties

Retourne les annonces associées aux passerelles liées aux item_ids du token (y compris les passerelles déléguées). Aucun paramètre : le filtrage est automatique.

Réponse 200 OK — un tableau de TsImmoProperty (modèle immobilier normalisé, champs en snake_case, champs null omis) :

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "gateway_id": "660e8400-e29b-41d4-a716-446655440000",
    "stream_id": "770e8400-e29b-41d4-a716-446655440000",
    "crm_source": "apimo",
    "reference": "REF-12345",
    "crm_reference": "CRM-12345",
    "type": "apartment",
    "sub_type": "duplex",
    "offer_type": "sale",
    "status": "available",
    "title": { "fr": "Bel appartement 3 pièces", "en": "Beautiful 3-room apartment" },
    "description": { "fr": "Lumineux duplex traversant...", "en": "Bright through-duplex..." },
    "bedrooms": 2,
    "bathrooms": 1,
    "floor": "3",
    "orientation": "S",
    "financial": {
      "transaction": {
        "price": { "amount": 350000, "currency": "EUR" }
      }
    },
    "location": {
      "city": "Paris",
      "postal_code": "75001",
      "countryCode": "FR",
      "geo": { "latitude": 48.8566, "longitude": 2.3522 }
    },
    "sizes": {
      "liveable_area": { "size": 75.5, "unit": "sq_m" }
    },
    "images": [
      { "url": "https://cdn.example.com/photo1.jpg", "ordinal": 0 }
    ],
    "property_url": "https://www.your-agency.com/property/apartment-paris",
    "cover_thumbnail": "https://cdn.example.com/photo1-thumb.jpg",
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-15T10:00:00Z",
    "fetched_at": "2026-01-15T10:00:00Z"
  }
]

PUT/v1/gateway/properties/{id}/url

Callback utilisé par le plugin client pour renseigner l'URL de la page publiée d'un bien après synchronisation. Met à jour le champ property_url.

curl -X PUT "https://api.ts-immo.org/v1/gateway/properties/PROPERTY_ID/url" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://www.your-agency.com/property/apartment-t3-paris" }'

POST/v1/gateway/properties/search/ai

Recherche de biens en langage naturel. L'input est traité comme hostile : caractères de contrôle supprimés, longueur tronquée à 500, sortie du LLM validée contre une whitelist. Le filtre gateway_id est toujours forcé depuis le token.

curl -X POST "https://api.ts-immo.org/v1/gateway/properties/search/ai" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "query": "3-bedroom apartment near Lyon, max 500000 EUR, with a pool" }'

La réponse retourne les biens correspondants (max 50), le nombre total et le filtre MongoDB généré (pour transparence) :

{
  "results": [ { "id": "...", "type": "apartment", "offer_type": "sale", "...": "..." } ],
  "total_count": 5,
  "filter": {
    "type": "apartment",
    "bedrooms": { "$gte": 3 },
    "amenities": { "$all": ["pool"] },
    "financial.transaction.price.amount": { "$lte": 500000 }
  }
}

POST/v1/gateway/site/activate

Valide qu'au moins une passerelle du client possède un connecteur de sortie TS_SYNC dont l'URL correspond au domaine. Si trouvée, le plugin_auth_key est propagé et un enregistrement d'activation est créé.

Exemple de réponse :

{
  "success": true,
  "status": "activated",
  "domain": "https://your-site.com",
  "activated_at": "2026-03-26T10:00:00Z",
  "plan": "pro",
  "expires_at": "2027-03-26T00:00:00Z",
  "biens_max": 500
}

POST/v1/gateway/estimations

Émet une estimation de prix ancrée DVF. Le caller ne passe aucun identifiant de passerelle : elle est résolue depuis le token. Au moins (address | postal_code) ou (latitude, longitude) doit être fourni — l'adresse géocodée l'emporte sur les coordonnées.

{
  "property_type": "house",
  "offer_type": "sale",
  "liveable_area_sqm": 120,
  "address": "10 Rue de la République, 74300 Cluses",
  "postal_code": "74300",
  "construction_year": 1985,
  "epc_category": "B",
  "with_commentary": true
}

Réponse 200 OK — fourchette centrale / basse / haute, niveau de confiance, ajustements appliqués, comparables et (sur ESTIMATION_IA) un commentaire :

{
  "request_id": "8c1c0c5e-...",
  "offer_type": "sale",
  "central":   { "total": 415000, "price_per_sqm": 3458, "currency": "EUR" },
  "low_bound": { "total": 385000, "price_per_sqm": 3208, "currency": "EUR" },
  "high_bound":{ "total": 448000, "price_per_sqm": 3733, "currency": "EUR" },
  "confidence": { "level": "MEDIUM", "sample_size": 17, "final_radius_km": 1.5 },
  "adjustments": [ { "code": "DPE_A_B", "percent": 0.03 } ],
  "top_comparables": [ { "source": "DVF", "sold_price": 395000, "price_per_sqm": 3291 } ]
}

GET/v1/gateway/leads

Liste paginée des prospects capturés via le bloc lead des estimations, triés par date de création décroissante.

{
  "items": [
    {
      "id": "uuid",
      "first_name": "Marie",
      "last_name": "Dupont",
      "email": "marie.dupont@example.com",
      "project_timeframe_months": 6,
      "offer_type": "SALE",
      "property_type": "HOUSE",
      "estimated_central_total": 415000,
      "currency": "EUR",
      "created_at": "2026-05-02T23:14:58Z"
    }
  ],
  "page": 0,
  "size": 50,
  "total_elements": 87,
  "total_pages": 2
}

POST/v1/gateway/gateways/{id}/addons/{addonCode}

Achète l'addon pour la passerelle. Le prix est résolu côté serveur depuis le catalogue. Idempotent : si l'addon est déjà actif, le purchase existant est retourné. Réservé à l'owner ou au délégué FULL_ACCESS.

curl -X POST "https://api.ts-immo.org/v1/gateway/gateways/GATEWAY_ID/addons/ESTIMATION" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "period": "MONTHLY", "currency": "EUR" }'

GET/v1/gateway/insights/{gatewayId}/overview

Aperçu dashboard sur une fenêtre. gatewayId est passé dans le path et vérifié contre le scope du token ; l'addon INSIGHTS doit être actif (sinon 409). Inclut la comparaison avec la fenêtre précédente.

{
  "unique_visitors": 1432,
  "sessions": 1879,
  "page_views": 5421,
  "leads": 28,
  "conversion_rate": 0.0195,
  "hot_leads": 7,
  "urgent_leads": 2,
  "series": [
    { "date": "2026-05-01", "unique_visitors": 52, "sessions": 67, "page_views": 198, "leads": 1 }
  ]
}

PATCH/v1/gateway/notification-preferences

Mise à jour partielle des préférences. Chaque champ est optionnel : un champ omis ou null ne modifie pas la valeur en base. Les valeurs par défaut sont toutes à true (opt-out).

curl -X PATCH "https://api.ts-immo.org/v1/gateway/notification-preferences" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "sync": false }'

Codes d'erreur

Les erreurs suivent l'enveloppe standard partagée par toutes les APIs ts-services : un message lisible, un code machine, un timestamp et un détail optionnel.

{
  "message": "Human-readable message",
  "code": "ERROR_CODE",
  "timestamp": "2026-04-18T10:00:00Z",
  "detail": "Optional technical detail, may be null"
}